feat(dx): codelens doctor command — env audit + auto-fix, exit codes 0/1/2 (closes #64 phase-1)

[Wolfvin]

Summary

Implements Phase 1 of issue #64 — codelens doctor command for environment audit + auto-fix.

doctor audits the local environment for everything CodeLens needs to run well, and reports a single-pass table of checks. It's the "why doesn't this work?" debugging tool — for users, for CI, and for the setup script.

Files

New:

• scripts/commands/doctor.py — full doctor command: 10 audit checks, --fix, --verbose, --format {text,json}, exit codes 0/1/2
• tests/test_doctor.py — 32 tests covering output schema, aggregation logic, version comparison, fix mode (mocked), CLI smoke, network-failure tolerance

Modified:

• scripts/codelens.py — dispatcher now (1) skips format_output when doctor already printed its text table, (2) propagates exit_code from doctor result; subparser --format no longer auto-added when a command defines its own
• tests/test_integration.py — EXPECTED_COMMAND_COUNT 67 → 68 (manual sentinel, by design not auto-synced)
• README.md, SKILL.md, SKILL-QUICK.md, pyproject.toml, skill.json, scripts/graph_model.py — auto-synced by python3 scripts/sync_command_count.py --apply to reflect 67 → 68

Audit checks (10 total)

1. Python version (≥ 3.8) — critical if too old
2. tree_sitter module — critical
3. All 6 tree-sitter grammars (html, css, js, ts, rust, python) — critical if any missing
4. yaml (PyYAML) — warning (optional)
5. watchdog — warning (optional, for file watching)
6. sqlite3 — critical (stdlib, used for persistent registry)
7. urllib — critical (stdlib, used for vuln-scan + upgrade)
8. git binary — warning (optional, for ownership)
9. .codelens/ writable — critical (creates dir + probe-write)
10. Latest CodeLens version vs GitHub Releases — warning (network failure tolerant, never critical)

Key design decisions

1. Exit codes 0/1/2 — ok → 0, warning → 1, critical → 2. CI pipelines can gate on doctor failures.
2. Network-failure tolerance — the latest-version check downgrades to warning (never critical) on network errors, so air-gapped CI doesn't fail doctor.
3. --fix is safe — only runs pip install --user for missing Python deps. Does NOT install system binaries (git, etc.). Single pip invocation for all missing packages (faster + one dependency-resolver pass).
4. --format json for CI — machine-readable schema with status, exit_code, checks[], fixes[], summary{ok,warning,critical,total}, platform{python,platform,machine,executable}.
5. --format text (default) is human-readable — ASCII symbols [OK]/[WARN]/[FAIL] so output is grep-friendly and works on Windows terminals.
6. Re-runs checks after --fix — the reported exit code reflects the post-fix state, so CI knows if the fix actually resolved the issues.
7. Local --format overrides global — doctor is the first command to define its own --format (with text choice); dispatcher was updated to respect command-specific --format instead of conflict-erroring.

Acceptance criteria

• codelens doctor correctly detects all missing dependencies
• codelens doctor --fix installs missing deps without error (mocked in tests)
• codelens doctor --format json produces valid JSON for CI
• codelens doctor --verbose adds detail lines
• Exit codes 0/1/2 propagate correctly
• sync_command_count.py --apply run — all docs reflect 68 commands
• EXPECTED_COMMAND_COUNT sentinel updated 67 → 68

(Phases 2–4 — codelens sessions, install.sh --dry-run/--self-test/--uninstall, codelens upgrade — are out of scope for this Phase 1 PR.)

Test results

• 32 new tests in tests/test_doctor.py — all pass
• tests/test_command_count.py + tests/test_integration.py::TestModuleStructure — all pass
• No regressions in existing test suite (verified 1239 passed, 15 skipped, 4 pre-existing upstream failures deselected)

Verified git apply cleanly against Wolfvin/CodeLens@main.

Closes #64 (phase-1).

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sonarqubecloud]

Quality Gate passed

Issues
9 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud