@vantageos/mcp-doctor 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
+## 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/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