devmap

A source-of-truth scanner and governance layer for your machine's development environment. One command maps the whole dev setup, draws the PATH-conflict graph, and surfaces ghost binaries and multi-version collisions.

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, and project-local virtual environments — and produces a single machine-readable manifest plus an actionable issue list.

Install

This PyPI package ships the real devmap CLI. It bundles the compiled devmap app and launches it via Node.js (or Bun, if present), so it works standalone — no need to install from npm or build from source:

pip install devmap
devmap scan

Requirements at runtime: a Node.js (or Bun) runtime available on PATH. Python itself is only used as the installer/launcher wrapper.

Features

• One-command full scan of the dev environment (runtimes, package managers, IDEs, and the environment layers below).
• 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).
• 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.
• Environment layers: vcpkg packages, per-python pip packages (incl. upgradable), apt packages (Linux), conda environments, Docker (binary + daemon + images/containers), WSL distros, Visual Studio dev shells, and project-local environments (.venv, node_modules).
• Dependency auditing (optional): with --audit-deps, devmap detects and invokes installed SCA tools (osv-scanner, govulncheck, pip-audit, Trivy), parses their JSON, and merges results into a unified view. devmap is a scanner/orchestrator, not a CVE database — for authoritative vulnerability data, use those tools directly.
• Health layer: converges official self-checks into one view — pip check (broken dependency requirements, offline by default) and, with --health-network, npm doctor / rustup check. Unavailable or offline probes degrade gracefully to info.
• Three sub-commands: scan (the fact source), query (ask the manifest), devdiff (compare two manifests — environment drift / cross-machine consistency).
• Zero Python dependencies. The bundled app is pure TypeScript compiled to JavaScript.

Usage

devmap scan                        # pretty-print to terminal, write ~/.devmap/devmap.json
devmap scan --json                # machine-readable JSON (devmap.json schema) to stdout
devmap scan --report              # full markdown report
devmap scan --scan-root C:\src     # also scan project-local envs under a root (comma-separated for many)
devmap scan --wsl-deep            # also wake stopped WSL distros and probe their tools (slower)
devmap scan --outdated            # hit PyPI to list upgradable pip/conda packages (slower, needs network)
devmap scan --ci                  # exit code 1 if any error-severity issue is found
devmap scan --audit-deps          # invoke installed SCA tools and merge CVE findings

Key scan flags:

| Flag | Description | |------|-------------| | --json | Emit machine-readable JSON (the devmap.json schema) to stdout. | | --report | Emit a full markdown report. | | --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). | | --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. | | --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). |

query — ask the manifest

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

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.

Repository

https://github.com/StevenLOL/devmap

License

MIT