MOO-72 Commit 5: dependency and runtime health checks

[OwenTanzer]

Summary

• /readyz gains cacheStorage/nodeRuntime (readiness-gating) and pythonRuntime/pythonTreeSitter/githubReachable (feature-specific, non-gating) checks, alongside the existing pyan3/codeVisualizer checks — all normalized to one {ok, detail, version, checkedAt} status shape.
• cacheStorage round-trips against a dedicated, isolated GraphCache instance, never the live request-serving cache — a naive self-test against production cache state would perturb real LRU order, consume capacity, and risk a key collision on every /readyz hit.
• nodeRuntime enforces the actual declared range in package.json's engines.node (^20.19.0 || >=22.12.0) via a small, pure, unit-tested isSupportedNodeVersion(version) helper — not just a bare major-version floor, which would wrongly accept 20.0.0/21.x/22.0.0.
• pyan3/pythonRuntime/githubReachable are periodically re-verified, folded into the existing 5-minute metrics-summary interval (one fewer new timer) via a new, independently-unit-testable refreshDependencyStatuses() (server/lib/dependency-status.js), reentrancy-guarded so an overlapping tick is skipped rather than run concurrently. codeVisualizer stays startup-only — its parser-init memoization lives inside the vendored, commit-pinned @codevisualizer/core package, not something this codebase controls or should patch just to add live re-verification.
• pythonTreeSitter surfaces the existing PYTHON_TREE_SITTER_CAPABLE constant (the repository layer's own, separate Python-grammar probe) as its own readiness entry — a second, independent tree-sitter dependency from CodeVisualizer's that a first plan draft missed.
• graphvizDot reports {applicable: false} (not ok: true) — pyan3 emits DOT text directly, parsed via the ts-graphviz JS library; no external graphviz/dot binary is ever invoked.
• Sensitive detail/version/checkedAt fields are only included when the request carries the same Authorization: Bearer <AUTH_TOKEN> used for /api/* — an unauthenticated /readyz only ever sees ok/gatesReadiness.
• New verifyGithubReachable (github-analyzer-bridge.js) checks credential validity/reachability via GET /rate_limit (doesn't consume the caller's own rate-limit quota), deliberately independent of the shared, per-request-mutable GitHub.token singleton to avoid a background-check-races-real-request hazard. Injectable fetchImpl/apiBase for hermetic unit testing.
• New verifyPythonRuntime/recheckPyan3Available (pyan3Adapter.js) — separate from pyan3's own pinned-version check per the checklist's two distinct bullets, and a production-facing (not test-only-named) re-check for the periodic refresh.

Test plan

• npm test — 654/654 passing (baseline 623 + 31 new)
• tests/dependency-status.test.mjs (new) — proves one failing check (bad Python binary, bad GitHub token) never affects the others, and refreshDependencyStatuses never rejects as a whole.
• tests/server-health.test.mjs — extended: cache-storage-never-touches-the-live-cache (asserts a real live GraphCache's size/bytes/entry are completely unchanged after hitting /readyz), Node version boundary cases, auth-gated detail presence/absence, every new check's shape.
• tests/server-github-bridge.test.mjs — verifyGithubReachable against a mocked fetchImpl: 200, 401, non-401 non-2xx, network-error, abort, and header-shape assertions.
• tests/pyan3-adapter.test.mjs — recheckPyan3Available genuinely re-runs (forces a failure, then recovers against the real binary, not a stale memoized rejection); verifyPythonRuntime against both a real interpreter and a missing one.
• Ran the real end-to-end smoke test (tests/server-smoke.mjs) against the actual server process, the real pinned pyan3, and a real GitHub token — all 22 steps pass, including new assertions that the real /readyz response has every new check ok:true, graphvizDot.applicable:false, and that detail/version are absent unauthenticated and present authenticated.

🤖 Generated with Claude Code

[linear-code]

MOO-72

[OwenTanzer]

One runtime-health mismatch to address.

[OwenTanzer]

[P2] Reject non-Python-3 runtimes

This reports any parseable Python X.Y.Z output as healthy, so an operator-configured Python 2 executable returns pythonRuntime.ok: true. The adapter's existing contract requires a valid Python 3 interpreter (and the setup scripts prefer python3), so /readyz can give a misleading runtime-health signal while analysis cannot run. Please require major version 3 here and cover the Python 2 output case.

[OwenTanzer]

Fixed. verifyPythonRuntime's parse/gate logic is extracted into a pure evaluatePythonVersionOutput({stdout,stderr}) helper (server/lib/pyan3Adapter.js) that now checks the parsed major version is exactly 3, rejecting Python 2 (and any other major) with an actionable detail ("found Python X.Y.Z, but a Python 3 interpreter is required") while still reporting the detected version so an operator can see what's actually installed. Verified with real Python 2 and Python 3 --version output shapes (stderr for 2.x, stdout for 3.x, matching the real interpreters' actual behavior) rather than trying to spawn a fake Python 2 binary -- a .bat-based stand-in turned out to be unreliable on Windows (execFile rejects it without shell:true, which this codebase deliberately never sets for security). Full suite: 658/658.