@vantageos/mcp-doctor 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -3,6 +3,74 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 0.3.1 — 2026-10-04
+
+### Fixed
+- **`npm test` on a clean clone failed 3 of 341.** `tests/bin-entrypoint.test.ts`
+  symlinks to `dist/doctor.js` and invokes it — deliberately, because the symlink is
+  the trigger for the defect those cases cover — but it never ensured the build
+  existed. A contributor cloning the repo and running the suite got
+  `Cannot find module .../dist/doctor.js` three times, on `main`, with nothing saying
+  a build was required first.
+  Fixed with `pretest: npm run build`, following the convention `prepack` and
+  `prepublishOnly` already use in this manifest rather than inventing a mechanism.
+- **D9 no longer throws when no `package.json` sits above the scanned root.** It
+  returns `could-not-judge` in band, the run completes the remaining detectors, and
+  the table prints. Previously the throw reached the consumer as exit 1 with a stack
+  trace — exit 1 being this tool's code for *a violation*, so a crash was
+  indistinguishable from a finding.
+
+### Note on why 0.3.0 shipped with the test defect
+Every environment where the work happens already has `dist/` — so the test passed for
+everyone who wrote it, and the one gated path (`prepublishOnly`, which runs
+`build && test`) was the one path that could not expose it. A test depending on an
+unstated prior step cannot fail for its author.
+
+---
+
+## 0.3.0 — 2026-10-04
+
+The documented invocation never ran. Through `node_modules/.bin/mcp-doctor` this
+tool printed **nothing** and exited **0** — for every target, since the bin was
+published. Every station that ran `npx mcp-doctor <tree>` and saw no output read a
+pass that was never computed.
+
+### READ THIS BEFORE UPGRADING
+
+**A CI job that was passing may now fail, and that is the fix working.** If you
+wired `npx mcp-doctor` into a pipeline and it has been green, it was green because
+nothing ran. On a real target this tool has findings to report. Budget for a first
+red run.
+
+### Fixed
+- **The bin is a symlink, and the entrypoint guard compared raw paths.** npm installs
+  `bin` as a symlink, so `process.argv[1]` is the link path while `import.meta.url`
+  is the resolved real path; compared directly they never match and `main()` never
+  ran. Both sides now resolve through `realpathSync`, each side guarded: a path that
+  cannot be resolved answers "do not run" rather than either running on an ordinary
+  library import or failing silently.
+  Measured on the published 0.2.0 before the fix — `./node_modules/.bin/mcp-doctor t`
+  exit 0 / 0 bytes against `node .../dist/doctor.js t` exit 2 / 6308 bytes.
+- **`--version`, `--help` and `-V` were silent for the same reason** and now answer.
+  The version is READ from the shipped manifest rather than compiled in, so it cannot
+  drift from the binary.
+- **The usage line named a development command no consumer can type**
+  (`tsx src/doctor.ts`). It now names `mcp-doctor` and lists the exit codes.
+
+### Added
+- **D16 is judged at runtime, not only statically.** Health-route census plus a dynamic
+  mode: the version a server actually SERVES on its pre-auth `initialize` handshake is
+  read from `serverInfo.version` and compared against `package.json`. A served version
+  that drifts from the canonical one is now a finding rather than invisible.
+- A static D16 verdict says out loud which mode produced it (`[static read]` prefix), so
+  a reader can tell an observation from a fallback.
+
+### Changed — observable contract
+- D16's static verdict strings carry the `[static read]` prefix. Anything parsing that
+  text rather than the `state` field must be updated.
+
+---
+
 ## 0.2.0 — 2026-08-16
 
 The engine gains a live-session contract and an honest exit code; a second

package/README.md

@@ -1,13 +1,17 @@
 # @vantageos/mcp-doctor
 
-Static **MCP conformance checker**. Point it at an MCP server source tree and it emits a
-**conformance-diff table** against the MCP **2026-07-28** standard — one row per checked item:
+**MCP conformance checker**. Point it at an MCP server source tree and it emits a
+**conformance-diff table** against the MCP **2026-07-28** standard — one row per detector:
 
 ```
-item | file:line | present | absent | non-conforming | verdict
+item | file:line | state | verdict
 ```
 
