devmap 0.4.1__tar.gz → 0.4.2__tar.gz

devmap-0.4.2/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: devmap
+Version: 0.4.2
+Summary: Map your machine's dev environment and surface issues (PATH conflicts, ghost binaries, multi-version collisions). fastfetch-for-dev-tools. This PyPI package ships the real devmap CLI (a bundled JavaScript app launched via Node.js or Bun), so `pip install devmap && devmap` works standalone.
+Author: devmap contributors
+License: MIT
+Project-URL: Homepage, https://github.com/StevenLOL/devmap
+Project-URL: Repository, https://github.com/StevenLOL/devmap
+Keywords: devmap,devtools,environment,scanner,fastfetch,diagnostics,dev-environment,path-conflict,ghost-binary
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# devmap
+
+> **The environment-reliability insurance for AI agents.** Before an agent changes *your* machine, let it ask devmap one question: *"can this environment run my command cleanly right now?"* — and get a structured answer instead of a mid-run failure.
+
+`devmap` is the developer-focused spiritual successor to `fastfetch`: instead of only printing system specs, it scans the *development* surface of your machine — runtimes, package managers, IDEs, per-interpreter pip packages, conda/WSL/Docker environments, Visual Studio dev shells, project-local virtual environments, **mobile SDKs (Android / Flutter / Dart / NDK)**, and the **Windows pre-flight** state an AI agent dies on — and produces a single machine-readable manifest plus an actionable issue list. As an MCP server it plugs straight into Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy, so the agent calls `preflight` *before* it ever shells out a command.
+
+## Install
+
+This PyPI package ships the **real devmap CLI**. The wheel embeds the compiled devmap app (`devmap/_devmap.mjs`) and launches it through **Node.js** (or **Bun**, if present) — so `pip install devmap && devmap` works standalone, with no npm install and no build step:
+
+```bash
+pip install devmap
+devmap --version
+```
+
+Requirements at runtime: **Node.js (or Bun)** on `PATH`. Python is only the installer/launcher wrapper — the package has zero Python dependencies.
+
+> The npm channel (`npm i -g devmap`) ships the same bundle and is equally valid. Pick whichever package manager you already use.
+
+## Why devmap (and why it is built for agents)
+
+- **AI agents break on dirty environments, not on missing specs.** An agent that shells out a `flutter build` or `pip install` on a machine with a Constrained-Language-Mode PowerShell, a Restricted execution policy, a GBK codepage, or an unset `ANDROID_HOME` fails mid-run. `devmap --mcp` exposes a **`preflight`** tool the agent calls *first* — it returns `ok / blockers / warnings` plus the exact Windows and mobile-SDK constraints, so the agent fixes (or asks the user to fix) them up front.
+- **The agent stays in control.** devmap is a read-only oracle. It never modifies your environment — it reports, and the agent decides. No hidden mutations, no "helpful" auto-fixes.
+
+## Features
+
+- **One-command full scan** of the dev environment (runtimes, package managers, IDEs, environment layers, mobile SDKs, and Windows pre-flight).
+- **PATH conflict graph**: detects multi-version tools, shadowed binaries, and ghost/broken symlinks (e.g. Windows App Execution Aliases that look broken but aren't). This is devmap's original wedge — **14 source-available rivals all lack it**.
+- **Off-PATH awareness**: reports installed-but-not-on-PATH tools, while correctly treating version-manager environments (conda envs, nvm versions) as by-design off-PATH.
+- **Mobile SDK moat (exclusive)**: Android SDK (`ANDROID_HOME`/`sdkmanager`/`adb`), Flutter (version + channel + bundled Dart), standalone Dart, and NDK — flags `ANDROID_HOME` unset while tools are on PATH, dev/beta Flutter channels, and multiple NDK versions silently shadowing each other. No competitor scans this.
+- **Windows pre-flight moat (exclusive)**: six checks an agent dies on — PowerShell execution policy, Constrained Language Mode (error), console code page, schannel cert-revocation, App Execution Aliases shadowing real `python`/`curl`, and the safe-delete shim that makes deletions fail closed.
+- **MCP server**: `devmap --mcp` speaks MCP over stdio and exposes `scan_environment`, `query_tool`, and `preflight`.
+- **Security layer (opt-in)**: `--audit-deps` detects and invokes your installed SCA tools (OSV-Scanner / pip-audit / govulncheck / Trivy), parses their JSON, and merges findings into one view; `--scan-secrets` adds a fully offline hardcoded-credential scan over a curated allowlist of `$HOME`/project config files, with every matched value redacted. devmap is a *scanner/orchestrator*, **not** a CVE database.
+- **Health layer**: converges official self-checks into one view, **per environment**. Offline by default: `pip check` runs for **every** Python interpreter, and `conda doctor` runs for **every** conda env. With `--health-network`, `npm doctor` / `rustup check` are added. Missing/offline probes degrade gracefully to `info` (skipped). Passing checks are summarized as `✓ N checks passed` — only `warn`/`error` surface under `issues (N)`.
+- **Share card**: `devmap --card` prints a screenshot-friendly ASCII/Markdown card; `devmap --share` writes it to `./devmap-card.md`.
+- **Three sub-commands**: `scan` (the fact source), `query` (ask the manifest), `devdiff` (compare two manifests — environment drift / cross-machine consistency).
+- **Zero external dependencies.** Pure TypeScript, shipped prebuilt.
+
+## Usage
+
+`devmap` **defaults to `scan`** — you can drop the `scan` word entirely.
+
+```bash
+devmap                          # pretty-print to terminal, write ~/.devmap/devmap.json
+devmap --json                   # machine-readable JSON (devmap.json schema) to stdout
+devmap --report                 # full markdown report
+devmap --scan-root C:\src       # also scan project-local envs under a root
+devmap --wsl-deep               # also wake stopped WSL distros and probe their tools (slower)
+devmap --outdated               # hit PyPI to list upgradable pip/conda packages (needs network)
+devmap --ci                     # exit code 1 if any error-severity issue is found
+devmap --card                   # print a screenshot-friendly share card
+devmap --share                  # write the share card to ./devmap-card.md
+```
+
+Key `scan` flags:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit machine-readable JSON (the `devmap.json` schema) to stdout. |
+| `--report` | Emit a full markdown report. |
+| `--card` | Print a screenshot-friendly share card (pure ASCII/Markdown — never mojibakes on GBK consoles). |
+| `--share` | Write the share card to `./devmap-card.md`. |
+| `--no-manifest` | Do not persist the manifest to disk. |
+| `--manifest <path>` | Read/write the manifest at a custom path (default `~/.devmap/devmap.json`). |
+| `--disable <r1,r2>` | Disable check rules by ID prefix (e.g. `path.duplicate`, `pip.outdated`, `security`). |
+| `--shell <list>` | Which shell views to reconstruct: `current\|powershell\|gitbash\|wsl\|all`. |
+| `--scan-root <dir>` | Root(s) to scan for project-local environments (comma-separated). Default: cwd. |
+| `--outdated` | Network check for upgradable pip/conda packages (off by default). |
+| `--wsl-deep` | Probe inside stopped WSL distros (off by default to avoid waking them). |
+| `--audit-deps` | Invoke installed SCA tools and merge CVE findings into the report (opt-in, uses network). |
+| `--scan-secrets` | Scan a curated allowlist of credential files for hardcoded secrets (opt-in, offline, values redacted). |
+| `--health-network` | Also run network health probes (`npm doctor` / `rustup check`). |
+| `--mcp` | Run as an MCP server over stdio instead of scanning. |
+| `--ci` | Exit non-zero on any error-severity issue. |
+| `--quiet` | Suppress the live scan progress feedback (for scripts/CI). |
+| `--bom` | Prefix output with a UTF-8 BOM so Notepad-like viewers render it correctly (stdout redirect/pipe only). |
+
+### `--mcp` — run as an MCP server
+
+```bash
+devmap --mcp
+```
+
+Register it with any MCP-capable agent (Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy / VS Code):
+
+```jsonc
+{
+  "mcpServers": {
+    "devmap": { "command": "devmap", "args": ["--mcp"] }
+  }
+}
+```
+
+Three tools are exposed:
+
+| Tool | Purpose |
+|------|---------|
+| `preflight` | **Call this first.** Returns `ok / blockers / warnings` plus the environment constraints (PowerShell language mode, execution policy, codepage, schannel revocation, Android/Flutter state) that would break the command you are about to run. |
+| `scan_environment` | Run a full scan and return the manifest. |
+| `query_tool` | Ask an existing manifest about a specific tool (version, path, on-PATH state). |
+
+```jsonc
+// agent -> devmap (MCP)
+{ "tool": "preflight", "arguments": { "target": "powershell", "forAgent": true } }
+// -> { "ok": false, "blockers": ["win.langmode"], "warnings": ["win.execpolicy", "win.schannel"],
+//      "languageMode": "ConstrainedLanguage", "codepage": 936, "schannelRevoke": true, ... }
+```
+
+`blockers` non-empty ⇒ fix first. `ok: true` ⇒ the agent can proceed.
+
+### `query` — ask the manifest
+
+```bash
+devmap query                       # everything
+devmap query node                 # tools whose id contains "node"
+devmap query runtime.node         # dot-form category.tool selector (runtime / pkg / ide)
+devmap query --issues             # only issues
+devmap query --conflicts          # only conflicts (multiVersion / path / ghost)
+devmap query --off-path           # only off-PATH installs
+devmap query --kind runtime       # filter by category
+devmap query --where conda        # filter by install path substring
+```
+
+### `devdiff` — compare two manifests
+
+```bash
+devmap devdiff                    # stored manifest  vs  current live scan
+devmap devdiff <file>             # stored/before    vs  <file>
+devmap devdiff <a> <b>            # compare two manifest files
+```
+
+Reports added/removed installs, version changes, and issues added/resolved.
+
+## Output
+
+- The default `scan` writes the manifest to **`~/.devmap/devmap.json`** (pure UTF-8, no BOM — directly parseable by Bun/Node/Python/jq).
+- Use `query` / `devdiff` against a stored manifest without re-scanning.
+
+### Encoding note
+
+Output is UTF-8. Windows Notepad may mojibake a BOM-less UTF-8 file — open it in VS Code, Windows Terminal, or an IDE, or add `--bom` when redirecting. When reading a BOM-prefixed file in Python, use `open(p, encoding="utf-8-sig")`.
+
+## Repository
+
+https://github.com/StevenLOL/devmap
+
+## License
+
+[MIT](https://github.com/StevenLOL/devmap/blob/main/LICENSE)

devmap-0.4.2/README.md

@@ -0,0 +1,149 @@
+# devmap
+
+> **The environment-reliability insurance for AI agents.** Before an agent changes *your* machine, let it ask devmap one question: *"can this environment run my command cleanly right now?"* — and get a structured answer instead of a mid-run failure.
+
+`devmap` is the developer-focused spiritual successor to `fastfetch`: instead of only printing system specs, it scans the *development* surface of your machine — runtimes, package managers, IDEs, per-interpreter pip packages, conda/WSL/Docker environments, Visual Studio dev shells, project-local virtual environments, **mobile SDKs (Android / Flutter / Dart / NDK)**, and the **Windows pre-flight** state an AI agent dies on — and produces a single machine-readable manifest plus an actionable issue list. As an MCP server it plugs straight into Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy, so the agent calls `preflight` *before* it ever shells out a command.
+
+## Install
+
+This PyPI package ships the **real devmap CLI**. The wheel embeds the compiled devmap app (`devmap/_devmap.mjs`) and launches it through **Node.js** (or **Bun**, if present) — so `pip install devmap && devmap` works standalone, with no npm install and no build step:
+
+```bash
+pip install devmap
+devmap --version
+```
+
+Requirements at runtime: **Node.js (or Bun)** on `PATH`. Python is only the installer/launcher wrapper — the package has zero Python dependencies.
+
+> The npm channel (`npm i -g devmap`) ships the same bundle and is equally valid. Pick whichever package manager you already use.
+
+## Why devmap (and why it is built for agents)
+
+- **AI agents break on dirty environments, not on missing specs.** An agent that shells out a `flutter build` or `pip install` on a machine with a Constrained-Language-Mode PowerShell, a Restricted execution policy, a GBK codepage, or an unset `ANDROID_HOME` fails mid-run. `devmap --mcp` exposes a **`preflight`** tool the agent calls *first* — it returns `ok / blockers / warnings` plus the exact Windows and mobile-SDK constraints, so the agent fixes (or asks the user to fix) them up front.
+- **The agent stays in control.** devmap is a read-only oracle. It never modifies your environment — it reports, and the agent decides. No hidden mutations, no "helpful" auto-fixes.
+
+## Features
+
+- **One-command full scan** of the dev environment (runtimes, package managers, IDEs, environment layers, mobile SDKs, and Windows pre-flight).
+- **PATH conflict graph**: detects multi-version tools, shadowed binaries, and ghost/broken symlinks (e.g. Windows App Execution Aliases that look broken but aren't). This is devmap's original wedge — **14 source-available rivals all lack it**.
+- **Off-PATH awareness**: reports installed-but-not-on-PATH tools, while correctly treating version-manager environments (conda envs, nvm versions) as by-design off-PATH.
+- **Mobile SDK moat (exclusive)**: Android SDK (`ANDROID_HOME`/`sdkmanager`/`adb`), Flutter (version + channel + bundled Dart), standalone Dart, and NDK — flags `ANDROID_HOME` unset while tools are on PATH, dev/beta Flutter channels, and multiple NDK versions silently shadowing each other. No competitor scans this.
+- **Windows pre-flight moat (exclusive)**: six checks an agent dies on — PowerShell execution policy, Constrained Language Mode (error), console code page, schannel cert-revocation, App Execution Aliases shadowing real `python`/`curl`, and the safe-delete shim that makes deletions fail closed.
+- **MCP server**: `devmap --mcp` speaks MCP over stdio and exposes `scan_environment`, `query_tool`, and `preflight`.
+- **Security layer (opt-in)**: `--audit-deps` detects and invokes your installed SCA tools (OSV-Scanner / pip-audit / govulncheck / Trivy), parses their JSON, and merges findings into one view; `--scan-secrets` adds a fully offline hardcoded-credential scan over a curated allowlist of `$HOME`/project config files, with every matched value redacted. devmap is a *scanner/orchestrator*, **not** a CVE database.
+- **Health layer**: converges official self-checks into one view, **per environment**. Offline by default: `pip check` runs for **every** Python interpreter, and `conda doctor` runs for **every** conda env. With `--health-network`, `npm doctor` / `rustup check` are added. Missing/offline probes degrade gracefully to `info` (skipped). Passing checks are summarized as `✓ N checks passed` — only `warn`/`error` surface under `issues (N)`.
+- **Share card**: `devmap --card` prints a screenshot-friendly ASCII/Markdown card; `devmap --share` writes it to `./devmap-card.md`.
+- **Three sub-commands**: `scan` (the fact source), `query` (ask the manifest), `devdiff` (compare two manifests — environment drift / cross-machine consistency).
+- **Zero external dependencies.** Pure TypeScript, shipped prebuilt.
+
+## Usage
+
+`devmap` **defaults to `scan`** — you can drop the `scan` word entirely.
+
+```bash
+devmap                          # pretty-print to terminal, write ~/.devmap/devmap.json
+devmap --json                   # machine-readable JSON (devmap.json schema) to stdout
+devmap --report                 # full markdown report
+devmap --scan-root C:\src       # also scan project-local envs under a root
+devmap --wsl-deep               # also wake stopped WSL distros and probe their tools (slower)
+devmap --outdated               # hit PyPI to list upgradable pip/conda packages (needs network)
+devmap --ci                     # exit code 1 if any error-severity issue is found
+devmap --card                   # print a screenshot-friendly share card
+devmap --share                  # write the share card to ./devmap-card.md
+```
+
+Key `scan` flags:
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit machine-readable JSON (the `devmap.json` schema) to stdout. |
+| `--report` | Emit a full markdown report. |
+| `--card` | Print a screenshot-friendly share card (pure ASCII/Markdown — never mojibakes on GBK consoles). |
+| `--share` | Write the share card to `./devmap-card.md`. |
+| `--no-manifest` | Do not persist the manifest to disk. |
+| `--manifest <path>` | Read/write the manifest at a custom path (default `~/.devmap/devmap.json`). |
+| `--disable <r1,r2>` | Disable check rules by ID prefix (e.g. `path.duplicate`, `pip.outdated`, `security`). |
+| `--shell <list>` | Which shell views to reconstruct: `current\|powershell\|gitbash\|wsl\|all`. |
+| `--scan-root <dir>` | Root(s) to scan for project-local environments (comma-separated). Default: cwd. |
+| `--outdated` | Network check for upgradable pip/conda packages (off by default). |
+| `--wsl-deep` | Probe inside stopped WSL distros (off by default to avoid waking them). |
+| `--audit-deps` | Invoke installed SCA tools and merge CVE findings into the report (opt-in, uses network). |
+| `--scan-secrets` | Scan a curated allowlist of credential files for hardcoded secrets (opt-in, offline, values redacted). |
+| `--health-network` | Also run network health probes (`npm doctor` / `rustup check`). |
+| `--mcp` | Run as an MCP server over stdio instead of scanning. |
+| `--ci` | Exit non-zero on any error-severity issue. |
+| `--quiet` | Suppress the live scan progress feedback (for scripts/CI). |
+| `--bom` | Prefix output with a UTF-8 BOM so Notepad-like viewers render it correctly (stdout redirect/pipe only). |
+
+### `--mcp` — run as an MCP server
+
+```bash
+devmap --mcp
+```
+
+Register it with any MCP-capable agent (Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy / VS Code):
+
+```jsonc
+{
+  "mcpServers": {
+    "devmap": { "command": "devmap", "args": ["--mcp"] }
+  }
+}
+```
+
+Three tools are exposed:
+
+| Tool | Purpose |
+|------|---------|
+| `preflight` | **Call this first.** Returns `ok / blockers / warnings` plus the environment constraints (PowerShell language mode, execution policy, codepage, schannel revocation, Android/Flutter state) that would break the command you are about to run. |
+| `scan_environment` | Run a full scan and return the manifest. |
+| `query_tool` | Ask an existing manifest about a specific tool (version, path, on-PATH state). |
+
+```jsonc
+// agent -> devmap (MCP)
+{ "tool": "preflight", "arguments": { "target": "powershell", "forAgent": true } }
+// -> { "ok": false, "blockers": ["win.langmode"], "warnings": ["win.execpolicy", "win.schannel"],
+//      "languageMode": "ConstrainedLanguage", "codepage": 936, "schannelRevoke": true, ... }
+```
+
+`blockers` non-empty ⇒ fix first. `ok: true` ⇒ the agent can proceed.
+
+### `query` — ask the manifest
+
+```bash
+devmap query                       # everything
+devmap query node                 # tools whose id contains "node"
+devmap query runtime.node         # dot-form category.tool selector (runtime / pkg / ide)
+devmap query --issues             # only issues
+devmap query --conflicts          # only conflicts (multiVersion / path / ghost)
+devmap query --off-path           # only off-PATH installs
+devmap query --kind runtime       # filter by category
+devmap query --where conda        # filter by install path substring
+```
+
+### `devdiff` — compare two manifests
+
+```bash
+devmap devdiff                    # stored manifest  vs  current live scan
+devmap devdiff <file>             # stored/before    vs  <file>
+devmap devdiff <a> <b>            # compare two manifest files
+```
+
+Reports added/removed installs, version changes, and issues added/resolved.
+
+## Output
+
+- The default `scan` writes the manifest to **`~/.devmap/devmap.json`** (pure UTF-8, no BOM — directly parseable by Bun/Node/Python/jq).
+- Use `query` / `devdiff` against a stored manifest without re-scanning.
+
+### Encoding note
+
+Output is UTF-8. Windows Notepad may mojibake a BOM-less UTF-8 file — open it in VS Code, Windows Terminal, or an IDE, or add `--bom` when redirecting. When reading a BOM-prefixed file in Python, use `open(p, encoding="utf-8-sig")`.
+
+## Repository
+
+https://github.com/StevenLOL/devmap
+
+## License
+
+[MIT](https://github.com/StevenLOL/devmap/blob/main/LICENSE)

{devmap-0.4.1 → devmap-0.4.2}/devmap/__init__.py

@@ -14,7 +14,16 @@ import shutil
 import subprocess
 import sys
 
-__version__ = "0.2.5"
+try:  # single source of truth = installed wheel metadata (never hand-bumped)
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _pkg_version
+
+    try:
+        __version__ = _pkg_version("devmap")
+    except PackageNotFoundError:  # running from a source tree
+        __version__ = "0+unknown"
+except Exception:  # pragma: no cover - very old Python / frozen env
+    __version__ = "0+unknown"
 
 _BUNDLE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "_devmap.mjs")