Metadata-Version: 2.4
Name: devmap
Version: 0.4.3
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. The server targets **MCP `2026-07-28`** — stateless core (`server/discover`, no handshake required), tool `annotations` (`readOnlyHint`), JSON Schema `outputSchema` + `structuredContent` results, and cacheable `tools/list` — while still answering the legacy `initialize` handshake for older clients.

| 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)