-No narrative, no LLM, no network: a deterministic static scan you can wire into CI. It reproduces,
+where `state` is one of `present`, `absent`, `non-conforming` or `could-not-judge` (see
+[States and exit codes](#states-and-exit-codes)).
+
+No narrative, no LLM. By default it is a deterministic **static** scan you can wire into CI; with
+`--mode=dynamic` it also launches the server and judges what it actually serves. It reproduces,
 unaided, the manual conformance audits the fleet ran by hand on its own MCP servers.
 
 ## Usage
@@ -37,6 +41,56 @@ D7 protocol-kit          | package.json       | absent          | hand-rolled bu
 The path is the root of the MCP server sources (the folder holding `server.ts` / `transport/` /
 `package.json`). `node_modules`, `dist`, `build`, `.git` and test folders are skipped automatically.
 
+### Options
+
+The binary's own `--help` is the authority; this is what it prints:
+
+```
+usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
+
+  --mode=static   read the tree only (default)
+  --mode=dynamic  launch the server and judge what it serves
+  --mode=both     both, dynamic findings taking precedence
+  --version       print the version and exit
+  --help          print this and exit
+
+exit: 0 clean, 1 a violation, 2 an abstention with no violation
+```
+
+## States and exit codes
+
+| state | meaning | effect on exit |
+|---|---|---|
+| `present` | the standard item is satisfied | none |
+| `absent` | the detector found nothing to judge — see the caveat below | none |
+| `non-conforming` | the item is present and wrong | **exit 1** |
+| `could-not-judge` | the detector could not read its input and says so in the row — in 0.3.1, only D9 does this (no `package.json` above the root); see the limits below | **exit 2**, unless something else is non-conforming |
+
+The exit code keeps three outcomes distinct, which is what makes the tool safe in CI:
+
+- **0** — clean.
+- **1** — at least one violation.
+- **2** — no violation, but at least one detector abstained. **An abstention is never a pass**: it
+  means part of the tree was not judged, and the row names which part and why.
+
+**Two known limits in 0.3.1, stated rather than hidden:**
+
+- **`absent` currently means two things.** It is used both for "this rule does not apply here" and,
+  for some detectors, "this is required and missing". The second should move the exit code and
+  today does not. Until that is split, read an `absent` row against the rule it names rather than
+  treating it as harmless.
+- **Unreadable input is handled in band by D9 only.** In 0.3.1, D9 reports `could-not-judge` when no
+  `package.json` sits above the scanned root, and the run completes. Several other detectors still
+  **throw** on unreadable input — a malformed manifest, a computed value — which aborts the run with
+  exit 1 and a stack trace, indistinguishable from a violation. Converting them is in progress.
+
+By design, a detector whose own internal self-check fails stops the run — that is the instrument
+reporting that it is broken, and silencing it would hide the fault behind a normal-looking table.
+
+**Upgrading from 0.2.0:** through `npx` or `node_modules/.bin`, 0.2.0 printed nothing and exited 0
+for every target, because its entrypoint guard never fired under a symlink. A CI job that has been
+green on 0.2.0 was green because nothing ran. Expect findings on the first run of 0.3.x.
+
 ## Programmatic use
 
 ```ts
@@ -46,7 +100,7 @@ const results = runDoctor("./mcp-server");
 console.log(renderTable("./mcp-server", results));
 ```
 
-## What it checks — the 6 Tier-A detectors (MCP 2026-07-28)
+## What it checks (MCP 2026-07-28)
 
 Each detector maps one standard item and is proven **bipolar** on real material: a genuine defect
 (MUST_FLAG) and a genuine conformant site (MUST_PASS).
@@ -62,7 +116,11 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D15** cache-coherence | Server Rule 15 — every tool-set mutation (RegisteredTool `.enable/.disable/.update/.remove`, `unregisterTool`) is correlated with a `notifications/tools/list_changed` emission | present / absent / non-conforming / could-not-judge |
 | **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth | present / absent / non-conforming / could-not-judge |
 
-The registered detector set is the source of truth (`src/detectors/index.ts`); the table above is illustrative, not the count. **Adding a detector is how a friction becomes durable — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the loop.**
+**This table is a sample, not the inventory.** Every registered detector runs on every invocation,
+so the authoritative list is simply the output of a run — one row per detector. The registered set
+lives in `src/detectors/index.ts`. No count is written here on purpose: a number typed into a README
+is correct on the day it is written and wrong at the next detector, which is exactly how this
+heading came to claim 6 while the tool shipped dozens. **Adding a detector is how a friction becomes durable — see [CONTRIBUTING.md](./CONTRIBUTING.md) for the loop.**
 
 ## Positioning
 
@@ -71,10 +129,17 @@ standard by naming the exact `file:line` to fix — and a **vendable product** f
 MCP servers who needs a reproducible conformance gate. It is deterministic: the same tree yields the
 same diff on any machine, so it belongs in CI, not in a review checklist.
 
+## Contributing
+
+`npm test` builds first (a `pretest` script runs `npm run build`), because several tests drive the
+real published entry point through a symlinked bin and need `dist/` to exist. Earlier versions
+assumed a prior build, which passed for anyone who had already built and failed for anyone who had
+just cloned.
+
 ## License
 
 FSL-1.1-Apache-2.0 (Functional Source License, Apache 2.0 future license). See [LICENSE](./LICENSE).
 
 ---
 
-Orchestrator: Gamma — VantageOS Team | 2026-08-03
+Orchestrator: Gamma — VantageOS Team | 2026-10-04

package/dist/doctor.d.ts

@@ -37,6 +37,13 @@ interface DetectorResult {
 interface RuntimeTool {
     /** The tool name the server actually advertises at runtime (post-startup). */
     name: string;
+    /**
+     * The description the server actually SERVES over `tools/list`, post-
+     * startup — the surface C-19 measures (never the source-declared string,
+     * which can drift from what a real client receives). Unset only when the
+     * running server declares no description for the tool.
+     */
+    description?: string;
     /**
      * Number of eval cases covering this tool, resolved by the runtime builder
      * from the target's `evals/evals.json` (matched by tool name). Optional
@@ -65,9 +72,42 @@ interface RuntimeContext {
     root: string;
     tools: RuntimeTool[];
     launchError?: string;
+    /**
+     * The `serverInfo` object the running server returned in its `initialize`
+     * response — the same non-authenticated discovery handshake a client reads
+     * `version` from (S-7). Additive field: existing dynamic detectors that
+     * never read it are unaffected. C-25 reads it for a build-identity field
+     * served alongside `version` (commit hash / build id). Unset when the
+     * launched server returned no `serverInfo` or the launch failed
+     * (`launchError` is then set instead).
+     */
+    serverInfo?: Record<string, unknown>;
+    /**
+     * The commit the running server is EXPECTED to be serving, DERIVED from
+     * `git rev-parse HEAD` in the target tree — never hand-typed (see
+     * derive-never-type). Unset when the target is not a resolvable git
+     * checkout: C-25's dynamic served-vs-expected comparison is then reported
+     * as OWED (could-not-judge), never silently skipped as a pass.
+     * When set it is ALWAYS a full 40-hex commit id (`/^[0-9a-f]{40}$/`,
+     * enforced by `deriveExpectedCommit`): C-25's comparison reasons about
+     * length and asserts that shape rather than assuming it.
+     */
+    expectedCommit?: string;
 }
 interface Detector {
     id: string;
+    /**
+     * The canonical standard rule id this detector judges (e.g. "C-6"). Optional
+     * so the pre-existing detectors that predate this field still compile; every
+     * detector built or re-pinned against a standard rule MUST populate it.
+     * Coverage of the standard is DERIVED from this field across the registry
+     * (see `scripts/trunk-coverage.ts`) — never from a hand-kept list.
+     */
+    rule?: string;
+    /** The standard commit this detector's `rule` was read against. Required
+     * alongside `rule`: a rule id with no pin is unverifiable against a moving
+     * doc. */
+    pin?: string;
     /** Static verdict from the source tree. REQUIRED — static is never optional. */
     run(tree: Tree): DetectorResult;
     /**
@@ -129,6 +169,10 @@ interface Session {
  */
 interface LiveDetector {
     id: string;
+    /** See `Detector.rule` — same contract, same derivation. */
+    rule?: string;
+    /** See `Detector.pin` — same contract. */
+    pin?: string;
     /**
      * Live verdict from a running session. REQUIRED for a live detector. It owns
      * the abstain contract: a session it cannot read (absent, throwing, timing