@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/doctor/checks/checkShellCompletions.ts

@@ -8,7 +8,7 @@ import {
   runComplete,
 } from "../../../kernel/completion/index.js";
 import { capabilities } from "../../index.js";
-import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import type { CompletionsDetection } from "../../setup/operations/index.js";
 import { activationHint, type ShellId } from "../../setup/shell.js";
 import type { CheckResult } from "../types.js";
 
@@ -97,14 +97,26 @@ async function completeProbe(cwd: string): Promise<number> {
  * 3. For zsh, `~/.zfunc` is on `$fpath` — the activation step setup can only
  *    hint. Installed-but-unwired reports a distinct remedy.
  *
- * @param cwd - The project directory (the resolver's entity seam, and the
- *   `completion` config gate 2 renders this project's body from).
- * @returns A CheckResult: pass (up to date + wired + answering), fail (with the
- *   attributable remedy), or skip (shell undetected).
- * @note Impure — reads `$SHELL`, the install path, the config layers, `.zshrc`,
- *   and drives the storeless resolver.
+ * Fault tiers: a broken resolver, a stale installed script, or an unwired zsh
+ * install are `fail` — something that exists does not work. A script that was
+ * never installed is `available`: completions are opt-in and a fresh install
+ * is healthy without them.
+ *
+ * The detection is passed IN rather than re-read: the `completions` target
+ * detects once per invocation and both the setup plan and this row read that
+ * one answer, so the two surfaces cannot describe different files.
+ *
+ * @param cwd - The project directory (the resolver's entity seam).
+ * @param d - The `completions` target's detection for this invocation.
+ * @returns A CheckResult: pass (up to date + wired + answering), available
+ *   (never installed, with the setup remedy), fail (with the attributable
+ *   remedy), or skip (shell undetected).
+ * @note Impure — reads the install path, `.zshrc`, and drives the resolver.
  */
-export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
+export async function checkShellCompletions(
+  cwd: string,
+  d: CompletionsDetection,
+): Promise<CheckResult> {
   // 1. Effect test: the resolver the scripts delegate to must actually answer.
   let candidates: number;
   try {
@@ -114,7 +126,7 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
     return {
       name: NAME,
       status: "fail",
-      detail: `completion resolver failed: ${reason}`,
+      detail: `${BIN_NAME} cannot answer \`<TAB>\`: ${reason}`,
       remedy: `Report this as a bug — \`${BIN_NAME} __complete\` should never throw.`,
     };
   }
@@ -122,25 +134,59 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
     return {
       name: NAME,
       status: "fail",
-      detail: `completion resolver returned no candidates for \`${BIN_NAME} <TAB>\``,
+      detail: `${BIN_NAME} answered \`<TAB>\` with nothing to complete`,
       remedy: "Report this as a bug — the noun context is always non-empty.",
     };
   }
 
-  // 2. The installed script is a script `setup completions` would write.
-  const { shell, path, state } = await detectCompletions(cwd);
+  // 2. The check is about the shell the user is IN. Reporting on the login
+  //    shell instead is what let this row print a green check for a shell the
+  //    user never opens while the one they live in had nothing installed.
+  const { shell, path, state } = d;
+  if (d.detection.kind === "ambiguous") {
+    return {
+      name: NAME,
+      status: "skip",
+      detail: `${BIN_NAME} answers \`<TAB>\`, but the running shell cannot be identified — SHELL names ${d.detection.login}, which is your login shell`,
+      remedy: `Run \`${INSTALL_REMEDY}\` from the shell you want completions in.`,
+    };
+  }
   if (shell === null || path === null) {
     return {
       name: NAME,
       status: "skip",
-      detail: "resolver OK; shell not detected ($SHELL unset)",
+      detail: `${BIN_NAME} answers \`<TAB>\`, but no bash, zsh, or fish was found in this process tree`,
+    };
+  }
+  // The installed script delegates every name context to the binary. A script
+  // that cannot reach it is inert, and reporting it as current is the same
+  // false green this row already told once.
+  //
+  // This gate runs BEFORE the install probe, so it says only what it has
+  // verified: that the binary does not resolve. Claiming "script installed" here
+  // told a user running this CLI by absolute path that a script they had never
+  // installed was broken — an invented file, in the row whose whole job is to
+  // report the real one. Nothing installed is still the opt-in `available` tier.
+  if (!d.binOnPath) {
+    const installed = state !== "absent";
+    return {
+      name: NAME,
+      status: installed ? "fail" : "available",
+      detail: installed
+        ? `${shell} script installed, but \`${BIN_NAME}\` is not on PATH — the script cannot run it`
+        : `${BIN_NAME} answers \`<TAB>\`, but is not on PATH — an installed script cannot run it`,
+      remedy: `Put \`${BIN_NAME}\` on your PATH.`,
     };
   }
   if (state === "absent") {
+    // Never installed is `available`, not a fault: completions are opt-in and
+    // a fresh install is healthy without them. An INSTALLED script that is
+    // out of date or unwired (below) is the real failure — something the user
+    // set up no longer works.
     return {
       name: NAME,
-      status: "fail",
-      detail: `resolver OK; ${shell} script not installed`,
+      status: "available",
+      detail: `${BIN_NAME} answers \`<TAB>\`; the ${shell} script is not installed`,
       remedy: INSTALL_REMEDY,
     };
   }
@@ -148,7 +194,7 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
     return {
       name: NAME,
       status: "fail",
-      detail: `resolver OK; ${shell} script at ${path} is out of date`,
+      detail: `${BIN_NAME} answers \`<TAB>\`; the ${shell} script at ${path} is out of date`,
       remedy: INSTALL_REMEDY,
     };
   }
@@ -166,6 +212,6 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   return {
     name: NAME,
     status: "pass",
-    detail: `${shell} up to date and resolving (${candidates} nouns)`,
+    detail: `${shell} (the shell you are in) — installed, up to date, and completing ${candidates} commands`,
   };
 }

package/src/capabilities/doctor/checks/harnessInventory.test.ts

@@ -0,0 +1,219 @@
+/**
+ * The harness inventory roll-up — the pure half, driven by fixtures.
+ *
+ * `doctor.test.ts` covers the wiring (both scopes, `--verbose`, the real
+ * registry). What is unit-tested here is the classification itself: the
+ * registry supplies the universe so the NEGATIVE is representable, the groups
+ * supply the state, and no combination of the two may ever produce a `fail`.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  harnessInventory,
+  type InventoryGroup,
+  type InventoryHarness,
+  type InventoryMember,
+  type InventoryRow,
+  inventoryHealth,
+  inventoryItems,
+  isDetectedState,
+  type WriteState,
+} from "./harnessInventory.js";
+
+const REGISTRY: InventoryHarness[] = [
+  { id: "claude-code", name: "Claude Code", inScope: true },
+  { id: "cursor", name: "Cursor", inScope: true },
+  { id: "vscode", name: "VS Code", inScope: false },
+];
+
+/** One harness's share of a file — its OWN write's state, never the file's. */
+const named = (name: string, state: WriteState): InventoryMember => ({
+  name,
+  state,
+});
+
+const roll = (groups: InventoryGroup[]): InventoryRow[] =>
+  harnessInventory(REGISTRY, groups, "global");
+
+describe("harnessInventory — the roll-up", () => {
+  it("classifies each registry harness against the scope's groups", () => {
+    const rows = roll([
+      {
+        path: "~/.claude.json",
+        harnesses: [named("Claude Code", "registered")],
+      },
+      { path: "~/.cursor/mcp.json", harnesses: [named("Cursor", "absent")] },
+    ]);
+
+    expect(rows.map((r) => `${r.harnessId}:${r.state}`)).toEqual([
+      "claude-code:registered",
+      "cursor:detected",
+      // Not detected AND has no location in this scope at all — the two are
+      // different facts and the row says which one applies.
+      "vscode:unscoped",
+    ]);
+    expect(rows[0]?.locations).toEqual(["~/.claude.json"]);
+    expect(rows[2]?.locations).toEqual([]);
+  });
+
+  it("keeps 'undetected' and 'unscoped' apart", () => {
+    // Same absence, two different reasons: Cursor could be here and is not,
+    // VS Code could never be here at all.
+    const rows = roll([]);
+    expect(rows.find((r) => r.harnessId === "cursor")?.state).toBe(
+      "undetected",
+    );
+    expect(rows.find((r) => r.harnessId === "vscode")?.state).toBe("unscoped");
+  });
+
+  it("reports a drifted group as drifted, not as registered", () => {
+    const rows = roll([
+      { path: "~/.claude.json", harnesses: [named("Claude Code", "drifted")] },
+    ]);
+    expect(rows[0]?.state).toBe("drifted");
+  });
+
+  it("a harness sharing two files is registered only when BOTH carry the entry", () => {
+    const both = harnessInventory(
+      REGISTRY,
+      [
+        { path: "a.json", harnesses: [named("Cursor", "registered")] },
+        { path: "b.json", harnesses: [named("Cursor", "registered")] },
+      ],
+      "global",
+    );
+    expect(both[1]?.state).toBe("registered");
+    expect(both[1]?.locations).toEqual(["a.json", "b.json"]);
+
+    const mixed = harnessInventory(
+      REGISTRY,
+      [
+        { path: "a.json", harnesses: [named("Cursor", "registered")] },
+        { path: "b.json", harnesses: [named("Cursor", "absent")] },
+      ],
+      "global",
+    );
+    expect(mixed[1]?.state).toBe("drifted");
+  });
+
+  it("gives each harness sharing ONE file its own state, not the file's", () => {
+    // The co-detection case, and the reason a group carries per-harness state:
+    // `.vscode/mcp.json` holds VS Code's `servers` and Cline's `mcpServers` as
+    // two independent entries. Register pragma for VS Code alone and the FILE
+    // classifies as drifted — one key current, one absent — but neither
+    // harness is drifted: VS Code is registered and Cline is merely detected.
+    // A fixture with one harness per file cannot see this.
+    const shared: InventoryHarness[] = [
+      { id: "cline", name: "Cline", inScope: true },
+      { id: "vscode", name: "VS Code", inScope: true },
+    ];
+    const rows = harnessInventory(
+      shared,
+      [
+        {
+          path: ".vscode/mcp.json",
+          harnesses: [named("Cline", "absent"), named("VS Code", "registered")],
+        },
+      ],
+      "project",
+    );
+
+    expect(rows.map((r) => `${r.harnessId}:${r.state}`)).toEqual([
+      "cline:detected",
+      "vscode:registered",
+    ]);
+    // Both are located in the same file — the sharing itself is unchanged.
+    for (const row of rows) expect(row.locations).toEqual([".vscode/mcp.json"]);
+  });
+
+  it("ignores a group naming a harness the registry does not know", () => {
+    // The inventory reports on the REGISTRY; a group is evidence, not a source
+    // of rows, so an unknown name adds nothing rather than inventing an entry.
+    const rows = roll([
+      { path: "x.json", harnesses: [named("Ghost Editor", "registered")] },
+    ]);
+    expect(rows).toHaveLength(REGISTRY.length);
+    expect(rows.map((r) => r.harnessName)).not.toContain("Ghost Editor");
+  });
+
+  it("names every row with the scope it was rolled up for", () => {
+    const rows = harnessInventory(REGISTRY, [], "project");
+    expect(rows.every((r) => r.scope === "project")).toBe(true);
+  });
+});
+
+describe("harnessInventory — the listing", () => {
+  const rows = roll([
+    { path: "~/.claude.json", harnesses: [named("Claude Code", "registered")] },
+  ]);
+
+  it("shows detected harnesses only by default", () => {
+    const items = inventoryItems(rows, false);
+    expect(items.map((i) => i.label)).toEqual(["Claude Code"]);
+    expect(items[0]?.detail).toBe("registered — ~/.claude.json");
+  });
+
+  it("--verbose widens the same rows to the whole registry", () => {
+    const items = inventoryItems(rows, true);
+    expect(items.map((i) => i.label)).toEqual([
+      "Claude Code",
+      "Cursor",
+      "VS Code",
+    ]);
+    expect(items[1]?.detail).toBe("not detected");
+    // Scope-aware, and it states the FACT rather than naming a partition:
+    // VS Code keeps its MCP config per project, so there is no global file for
+    // pragma to be in. `no Global band` named an internal word for that.
+    expect(items[2]?.detail).toBe(
+      "keeps no global config — it is per-project only",
+    );
+  });
+
+  it("never renders any state as a failure", () => {
+    for (const item of inventoryItems(rows, true)) {
+      expect(item.status).not.toBe("fail");
+    }
+    const every = harnessInventory(REGISTRY, [], "project");
+    for (const item of inventoryItems(every, true)) {
+      expect(item.status).not.toBe("fail");
+    }
+  });
+
+  it("is a listing, not a verdict: pass when the scope holds harnesses, skip when it does not", () => {
+    expect(inventoryHealth(rows, false).status).toBe("pass");
+    expect(inventoryHealth(rows, false).detail).toBe(
+      "1 detected · 1 registered",
+    );
+    expect(inventoryHealth(rows, true).detail).toBe(
+      "1 detected · 1 registered · 3 known",
+    );
+
+    const empty = roll([]);
+    expect(inventoryHealth(empty, false).status).toBe("skip");
+    expect(inventoryHealth(empty, false).detail).toBe("no harnesses detected");
+    expect(inventoryHealth(empty, false).items).toEqual([]);
+    expect(inventoryHealth(empty, true).detail).toBe(
+      "none of 3 known harnesses detected",
+    );
+  });
+
+  it("counts a drifted harness as detected but not as registered", () => {
+    const drifted = roll([
+      { path: "~/.claude.json", harnesses: [named("Claude Code", "drifted")] },
+    ]);
+    expect(inventoryHealth(drifted, false).detail).toBe(
+      "1 detected · 0 registered",
+    );
+    expect(inventoryItems(drifted, false)[0]?.status).toBe("available");
+  });
+});
+
+describe("isDetectedState", () => {
+  it("counts every state that means the harness is on the machine", () => {
+    expect(isDetectedState("registered")).toBe(true);
+    expect(isDetectedState("drifted")).toBe(true);
+    expect(isDetectedState("detected")).toBe(true);
+    expect(isDetectedState("undetected")).toBe(false);
+    expect(isDetectedState("unscoped")).toBe(false);
+  });
+});

package/src/capabilities/doctor/checks/harnessInventory.ts

@@ -0,0 +1,298 @@
+/**
+ * The harness inventory: one row per harness per scope, saying what was detected
+ * and whether pragma is registered in it.
+ *
+ * Every fact this needs was ALREADY COMPUTED and thrown away.
+ * `TargetGroup.harnessNames` carries every harness sharing a config file and
+ * both consumers reduced it to `shortenPath(group.path)`; `McpDetection`
+ * carries the `absent`/`registered`/`drifted` classification of every WRITE in
+ * that file. The only thing detection could NOT answer is the negative —
+ * `detectHarnesses` filters to hits, so a harness the machine does not have was
+ * unrepresentable — which is why the roll-up takes the REGISTRY alongside the
+ * groups: the registry supplies the universe, the groups supply the state.
+ *
+ * The state arrives PER HARNESS, never per file. A shared `.vscode/mcp.json`
+ * holds VS Code's `servers` and Cline's `mcpServers` as two independent
+ * entries, so the file's aggregate — `drifted`, when one key is current and the
+ * other absent — is the standing of NEITHER harness. Pairing each name with
+ * the write it owns is the caller's job (it holds the registry's `mcpKey`s and
+ * the group's writes); by the time a group reaches this module the association
+ * is resolved and every name carries its own state.
+ *
+ * Three deliberate constraints:
+ *
+ * 1. **No `@canonical/harnesses` import, of any kind.** `capabilities/lazy.test`
+ *    forbids one from any file statically reachable from `capabilities/index`,
+ *    and its regex has no `import type` exemption. This module is reached only
+ *    through `runChecks`'s dynamic import today, but it is written so that
+ *    staying legal never depends on that: the inputs are declared here as
+ *    narrow structural records.
+ *
+ * 2. **Narrowed to DATA, so `mutates: false` is enforced rather than asserted.**
+ *    `McpDetection` is write-capable — it carries `writeMcpConfigTargets` and
+ *    `removeMcpConfigFrom` as live function references. Projecting it down to
+ *    {@link InventoryGroup} before it reaches this file means a read-only
+ *    report literally cannot reach a writer.
+ *
+ * 3. **It never invents a failure.** The states an inventory can report map onto
+ *    `pass`/`available`/`skip` and NEVER `fail` (see `../types.ts`): a machine
+ *    that simply does not have Windsurf is not a broken machine, and the `mcp`
+ *    row already owns the actionable finding for the harnesses it does have.
+ *    Reporting it twice is how a failure count becomes noise.
+ *
+ * Placement: this is a doctor helper because doctor is its only consumer today,
+ * and `shared/` is explicitly not a utility drawer (see `shared/index.ts`). It
+ * is written to MOVE there unchanged — pure, no capability imports beyond the
+ * scope type — the moment `setup`'s detection summary becomes the second caller.
+ */
+
+import type { CheckItem, CheckStatus, Scope } from "../types.js";
+
+/**
+ * What the inventory says about one harness in one scope.
+ *
+ * The vocabulary is deliberately NOT "installed". Two different claims used
+ * to share that word — `DetectedHarness.configExists` ("the harness's own
+ * config file exists", a harnesses-package field this module never surfaces)
+ * and the pragma-entry state (`McpTargetState`, which now says `registered`
+ * for exactly this reason). Every state here names the PRAGMA-ENTRY meaning.
+ * One name per claim, held across the reports: "installed" is reserved for
+ * artifacts the CLI itself places (the completion script, the LSP extension),
+ * "registered" for pragma's entry in someone else's config, "linked" for
+ * skill symlinks.
+ *
+ * - `registered` — detected, and pragma's MCP entry in this scope is current.
+ * - `drifted` — detected, and a pragma entry exists but differs from what a
+ *   write would emit. Actionable, but the `mcp` row is where it is actionED;
+ *   here it is reported without inflating the failure count.
+ * - `detected` — the harness is on this machine; pragma is not registered.
+ * - `undetected` — in the registry, has a location in this scope, not found.
+ * - `unscoped` — in the registry, but has NO config location in this scope at
+ *   all (VS Code is `scope: "project"`, so it can never hold a global entry).
+ *   Stated rather than omitted: a verbose listing that silently dropped a row
+ *   reads as a bug in the listing.
+ */
+export type InventoryState =
+  | "registered"
+  | "drifted"
+  | "detected"
+  | "undetected"
+  | "unscoped";
+
+/** One harness's standing in one scope. */
+export interface InventoryRow {
+  readonly harnessId: string;
+  readonly harnessName: string;
+  readonly scope: Scope;
+  readonly state: InventoryState;
+  /** The config paths in this scope that carry (or would carry) the entry. */
+  readonly locations: readonly string[];
+}
+
+/** A registry entry, narrowed to what the roll-up reads. */
+export interface InventoryHarness {
+  readonly id: string;
+  readonly name: string;
+  /** Whether this harness has a config location in the scope being rolled up. */
+  readonly inScope: boolean;
+}
+
+/** The prior state of one harness's own write, as detection classified it. */
+export type WriteState = "absent" | "registered" | "drifted";
+
+/** One harness's share of a config file: the state of the write IT owns. */
+export interface InventoryMember {
+  readonly name: string;
+  readonly state: WriteState;
+}
+
+/**
+ * One detected config file, narrowed off {@link McpDetection}: the group's
+ * already-shortened path, and every harness sharing it WITH ITS OWN state.
+ *
+ * Per harness, not per file — see the module docblock. A file-level state here
+ * would report both harnesses sharing `.vscode/mcp.json` as drifted the moment
+ * either one of them is registered alone.
+ */
+export interface InventoryGroup {
+  readonly path: string;
+  readonly harnesses: readonly InventoryMember[];
+}
+
+/** Whether a state means "this harness is on the machine". */
+export const isDetectedState = (state: InventoryState): boolean =>
+  state === "registered" || state === "drifted" || state === "detected";
+
+/**
+ * Roll one scope's detected config groups up against the registry into one row
+ * per harness.
+ *
+ * Groups are keyed by harness NAME because that is the only identity
+ * `TargetGroup` records; the registry is the map back to an id, which is why it
+ * is a parameter rather than a lookup. A harness naming no registry row is
+ * ignored rather than invented — the inventory reports on the registry, not on
+ * whatever a group happened to say.
+ *
+ * @param registry - Every known harness, each flagged for scope membership.
+ * @param groups - This scope's detected config files (narrowed, path-shortened),
+ *   each naming the harnesses that share it with their own per-write state.
+ * @param scope - The scope being rolled up.
+ * @returns One row per registry harness, in registry order.
+ * @note Pure — it reads no filesystem and holds no live effect.
+ */
+export function harnessInventory(
+  registry: readonly InventoryHarness[],
+  groups: readonly InventoryGroup[],
+  scope: Scope,
+): InventoryRow[] {
+  const states = new Map<string, WriteState>();
+  const locations = new Map<string, string[]>();
+  for (const group of groups) {
+    for (const member of group.harnesses) {
+      const paths = locations.get(member.name) ?? [];
+      paths.push(group.path);
+      locations.set(member.name, paths);
+      // A harness sharing two files is registered only where EVERY one of them
+      // carries the current entry — the same "all or nothing" rule
+      // `aggregateMcpStates` applies across the writes within a single file.
+      const prior = states.get(member.name);
+      states.set(
+        member.name,
+        prior === undefined || prior === member.state
+          ? member.state
+          : "drifted",
+      );
+    }
+  }
+
+  return registry.map((harness): InventoryRow => {
+    const detected = states.get(harness.name);
+    const paths = locations.get(harness.name) ?? [];
+    const state: InventoryState =
+      detected === undefined
+        ? harness.inScope
+          ? "undetected"
+          : "unscoped"
+        : detected === "registered"
+          ? "registered"
+          : detected === "drifted"
+            ? "drifted"
+            : "detected";
+    return {
+      harnessId: harness.id,
+      harnessName: harness.name,
+      scope,
+      state,
+      locations: paths,
+    };
+  });
+}
+
+/** The per-item status each state renders as. Never `fail` — see the docblock. */
+const STATE_STATUS: Record<InventoryState, CheckStatus> = {
+  registered: "pass",
+  drifted: "available",
+  detected: "available",
+  undetected: "skip",
+  unscoped: "skip",
+};
+
+/**
+ * The phrase each state reads as, scope-aware for the unscoped case.
+ *
+ * The unscoped line says WHERE the harness keeps its config rather than naming
+ * an internal partition. `no Global band` told the reader nothing: "band" was
+ * this repository's word, and the fact underneath it — VS Code stores its MCP
+ * config per project, so there is no global file for pragma to be in — is the
+ * thing that explains the row.
+ */
+const stateDetail = (row: InventoryRow): string => {
+  switch (row.state) {
+    case "registered":
+      return "registered";
+    case "drifted":
+      return "registered, entry differs from current";
+    case "detected":
+      return "detected, not registered";
+    case "undetected":
+      return "not detected";
+    case "unscoped":
+      return row.scope === "global"
+        ? "keeps no global config — it is per-project only"
+        : "keeps no per-project config — it is global only";
+  }
+};
+
+/**
+ * Project inventory rows into doctor sub-items.
+ *
+ * The default listing is DETECTED HARNESSES ONLY — a report that names every
+ * tool the user does not have buries the ones they do. `--verbose` widens it to
+ * the whole registry, which is the only view in which `undetected`/`unscoped`
+ * rows appear at all.
+ *
+ * @param rows - This scope's inventory rows.
+ * @param verbose - Whether to list the whole registry rather than the hits.
+ * @returns The sub-items, harness name in the left column.
+ */
+export function inventoryItems(
+  rows: readonly InventoryRow[],
+  verbose: boolean,
+): CheckItem[] {
+  const shown = verbose
+    ? rows
+    : rows.filter((row) => isDetectedState(row.state));
+  return shown.map((row): CheckItem => {
+    const where = row.locations.join(", ");
+    return {
+      label: row.harnessName,
+      status: STATE_STATUS[row.state],
+      detail: where ? `${stateDetail(row)} — ${where}` : stateDetail(row),
+    };
+  });
+}
+
+/** The inventory check's headline, and whether it has anything to show. */
+export interface InventoryHealth {
+  readonly status: CheckStatus;
+  readonly detail: string;
+  readonly items: readonly CheckItem[];
+}
+
+/**
+ * The whole inventory row for one scope: a listing, not a verdict.
+ *
+ * Its status is only ever `pass` (this scope has harnesses) or `skip` (it has
+ * none). It is the one scoped row that is not a setup target, so it derives no
+ * `fix:` line — the `mcp` and `skills` rows beside it own every action a
+ * harness can need, and a second row proposing the same command would be the
+ * "same finding seen twice" the report is built to avoid.
+ *
+ * @param rows - This scope's inventory rows.
+ * @param verbose - Whether the listing widens to the whole registry.
+ * @returns The status, headline and sub-items for the scope's inventory check.
+ */
+export function inventoryHealth(
+  rows: readonly InventoryRow[],
+  verbose: boolean,
+): InventoryHealth {
+  const detected = rows.filter((row) => isDetectedState(row.state));
+  const registered = rows.filter((row) => row.state === "registered");
+  const items = inventoryItems(rows, verbose);
+  if (detected.length === 0) {
+    return {
+      status: "skip",
+      detail: verbose
+        ? `none of ${rows.length} known harnesses detected`
+        : "no harnesses detected",
+      items,
+    };
+  }
+  return {
+    status: "pass",
+    detail: `${detected.length} detected · ${registered.length} registered${
+      verbose ? ` · ${rows.length} known` : ""
+    }`,
+    items,
+  };
+}

package/src/capabilities/doctor/checks/index.ts

@@ -0,0 +1,27 @@
+/**
+ * The doctor check catalogue — the diagnoses `doctor` composes into a report.
+ *
+ * A check is the whole shape of this domain: it inspects ONE thing, decides
+ * pass or fail, and hands back a `CheckResult` carrying the remedy. Keeping
+ * them apart from the report body is what lets `runChecks` stay a composition
+ * — it orders and awaits, and knows nothing about what any check looks at.
+ *
+ * Two kinds live here, and the barrel exposes them differently. The UNSCOPED
+ * checks diagnose what `setup` cannot install — the Node floor, the CLI's own
+ * version and install source, the pack answering this project's reads, and the
+ * store — so each is its own named entry point. The SCOPED rows are derived
+ * per target, per scope, from the setup target table rather than authored here,
+ * so they surface as the one generator that derives them, never as a list of
+ * row names this file would then have to keep in step with `setup`.
+ *
+ * The per-target probes (the completions script check, the MCP command
+ * resolution helpers) stay internal on purpose: `scopedChecks` is the only way
+ * they are meant to be reached, and a row reachable past its scope is a row
+ * `doctor` can report and `setup` cannot fix.
+ */
+
+export { checkKeStore } from "./checkKeStore.js";
+export { checkNodeVersion } from "./checkNodeVersion.js";
+export { checkPackageRefs } from "./checkPackageRefs.js";
+export { checkPragmaVersion } from "./checkPragmaVersion.js";
+export { scopedChecks } from "./targetHealth.js";