@canonical/pragma-cli 0.35.0 → 0.37.0

package/src/capabilities/create/create.verb.ts

@@ -523,11 +523,12 @@ export const createVerbs: Record<
   ),
   application: createVerb(
     "application",
-    "Scaffold a full React application with SSR and routing.",
+    "Scaffold a full React application with routing, and either server-side rendering or a client-only SPA.",
     applicationParams,
     [
       { cmd: `${BIN_NAME} create application react my-app` },
       { cmd: `${BIN_NAME} create application react my-app --relay` },
+      { cmd: `${BIN_NAME} create application react my-app --rendering spa` },
     ],
   ),
 };

package/src/capabilities/create/createGrammar.test.ts

@@ -655,7 +655,10 @@ describe("the mounted create grammar (subprocess)", () => {
       "--type": "library",
       "--description": "A replied library.",
     },
-    "application/react": { "--app-path": "replied-app" },
+    "application/react": {
+      "--app-path": "replied-app",
+      "--rendering": "spa",
+    },
   };
   for (const [commandPath, surface] of Object.entries(CREATE_SURFACE)) {
     it(`${commandPath}: the refusal's own instruction WORKS — its Missing tokens supplied back (+ --dry-run) preview, exit 0`, () => {
@@ -768,7 +771,7 @@ describe("the refusal cell through dispatchPrepared (in-process)", () => {
 describe("the mount's mode resolution — TTY driven through the seam", () => {
   // No suite can hand a subprocess a real TTY, so the §L rows that depend on
   // isTTY: true are pinned HERE, through the exported resolver the action
-  // itself calls (with cliIsTTY()). The OLD decision block routed TTY
+  // itself calls (with canPrompt()). The OLD decision block routed TTY
   // dry-run/undo into Ink; these rows keep that from silently returning.
   const prompts = CREATE_SURFACE["component/react"]?.prompts ?? [];
   const flags = (dryRun: boolean, undo: boolean, yes: boolean) => ({

package/src/capabilities/create/createSurface.generated.ts

@@ -17,7 +17,7 @@ export const CREATE_SURFACE: Readonly<Record<string, SurfaceCommand>> = {
       "application",
       "react"
     ],
-    "description": "Scaffold a complete React application with SSR and routing",
+    "description": "Scaffold a complete React application with routing, and either server-side rendering or a client-only SPA",
     "prompts": [
       {
         "name": "appPath",
@@ -41,6 +41,23 @@ export const CREATE_SURFACE: Readonly<Record<string, SurfaceCommand>> = {
         "default": false,
         "group": "Application"
       },
+      {
+        "name": "rendering",
+        "type": "select",
+        "message": "Rendering — ssr keeps the server layer (SSR servers and sitemap), spa is client-only",
+        "default": "ssr",
+        "choices": [
+          {
+            "label": "ssr - server-side rendering (Express + Bun servers, sitemap)",
+            "value": "ssr"
+          },
+          {
+            "label": "spa - client-only single-page app (no server layer)",
+            "value": "spa"
+          }
+        ],
+        "group": "Application"
+      },
       {
         "name": "relay",
         "type": "confirm",
@@ -278,6 +295,11 @@ export const CREATE_CLI_SYNTAX: Readonly<
       "takesValue": false,
       "kebabName": "intl"
     },
+    "rendering": {
+      "flag": "--rendering",
+      "takesValue": true,
+      "kebabName": "rendering"
+    },
     "relay": {
       "flag": "--relay",
       "takesValue": false,

package/src/capabilities/create/crossCli.subprocess.test.ts

@@ -258,9 +258,16 @@ describe("cross-CLI conformance matrix (PROTECTED)", () => {
   // here, which is the point).
   it("every declared generator binding path is driven by a conformance fixture", () => {
     expect(
-      [...CONFORMANCE_FIXTURES]
-        .map((fixture) => commandPathOf(fixture.generator))
-        .sort(),
+      // Deduplicated: the assertion is that every declared path is COVERED, and
+      // one path may carry several fixtures — application/react is driven by
+      // both the SSR arm and the SPA arm.
+      [
+        ...new Set(
+          CONFORMANCE_FIXTURES.map((fixture) =>
+            commandPathOf(fixture.generator),
+          ),
+        ),
+      ].sort(),
     ).toEqual(
       Object.values(CREATE_GENERATORS)
         .flatMap((binding) => binding.paths as readonly string[])

package/src/capabilities/create/mount.ts

@@ -47,9 +47,9 @@ import type { Task } from "@canonical/task";
 import { type Command, CommanderError } from "commander";
 import { PragmaError } from "../../kernel/error/index.js";
 import { renderErrorForFormat } from "../../kernel/error/renderError.js";
+import { canPrompt } from "../../kernel/interactivity.js";
 import { MUTATION_FLAG_DOCS } from "../../kernel/project/cli/constants.js";
 import {
-  cliIsTTY,
   dispatchPrepared,
   type MutationFlags,
 } from "../../kernel/project/cli/dispatch.js";
@@ -177,7 +177,7 @@ export function explicitLeafAnswers(
  * The mount's mode resolution — `decideInteraction` over the leaf's five
  * inputs, with the TTY fact INJECTED so the resolution is testable with
  * `tty: true` (no suite can drive a real TTY through a subprocess). The
- * action calls it with {@link cliIsTTY} — the same exported H3 gate the
+ * action calls it with {@link canPrompt} — the same exported H3 gate the
  * kernel's interaction context reads — so the mount and `runCreate` can
  * never disagree about interactivity.
  */
@@ -280,7 +280,7 @@ export function mountCreateTree(parent: Command, host: CliMountHost): void {
         generator.prompts,
         explicit,
         mutation,
-        cliIsTTY(),
+        canPrompt(),
       );
       if (mode === "refuse") {
         writeRefusal(

package/src/capabilities/distribution.parity.test.ts

@@ -30,6 +30,10 @@ if (!standardPack) {
 const CS = "http://pragma.canonical.com/codestandards#";
 const PREFIXES = {
   cs: CS,
+  // The store the fixture builds is queried with the story queries verbatim,
+  // and the category roll-up names `skos:broader` — a CORE prefix on the real
+  // build path (`buildPackPrefixes`), which this in-memory helper does not use.
+  skos: "http://www.w3.org/2004/02/skos/core#",
   owl: "http://www.w3.org/2002/07/owl#",
   rdfs: "http://www.w3.org/2000/01/rdf-schema#",
   xsd: "http://www.w3.org/2001/XMLSchema#",

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

@@ -0,0 +1,49 @@
+/**
+ * Covers the two things `checkNodeVersion` owns beyond the range comparison:
+ * the shape of the CheckResult, and that the failure path quotes the declared
+ * range rather than a number of its own. The range logic itself is pinned in
+ * `isSupportedNodeVersion.test.ts`.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
+import { checkNodeVersion } from "./checkNodeVersion.js";
+
+/** Swap `process.versions.node`, which is read-only in the normal way. */
+function withNodeVersion(version: string) {
+  vi.spyOn(process, "versions", "get").mockReturnValue({
+    ...process.versions,
+    node: version,
+  });
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("checkNodeVersion — reports against the declared range", () => {
+  it("passes on a supported version and reports it", async () => {
+    withNodeVersion("24.18.1");
+    const result = await checkNodeVersion();
+    expect(result).toEqual({
+      name: "Node version",
+      status: "pass",
+      detail: "v24.18.1",
+    });
+  });
+
+  it("fails on an unsupported version and quotes the declared range", async () => {
+    withNodeVersion("20.19.0");
+    const result = await checkNodeVersion();
+    expect(result.status).toBe("fail");
+    expect(result.detail).toContain("v20.19.0");
+    // The range must come from the manifest, never from a literal in the check.
+    expect(result.detail).toContain(SUPPORTED_NODE_RANGE);
+    expect(result.remedy).toContain(SUPPORTED_NODE_RANGE);
+  });
+
+  it("fails inside the 23.0-23.5 window the range excludes", async () => {
+    withNodeVersion("23.2.0");
+    expect((await checkNodeVersion()).status).toBe("fail");
+  });
+});

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

@@ -1,25 +1,29 @@
+import { SUPPORTED_NODE_RANGE } from "../../../constants.js";
 import type { CheckResult } from "../types.js";
-
-const MIN_NODE_MAJOR = 20;
+import { isSupportedNodeVersion } from "./isSupportedNodeVersion.js";
 
 /**
- * Check that the Node.js major version is at least {@link MIN_NODE_MAJOR}.
+ * Check that the running Node.js version satisfies this package's declared
+ * `engines.node` range.
+ *
+ * The floor is a property of the manifest, not of this file: a check that
+ * hardcodes its own number can disagree with the range the package publishes,
+ * and a consumer then passes a check the install contract would have failed.
  *
  * @returns A CheckResult with the current version and pass/fail status.
  * @note Impure — reads `process.versions`.
  */
 export async function checkNodeVersion(): Promise<CheckResult> {
   const version = process.versions.node;
-  const major = Number.parseInt(version.split(".")[0] ?? "0", 10);
 
-  if (major >= MIN_NODE_MAJOR) {
+  if (isSupportedNodeVersion(version)) {
     return { name: "Node version", status: "pass", detail: `v${version}` };
   }
 
   return {
     name: "Node version",
     status: "fail",
-    detail: `v${version} (requires >= ${MIN_NODE_MAJOR})`,
-    remedy: `Install Node.js >= ${MIN_NODE_MAJOR}`,
+    detail: `v${version} (requires ${SUPPORTED_NODE_RANGE})`,
+    remedy: `Install Node.js ${SUPPORTED_NODE_RANGE}`,
   };
 }

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

@@ -60,6 +60,51 @@ function ignoredSuffix(items: readonly CheckItem[]): string {
   return ` · ${items.length} ${items.length === 1 ? "story" : "stories"} ignored`;
 }
 
+/**
+ * The answering pack's provenance, one item per pack it was built from.
+ *
+ * `sourceRef` is a single comma-joined string — `@canonical/design-system@git:
+ * d6d8a6c8268cf2bd103e956a2540d6e36bd08d72, @canonical/anatomy-dsl@npm:0.2.2,
+ * …` — and printing it whole put four packs and two forty-character SHAs on one
+ * line, in a report whose every other multi-part check (`mcp`, `harnesses`)
+ * uses the sub-item mechanism. Provenance is the thing a reader is here for
+ * when they read this line at all: which revision of which pack answered.
+ *
+ * The scheme (`git`/`npm`/`self`/`file`) is kept because it says how to move
+ * the pin, and a git hash is cut to the seven characters every other tool in
+ * this workflow shows. A ref that does not parse is passed through whole rather
+ * than dropped — an unreadable provenance is still provenance, and hiding it
+ * would be the one failure this check exists to prevent.
+ *
+ * @param sourceRef - The manifest's comma-joined provenance string.
+ * @returns One passing item per pack, in the order the pack records them.
+ */
+function packItems(sourceRef: string): CheckItem[] {
+  return sourceRef
+    .split(",")
+    .map((ref) => ref.trim())
+    .filter((ref) => ref !== "")
+    .map((ref) => {
+      const parsed = /^(.+)@(git|npm|self|file|link):(.+)$/.exec(ref);
+      if (parsed === null) return { label: ref, status: "pass" as const };
+      const [, pack, scheme, revision] = parsed as unknown as [
+        string,
+        string,
+        string,
+        string,
+      ];
+      const short =
+        scheme === "git" && /^[0-9a-f]{40}$/.test(revision)
+          ? revision.slice(0, 7)
+          : revision;
+      return {
+        label: pack,
+        detail: `${scheme} ${short}`,
+        status: "pass" as const,
+      };
+    });
+}
+
 /**
  * Report which pack answers reads, its provenance, and its entity total.
  *
@@ -89,13 +134,30 @@ export async function checkPackageRefs(
   // The pack DOES answer reads, so the check itself passes; the ignored stories
   // are failing sub-items under it. (A `warn` status would ripple through the
   // renderer and the DoctorData counts to buy an icon.)
-  const items = await ignoredStoryItems(decision);
-  const suffix = ignoredSuffix(items);
+  const ignored = await ignoredStoryItems(decision);
+  const suffix = ignoredSuffix(ignored);
+  const sourceRef =
+    decision.kind === "embedded"
+      ? embeddedManifest().sourceRef
+      : (readManifest(decision.dir)?.sourceRef ?? "");
+  // Packs first, then anything wrong with them: the composition is the answer to
+  // "which revision am I reading", and a failing story is a note about one of
+  // the rows above it.
+  const packs = packItems(sourceRef);
+  const items = [...packs, ...ignored];
+  const composition = `${packs.length} ${packs.length === 1 ? "pack" : "packs"}, ${entities} entities${suffix}`;
+
   if (decision.kind === "embedded") {
     return {
       name,
       status: "pass",
-      detail: `embedded snapshot @ ${embeddedManifest().sourceRef} — ${entities} entities${suffix} · \`${BIN_NAME} sources update\` to build from the configured packs`,
+      // The update hint stays in the DETAIL rather than moving to `remedy`:
+      // the renderer prints a remedy only where there is something to fix or
+      // to finish, and a snapshot that is answering reads correctly is
+      // neither. "shipped with the CLI" rather than "embedded snapshot" — the
+      // reader needs to know where these packs came from, not what the build
+      // calls the artefact.
+      detail: `shipped with the CLI — ${composition} · run \`${BIN_NAME} sources update\` to build from your own configured packs instead`,
       ...(items.length > 0 ? { items } : {}),
     };
   }
@@ -103,7 +165,10 @@ export async function checkPackageRefs(
   return {
     name,
     status: "pass",
-    detail: `${manifest?.sourceRef ?? decision.contentHash.slice(0, 12)} — ${entities} entities, built ${manifest?.createdAt ?? "?"}${suffix}`,
+    detail:
+      packs.length > 0
+        ? `built ${manifest?.createdAt ?? "?"} — ${composition}`
+        : `${decision.contentHash.slice(0, 12)} — ${composition}, built ${manifest?.createdAt ?? "?"}`,
     ...(items.length > 0 ? { items } : {}),
   };
 }

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

@@ -94,10 +94,12 @@ function wireZfunc(): void {
 describe("checkShellCompletions — effect test (gate 1)", () => {
   it("passes the resolver gate: `pragma <TAB>` resolves nouns", async () => {
     // No shell → skip, but only AFTER the resolver answered — the detail proves
-    // the effect test ran and succeeded.
+    // the effect test ran and succeeded. The proof is the same fact worded for
+    // a reader ("pragma answers `<TAB>`") rather than as "resolver OK": the
+    // gate it pins is unchanged, only the sentence that reports it.
     const result = await check(tmp(), null);
     expect(result.status).toBe("skip");
-    expect(result.detail).toMatch(/resolver OK/);
+    expect(result.detail).toMatch(/answers `<TAB>`/);
   });
 });
 
@@ -137,7 +139,7 @@ describe("checkShellCompletions — install probe (gate 2)", () => {
     const result = await check(tmp(), "bash");
     expect(result.status).toBe("pass");
     expect(result.detail).toMatch(
-      /bash \(the shell in use\) up to date and resolving/,
+      /bash \(the shell you are in\) — installed, up to date, and completing/,
     );
   });
 
@@ -200,7 +202,7 @@ describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
     const result = await check(tmp(), "zsh");
     expect(result.status).toBe("pass");
     expect(result.detail).toMatch(
-      /zsh \(the shell in use\) up to date and resolving/,
+      /zsh \(the shell you are in\) — installed, up to date, and completing/,
     );
   });
 });

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

@@ -126,7 +126,7 @@ export async function checkShellCompletions(
     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.`,
     };
   }
@@ -134,7 +134,7 @@ export async function checkShellCompletions(
     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.",
     };
   }
@@ -147,7 +147,7 @@ export async function checkShellCompletions(
     return {
       name: NAME,
       status: "skip",
-      detail: `resolver OK; the running shell cannot be identified (SHELL names ${d.detection.login}, the login shell)`,
+      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.`,
     };
   }
@@ -155,7 +155,7 @@ export async function checkShellCompletions(
     return {
       name: NAME,
       status: "skip",
-      detail: "resolver OK; no bash, zsh, or fish in this process tree",
+      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
@@ -174,7 +174,7 @@ export async function checkShellCompletions(
       status: installed ? "fail" : "available",
       detail: installed
         ? `${shell} script installed, but \`${BIN_NAME}\` is not on PATH — the script cannot run it`
-        : `resolver OK; \`${BIN_NAME}\` is not on PATH — an installed 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.`,
     };
   }
@@ -186,7 +186,7 @@ export async function checkShellCompletions(
     return {
       name: NAME,
       status: "available",
-      detail: `resolver OK; ${shell} script not installed`,
+      detail: `${BIN_NAME} answers \`<TAB>\`; the ${shell} script is not installed`,
       remedy: INSTALL_REMEDY,
     };
   }
@@ -194,7 +194,7 @@ export async function checkShellCompletions(
     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,
     };
   }
@@ -212,6 +212,6 @@ export async function checkShellCompletions(
   return {
     name: NAME,
     status: "pass",
-    detail: `${shell} (the shell in use) 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);
+  });
+});