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

README.md

@@ -2,12 +2,12 @@
 
 > **Before an AI writes a new class/id/function, CodeLens must be checked. This is not optional.**
 
-CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 67 CLI commands, an MCP server with 65 tools (50 static + 15 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
+CodeLens is an AI-native code intelligence platform that gives AI agents **full visibility** into a codebase before they write any code. It prevents collision, overwrite of existing logic, security vulnerabilities, and dead code through 68 CLI commands, an MCP server with 66 tools (54 static + 12 dynamic), AST-based taint analysis, live CVE/OSV scanning, a plugin system with OWASP Top 10 + Compliance rule packs, a true graph data model (nodes + edges) for structural code queries, and token-efficient `--format compact` output for high-volume agent workflows (issue #17).
 
 ## Features
 
-- **67 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
-- **MCP Server (65 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 50 statically-defined tools + 15 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
+- **68 CLI Commands** — From basic scan/query to AST taint analysis, CVE scanning, plugin management, auto-fix, dashboards, CI/CD quality gates, and `graph-schema` for cheap graph-shape introspection
+- **MCP Server (66 Tools)** — Native AI agent integration via Model Context Protocol (JSON-RPC over stdio), 54 statically-defined tools + 12 dynamically discovered, every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`)
 - **Token-Efficient Compact Output (v8.2, issue #17)** — `--format compact` produces single-char-key JSON with abbreviated types, omitted null fields, and relative paths — ~50% smaller than `json` on real trace output. Combined with `--limit`/`--offset` pagination, 5 structural queries now cost <5k tokens (down from 30-80k)
 - **AST Taint Engine** — Tree-sitter based taint analysis with return-value propagation, scope hierarchy, and branch condition refinement
 - **Live CVE/OSV Scanning** — Real-time vulnerability data from OSV.dev API with SQLite cache, 9 ecosystems (PyPI, npm, crates.io, Go, Maven, NuGet, RubyGems, Pub, Hex)
@@ -225,8 +225,8 @@ codelens/
 │   ├── changelog.md               # Older changelog (per-version highlights)
 │   └── agent-integration.md       # AI agent integration guide
 ├── scripts/
-│   ├── codelens.py                # CLI entry point (67 commands registered)
-│   ├── mcp_server.py              # MCP JSON-RPC server (65 tools)
+│   ├── codelens.py                # CLI entry point (68 commands registered)
+│   ├── mcp_server.py              # MCP JSON-RPC server (66 tools)
 │   ├── registry.py                # Registry read/write/build
 │   ├── persistent_registry.py     # SQLite persistent storage (WAL mode)
 │   ├── base_parser.py             # Base tree-sitter parser

SKILL-QUICK.md

@@ -114,7 +114,7 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 | "Cross-file taint" | `dataflow` | `taint` (taint is single-file, AST-deep) |
 | "Auto-fix issues" | `fix` | `check` (check just gates, doesn't fix) |
 
-## All 67 Commands
+## All 68 Commands
 
 ### Setup & Lifecycle (8+)
 `init` · `scan [--incremental] [--max-files N] [--full]` · `registry-validate` · `detect` · `watch [--debounce SECS] [--git-mode] [--interval SECS]` · `git-status` · `migrate` · `serve` · `lsp-status` (issue #33: `codelens --lsp-status` top-level flag is an alias of `codelens lsp-status` — both delegate to `hybrid_engine.get_lsp_status()` and return the identical payload)
@@ -146,19 +146,19 @@ $CLI list --limit 5 --offset 10 --format compact            # → paginated + co
 ### Tooling (1)
 `plugin <install|list|search|update|info|validate>`
 
-**Total: 67 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
+**Total: 68 commands** (auto-registered via `commands/__init__.py`; rerun `python3 scripts/sync_command_count.py --apply` after adding/removing a command)
 
-## MCP Server (65 Tools)
+## MCP Server (66 Tools)
 
 Start the MCP server for AI agent integration:
 
 ```bash
 python3 scripts/codelens.py serve
 ```
 
-Exposes 65 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
+Exposes 66 tools as `codelens_<command>` (e.g., `codelens_query`, `codelens_taint`, `codelens_graph_schema`, `codelens_architecture`, `codelens_resolve_types`, `codelens_git_status`):
 - 50 statically-defined tools (full JSON schemas in `mcp_server.py`)
-- 15 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
+- 12 dynamically-discovered tools (auto-discovered from `COMMAND_REGISTRY`; long-running `watch` and `serve` are excluded)
 - Every tool accepts a `format` parameter (`json`/`markdown`/`ai`/`sarif`/`compact`). Use `format: "compact"` for token-efficient responses (~50% smaller than `json`).
 - `watch` and `serve` itself are excluded (long-running)
 

SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: codelens
 description: >
-  CodeLens — AI-Native Code Intelligence. 67 commands for AI-powered code analysis,
+  CodeLens — AI-Native Code Intelligence. 68 commands for AI-powered code analysis,
   security auditing, quality scoring, AST-based taint analysis, live CVE scanning,
   and pre-write safety checks. Supports 28+ languages with tree-sitter + regex
-  fallback parsing. MCP server exposes 65 tools for AI agent integration.
+  fallback parsing. MCP server exposes 66 tools for AI agent integration.
   For quick command reference with validated output schemas, see SKILL-QUICK.md.
   For version history, see CHANGELOG.md.
 ---

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "codelens"
 version = "8.2.0"
-description = "Live Codebase Reference Intelligence — 67 commands for AI-powered code analysis, security auditing, and quality scoring"
+description = "Live Codebase Reference Intelligence — 68 commands for AI-powered code analysis, security auditing, and quality scoring"
 readme = "README.md"
 license = {text = "MIT"}
 requires-python = ">=3.8"

scripts/codelens.py

@@ -877,9 +877,14 @@ def main():
                 existing_dests.add(action.dest)
         _existing_subparser_args[cmd_name] = existing_dests
 
-        # Add --format to each subparser (safe: no command defines its own --format)
-        sub.add_argument("--format", "-f", choices=["json", "markdown", "ai", "sarif", "compact"], default=None,
-                         help="Output format: json, markdown, ai (normalized schema), sarif (GitHub/VS Code), or compact (token-efficient single-char keys)")
+        # Add --format to each subparser (UNLESS the command defines its own).
+        # Issue #64: ``doctor`` defines its own ``--format`` with choices
+        # ``["text", "json"]`` because its default human-readable output is
+        # a text table, not JSON. Skipping the global add here lets that
+        # command-specific format work without an argparse conflict.
+        if "format" not in existing_dests:
+            sub.add_argument("--format", "-f", choices=["json", "markdown", "ai", "sarif", "compact"], default=None,
+                             help="Output format: json, markdown, ai (normalized schema), sarif (GitHub/VS Code), or compact (token-efficient single-char keys)")
 
         # Add AI-optimized flags to subparser ONLY if the command doesn't already have them
         if "top" not in existing_dests:
@@ -1272,12 +1277,26 @@ def main():
                 logger.warning(f"Suppression processing failed: {e}", exc_info=True)
 
         # ─── Format and print output ──
-        print(format_output(result, args.format, format_command, workspace))
-
-        # ─── Exit code for check command (CI quality gate) ──
+        # doctor (issue #64) prints its own human-readable text table when
+        # ``--format text`` is used, and signals via ``_doctor_printed_text``
+        # so the dispatcher skips the generic JSON formatter (which would
+        # otherwise dump the result dict a second time). In ``--format json``
+        # mode doctor does NOT print itself, and the normal formatter handles
+        # the JSON serialization.
+        if not (args.command == "doctor" and isinstance(result, dict)
+                and result.get("_doctor_printed_text")):
+            print(format_output(result, args.format, format_command, workspace))
+
+        # ─── Exit codes for CI-quality-gate commands ──
         if args.command == "check" and isinstance(result, dict):
             if result.get("gate") == "failed":
                 sys.exit(1)
+        # doctor (issue #64): exit 0=ok / 1=warning / 2=critical.
+        # The exit code lets CI pipelines gate on doctor failures.
+        if args.command == "doctor" and isinstance(result, dict):
+            exit_code = result.get("exit_code", 0)
+            if exit_code:
+                sys.exit(exit_code)
 
     except FileNotFoundError as e:
         error_result = {