@canonical/pragma-cli 0.35.0 → 0.36.0

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);
+  });
+});