envdoctor

envdoctor

envdoctor checks whether this machine's environment matches what a repo says it needs. Point it at a repo directory and it runs a small set of deterministic checks, each one passing or failing with the fix named. It never runs code from the repo, and it never prints a secret value.

Install

Run it without installing:

npx @reneturcios/envdoctor doctor [path]

Or install it globally:

npm install -g @reneturcios/envdoctor

CLI

envdoctor doctor [path] [--json]
envdoctor mcp
envdoctor --version

• doctor [path] checks the repo at path (default: the current directory) and prints a human readable report. Add --json for the machine readable report.
• mcp starts the MCP server on stdio.
• --version prints the version.

Exit codes: 0 when the verdict is HEALTHY, 1 when the verdict is ISSUES, 2 for a usage error such as a target that does not exist, and 141 when the reader closed the output pipe early.

MCP

The MCP server exposes one tool:

• doctor_env takes a path argument, runs the same checks as the CLI, and returns the JSON report.

Checks

v0.1 runs five checks, in this order:

1. NODE-VERSION - Compares the running Node version (process.version) against the engines.node range in the target's package.json. Supported range syntax: >=, <=, >, <, =, caret ranges such as ^20.0.0, tilde ranges such as ~20.11.0, exact versions such as 20.11.0, x-ranges such as 20.x and 20.11.x, partial versions, and space separated combinations such as >=18 <21. A range outside that syntax is reported as an info finding with rule RANGE-UNSUPPORTED instead of a guess. When the target has no package.json, this check is skipped with an info finding with rule NO-PACKAGE-JSON, and the remaining checks still run.
2. GIT-PRESENT - Passes when git --version succeeds.
3. NPM-PRESENT - Passes when npm --version succeeds.
4. LOCKFILE - Passes when one of package-lock.json, yarn.lock, or pnpm-lock.yaml exists at the target (the report says which one). A missing lockfile is a medium finding with rule NO-LOCKFILE.
5. ENV-FILE - Only applies when .env.example exists at the target. If .env is missing, that is a medium finding with rule ENV-MISSING and the fix "copy .env.example to .env and fill values". If .env exists, the key names in .env.example are compared against the key names in .env, and each name missing from .env is a medium finding with rule ENV-KEYS-MISSING. When there is no .env.example, the check passes because no env file is required.

Every passed check is counted in counts.checksPassed and appears in the report findings as an info entry with rule CHECK-PASS, so the printed report lists every check that ran.

Env values are never read into output

This guarantee is plain: envdoctor compares key names only.

• Both .env.example and .env are parsed by reading only the text left of the first = on each line. That text is the key name.
• Everything from the first = onward is a value. Values are discarded at parse time. They are not stored, not returned, not logged, and not printed in any report, finding, summary, or error.
• Findings about env files name keys, never values. For example, an ENV-KEYS-MISSING finding says a key named in .env.example is missing from .env; it says nothing about any value.

Verdict rules

• HEALTHY - No medium or high findings. Passed checks, skipped checks with a stated reason, and info notes such as RANGE-UNSUPPORTED do not change this verdict.
• ISSUES - At least one medium or high finding exists.

The report counts are checksRun, checksPassed, checksFailed, checksWarned, and checksSkipped, plus a findings total broken down by severity.

Limits

• v0.1 checks Node, git, npm, and files only: the engines.node range, the two tool versions, the lockfile, and the env files described above.
• Ports, running services, databases, and network reachability are not checked in v0.1. Port and service checks are future work.
• Disk space is out of scope.
• Only the Node range syntax listed under NODE-VERSION is supported. Any other range syntax produces a RANGE-UNSUPPORTED info finding rather than a pass or fail.
• Nothing in the target repo is executed. The only commands envdoctor runs are git --version and npm --version.