@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -1,73 +1,107 @@
 /**
- * Doctor check: report how each configured semantic package resolves.
+ * Doctor check: report which pack answers this project's reads.
  *
- * ADAPTED for v2: the old local>git>bundled loader chain is retired — resolution
- * now flows through `sources update` into `pragma.lock.json` + the cached pack.
- * This check reads the lock (which packages resolved) and the storeless pack
- * index (the entity total), never booting the store. An absent lock with
- * configured packages is the "run `sources update`" case.
+ * It switches on the ONE boot decision ({@link resolveSources}) rather than
+ * re-deriving it from config, so doctor can never call an install healthy that
+ * every read would fail. That is the whole point of the check: a project that
+ * configured its own packs and never built them reports `fail` with the update
+ * remedy — not a pass listing the distribution's packs it is not reading.
+ * Storeless throughout: the pointer, the manifest, and the entity index are
+ * read off disk, never through a store session.
+ *
+ * It also names every read story that pack carries but cannot use. Those are
+ * DROPPED at dispatch rather than thrown (a third-party story must never break
+ * a command), so doctor is where the user finds out — and it goes through the
+ * same `validateStories` the dispatch path uses, so the two can never disagree.
  */
 
+import { BIN_NAME } from "../../../constants.js";
 import {
   entityTotal,
   readPackIndex,
 } from "../../../kernel/completion/entitySource.js";
-import type { PackageEntry } from "../../../kernel/config/types.js";
-import { readLock } from "../../../kernel/runtime/lock.js";
+import { validateStories } from "../../../kernel/packs/collect.js";
+import { embeddedManifest } from "../../../kernel/runtime/graphpack/embedded.js";
+import { readManifest } from "../../../kernel/runtime/graphpack/manifest.js";
+import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
+import type { SourcesDecision } from "../../../kernel/runtime/resolveSources.js";
+import { resolveSources } from "../../../kernel/runtime/resolveSources.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import type { CheckItem, CheckResult } from "../types.js";
 
-const entryName = (entry: PackageEntry): string =>
-  typeof entry === "string" ? entry : entry.name;
+/**
+ * The stories the answering pack carries but cannot use, as check items.
+ *
+ * The registry is reached through a RUNTIME dynamic import (as
+ * `collectColophon` does) so the static `capabilities/index → doctorModule →
+ * checkPackageRefs → capabilities/index` cycle can never form.
+ *
+ * @param decision - The boot decision the check already resolved.
+ * @returns One failing item per ignored story, in declaration order.
+ * @note Impure — reads the answering pack's `stories.json`.
+ */
+async function ignoredStoryItems(
+  decision: SourcesDecision,
+): Promise<CheckItem[]> {
+  const { capabilities } = await import("../../index.js");
+  const { problems } = validateStories(activeStories(decision), capabilities);
+  return problems.map((problem) => ({
+    label: problem.source,
+    detail: problem.message,
+    status: "fail" as const,
+  }));
+}
+
+/** ` · N story/ies ignored` for a headline, or nothing when all are usable. */
+function ignoredSuffix(items: readonly CheckItem[]): string {
+  if (items.length === 0) return "";
+  return ` · ${items.length} ${items.length === 1 ? "story" : "stories"} ignored`;
+}
 
 /**
- * Report package resolution status against the lock and the entity total.
+ * Report which pack answers reads, its provenance, and its entity total.
  *
  * @param rt - The per-invocation runtime.
- * @returns A CheckResult with a per-package breakdown.
- * @note Impure — reads config, the lock, and the pack index from disk.
+ * @returns A CheckResult naming the answering pack, or the failure to build one.
+ * @note Impure — reads config, the active-pack pointer, and the pack index.
  */
 export async function checkPackageRefs(
   rt: PragmaRuntime,
 ): Promise<CheckResult> {
-  const entries = (await rt.loadConfig()).config.packages ?? [];
-  const lock = readLock(rt.cwd);
-  const index = readPackIndex(rt.cwd);
-  const totalEntities = index ? entityTotal(index) : 0;
+  const decision = resolveSources(await rt.loadConfig(), rt.cwd);
+  // The display says "packs" (config declarations); the file/function keep
+  // "Package" (npm/git resolution vocabulary).
+  const name = "pack refs";
 
-  if (entries.length === 0) {
+  if (decision.kind === "unavailable") {
     return {
-      name: "package refs",
-      status: "pass",
-      detail: `no packages configured — the embedded pack answers reads (${totalEntities.toLocaleString()} entities)`,
+      name,
+      status: "fail",
+      detail: decision.reason,
+      remedy: `${BIN_NAME} sources update`,
     };
   }
 
-  const items: CheckItem[] = [];
-  let unresolved = 0;
-  for (const entry of entries) {
-    const name = entryName(entry);
-    const packEntry = lock?.packs.find((pack) => pack.name === name);
-    if (packEntry) {
-      items.push({
-        label: name,
-        status: "pass",
-        detail: `resolved ${packEntry.resolved}`,
-      });
-    } else {
-      items.push({ label: name, status: "fail", detail: "not in the lock" });
-      unresolved += 1;
-    }
+  const index = readPackIndex(decision);
+  const entities = (index ? entityTotal(index) : 0).toLocaleString();
+  // 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);
+  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`,
+      ...(items.length > 0 ? { items } : {}),
+    };
   }
-
-  const ok = lock !== undefined && unresolved === 0;
+  const manifest = readManifest(decision.dir);
   return {
-    name: "package refs",
-    status: ok ? "pass" : "fail",
-    detail: ok
-      ? `${entries.length} package(s) resolved · ${totalEntities.toLocaleString()} entities`
-      : `${unresolved} of ${entries.length} package(s) not resolved`,
-    items,
-    ...(ok ? {} : { remedy: "pragma sources update" }),
+    name,
+    status: "pass",
+    detail: `${manifest?.sourceRef ?? decision.contentHash.slice(0, 12)} — ${entities} entities, built ${manifest?.createdAt ?? "?"}${suffix}`,
+    ...(items.length > 0 ? { items } : {}),
   };
 }

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

@@ -1,9 +1,10 @@
+import { BIN_NAME } from "../../../constants.js";
 import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
 import { detectInstallSource } from "../../shared/packageManager.js";
 import type { CheckResult } from "../types.js";
 
 /**
- * Report the pragma version and how it was installed. Always passes — purely
+ * Report the CLI version and how it was installed. Always passes — purely
  * informational.
  *
  * @param rt - The per-invocation runtime (for `version`).
@@ -15,7 +16,7 @@ export async function checkPragmaVersion(
 ): Promise<CheckResult> {
   const install = detectInstallSource();
   return {
-    name: "pragma version",
+    name: `${BIN_NAME} version`,
     status: "pass",
     detail: `v${rt.version} (installed via ${install.label})`,
   };

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

@@ -1,19 +1,28 @@
 /**
  * `checkShellCompletions` — the doctor check that verifies completions are
- * installed AND functional.
+ * installed AND up to date AND functional.
  *
  * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
- * the resolver effect test, the real install-path probe, and the zsh fpath
- * activation gate — are deterministic. The effect test (gate 1) drives the real
+ * the resolver effect test, the install probe, and the zsh fpath activation
+ * gate — are deterministic. The effect test (gate 1) drives the real
  * `runComplete` resolver; the install/fpath gates write real files under the
  * temp HOME rather than mocking the fs.
+ *
+ * Gate 2 compares BYTES, not existence, so the "installed" cases here write the
+ * real `emitScripts(capabilities)[shell]` body. A file that merely exists is
+ * now the failing case, and it has its own test — as does the boundary on the
+ * other side, where a per-project `completion` config must NOT be able to
+ * condemn the one global script.
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { completionScriptPath } from "../../setup/shell.js";
+import { emitScripts } from "../../../kernel/completion/emitScripts.js";
+import { capabilities } from "../../index.js";
+import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import { completionScriptPath, type ShellId } from "../../setup/shell.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
 
 const roots: string[] = [];
@@ -38,11 +47,16 @@ afterEach(() => {
   roots.length = 0;
 });
 
-/** Write the (empty) completion script to the shell's real install path. */
-function installScript(shell: "zsh" | "bash" | "fish"): void {
+/** Write `body` to the shell's real install path. */
+function writeScript(shell: ShellId, body: string): void {
   const path = completionScriptPath(shell);
   mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, "# stub\n");
+  writeFileSync(path, body);
+}
+
+/** Install the script `setup completions` would write for this shell. */
+function installScript(shell: ShellId): void {
+  writeScript(shell, emitScripts(capabilities)[shell]);
 }
 
 /** Write a `.zshrc` that puts ~/.zfunc on fpath. */
@@ -73,20 +87,56 @@ describe("checkShellCompletions — install probe (gate 2)", () => {
     expect(result.remedy).toBe("pragma setup completions");
   });
 
-  it("passes for bash once the script exists at its real path", async () => {
+  it("passes for bash once the up-to-date script is at its real path", async () => {
     process.env.SHELL = "/usr/bin/bash";
     installScript("bash");
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/bash installed and resolving/);
+    expect(result.detail).toMatch(/bash up to date and resolving/);
   });
 
-  it("passes for fish once the script exists at its real path", async () => {
+  it("passes for fish once the up-to-date script is at its real path", async () => {
     process.env.SHELL = "/usr/bin/fish";
     installScript("fish");
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
   });
+
+  it("fails when the installed script is out of date", async () => {
+    // Reproduced against the compiled binary before this was fixed: overwrite
+    // the installed script with junk and `doctor` still reported
+    // "✓ Shell completions: bash installed and resolving (19 nouns)", while
+    // `setup completions` in the same breath said "Updating bash completions".
+    // Every user upgrading across a grammar change lands here: the old script
+    // offers the old nouns and misses the new ones, and doctor is the one
+    // command whose job is to say so.
+    process.env.SHELL = "/usr/bin/bash";
+    writeScript("bash", "# STALE JUNK\n");
+    const result = await checkShellCompletions(tmp());
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/out of date/);
+    expect(result.remedy).toBe("pragma setup completions");
+  });
+
+  it("does NOT condemn the global script for one project's `completion` config", async () => {
+    // The script is ONE file per user; `completion` config is layered per
+    // project. Comparing the global file against only THIS directory's body
+    // made `doctor`'s verdict flip with `cd`: reproduced against the real
+    // check, a project declaring `minChars: 5` passed in its own directory and
+    // failed in every other, and running the offered remedy there moved the
+    // failure back rather than closing it. The first assertion is the
+    // discriminator — this project really does ask for a different body — so
+    // deleting the config write below turns the test red.
+    process.env.SHELL = "/usr/bin/bash";
+    installScript("bash");
+    const cwd = tmp();
+    writeFileSync(
+      join(cwd, "pragma.config.ts"),
+      "export default { completion: { minChars: 5 } };\n",
+    );
+    expect((await detectCompletions(cwd)).state).toBe("stale");
+    expect((await checkShellCompletions(cwd)).status).toBe("pass");
+  });
 });
 
 describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
@@ -106,6 +156,6 @@ describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
     wireZfunc();
     const result = await checkShellCompletions(tmp());
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/zsh installed and resolving/);
+    expect(result.detail).toMatch(/zsh up to date and resolving/);
   });
 });

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

@@ -1,20 +1,48 @@
-import { existsSync, readFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { BIN_NAME } from "../../../constants.js";
 import {
+  emitScripts,
   indexCompletionEnv,
   runComplete,
 } from "../../../kernel/completion/index.js";
 import { capabilities } from "../../index.js";
-import {
-  activationHint,
-  completionScriptPath,
-  detectShell,
-} from "../../setup/shell.js";
+import { detectCompletions } from "../../setup/operations/setupCompletions.js";
+import { activationHint, type ShellId } from "../../setup/shell.js";
 import type { CheckResult } from "../types.js";
 
 const NAME = "Shell completions";
 
+/** The one remedy for an absent or out-of-date script. */
+const INSTALL_REMEDY = `${BIN_NAME} setup completions`;
+
+/**
+ * Whether the installed script is the config-free emit — the body
+ * `setup completions` writes when no `completion` config tunes it.
+ *
+ * The completion script is ONE file per user, but the `completion` config it is
+ * rendered from is layered per project. So `detectCompletions(cwd)`'s `stale`
+ * means only "not what THIS directory would write", and on its own it would let
+ * any project that tunes `minChars` call a globally-correct script out of date
+ * from every other directory — a `doctor` verdict that flips with `cd`, and a
+ * remedy that just moves the failure to the project you came from. A script
+ * that matches neither this project's body nor the untuned one is the one that
+ * is genuinely stale.
+ *
+ * @param path - The install path.
+ * @param shell - The detected shell.
+ * @returns Whether the file there is byte-identical to the untuned emit.
+ * @note Impure — reads the install path. An unreadable file counts as `false`.
+ */
+function isUntunedScript(path: string, shell: ShellId): boolean {
+  try {
+    return readFileSync(path, "utf-8") === emitScripts(capabilities)[shell];
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Whether the user's `.zshrc` puts `~/.zfunc` on `$fpath` — the activation step
  * `setup completions` cannot perform for the user. zsh loads nothing from
@@ -53,23 +81,28 @@ async function completeProbe(cwd: string): Promise<number> {
 }
 
 /**
- * Check that shell completions are installed AND functional.
+ * Check that shell completions are installed AND up to date AND functional.
  *
  * Three gates, in order:
  * 1. The resolver answers (`completeProbe` drives `runComplete` end to end) —
  *    the effect every installed script depends on. A failure here is a real
  *    regression, so it fails even when nothing is installed.
- * 2. The script file exists at the shell's real install path (`shell.ts`) —
- *    NOT a `"pragma"` substring in an RC file, which `setup completions` never
- *    writes.
+ * 2. The installed script is present AND is a script `setup completions` would
+ *    write. Bytes, not existence: a file that merely exists proves nothing — a
+ *    user upgrading across a grammar change keeps the old script, loses the
+ *    moved nouns from TAB, and used to be told everything was fine. The path
+ *    and this project's body come from `detectCompletions`, the ONE owner of
+ *    that decision; {@link isUntunedScript} is what keeps a per-project
+ *    `completion` config from condemning a global file (see its docblock).
  * 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 (for the resolver's entity seam).
- * @returns A CheckResult: pass (installed + wired + answering), fail (with the
+ * @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, `.zshrc`, and drives the
- *   storeless resolver.
+ * @note Impure — reads `$SHELL`, the install path, the config layers, `.zshrc`,
+ *   and drives the storeless resolver.
  */
 export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   // 1. Effect test: the resolver the scripts delegate to must actually answer.
@@ -82,34 +115,41 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
       name: NAME,
       status: "fail",
       detail: `completion resolver failed: ${reason}`,
-      remedy: "Report this as a bug — `pragma __complete` should never throw.",
+      remedy: `Report this as a bug — \`${BIN_NAME} __complete\` should never throw.`,
     };
   }
   if (candidates === 0) {
     return {
       name: NAME,
       status: "fail",
-      detail: "completion resolver returned no candidates for `pragma <TAB>`",
+      detail: `completion resolver returned no candidates for \`${BIN_NAME} <TAB>\``,
       remedy: "Report this as a bug — the noun context is always non-empty.",
     };
   }
 
-  // 2. The script file exists at the shell's real install path.
-  const shell = detectShell();
-  if (!shell) {
+  // 2. The installed script is a script `setup completions` would write.
+  const { shell, path, state } = await detectCompletions(cwd);
+  if (shell === null || path === null) {
     return {
       name: NAME,
       status: "skip",
       detail: "resolver OK; shell not detected ($SHELL unset)",
     };
   }
-  const path = completionScriptPath(shell);
-  if (!existsSync(path)) {
+  if (state === "absent") {
     return {
       name: NAME,
       status: "fail",
       detail: `resolver OK; ${shell} script not installed`,
-      remedy: "pragma setup completions",
+      remedy: INSTALL_REMEDY,
+    };
+  }
+  if (state === "stale" && !isUntunedScript(path, shell)) {
+    return {
+      name: NAME,
+      status: "fail",
+      detail: `resolver OK; ${shell} script at ${path} is out of date`,
+      remedy: INSTALL_REMEDY,
     };
   }
 
@@ -126,6 +166,6 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
   return {
     name: NAME,
     status: "pass",
-    detail: `${shell} installed and resolving (${candidates} nouns)`,
+    detail: `${shell} up to date and resolving (${candidates} nouns)`,
   };
 }

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

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import type { DetectedHarness } from "@canonical/harnesses";
 import { detectHarnesses } from "@canonical/harnesses";
 import { runTask } from "@canonical/task/node";
+import { BIN_NAME } from "../../../constants.js";
 import type { CheckResult } from "../types.js";
 
 /**
@@ -21,7 +22,7 @@ export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
       name: "Skills symlinked",
       status: "fail",
       detail: "harness detection failed",
-      remedy: "pragma setup skills",
+      remedy: `${BIN_NAME} setup skills`,
     };
   }
 
@@ -55,6 +56,6 @@ export async function checkSkillsSymlinked(cwd: string): Promise<CheckResult> {
     name: "Skills symlinked",
     status: "fail",
     detail: `missing for ${missing.join(", ")}`,
-    remedy: "pragma setup skills",
+    remedy: `${BIN_NAME} setup skills`,
   };
 }

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

@@ -0,0 +1,42 @@
+/**
+ * `deriveBand` — band a doctor check by the harnesses it actually found.
+ *
+ * Fixtures wrap REAL harness definitions (via `findHarnessById`, no casts), so
+ * the scope→band mapping is exercised against the true `scope` fields: the
+ * regression this guards is a global-scope harness (Windsurf) being mislabeled
+ * PROJECT by a static per-name guess.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { findHarnessById } from "@canonical/harnesses";
+import { describe, expect, it } from "vitest";
+import { deriveBand } from "./deriveBand.js";
+
+/** A minimal {@link DetectedHarness} over a real definition (no `as` casts). */
+function detect(id: string): DetectedHarness {
+  const harness = findHarnessById(id);
+  if (!harness) throw new Error(`unknown harness fixture: ${id}`);
+  return { harness, confidence: "high", configExists: true, configPath: "x" };
+}
+
+describe("deriveBand", () => {
+  it("bands a project-scope harness (Cursor) as project", () => {
+    expect(deriveBand([detect("cursor")])).toBe("project");
+  });
+
+  it("bands a global-scope harness (Windsurf) as global — the fixed mislabel", () => {
+    expect(deriveBand([detect("windsurf")])).toBe("global");
+  });
+
+  it("bands a dual-scope harness (Claude Code) by its default band (project)", () => {
+    expect(deriveBand([detect("claude-code")])).toBe("project");
+  });
+
+  it("leaves a set spanning BOTH bands unbanded (general, not mislabeled)", () => {
+    expect(deriveBand([detect("cursor"), detect("windsurf")])).toBeUndefined();
+  });
+
+  it("leaves an empty set unbanded", () => {
+    expect(deriveBand([])).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,28 @@
+/**
+ * Derive a doctor check's config band from the harnesses it actually found,
+ * rather than a static per-check-name guess. The aggregate MCP checks read each
+ * harness's DEFAULT-band file (`defaultBandOf` — the home config for a
+ * global-only harness like Windsurf, the project file otherwise), so the band a
+ * finding belongs to is exactly that default band.
+ */
+
+import type { DetectedHarness } from "@canonical/harnesses";
+import { defaultBandOf } from "@canonical/harnesses";
+import type { ScopeBand } from "../types.js";
+
+/**
+ * The single config band a set of detected harnesses shares, or `undefined` when
+ * the set is empty or genuinely spans BOTH bands. A two-band finding stays
+ * unbanded (rendered in the general section) instead of being mislabeled as one
+ * band — faithful to the two-band model: band by what was found, never a guess.
+ *
+ * @param harnesses - The detected harnesses the check reports on.
+ * @returns The shared {@link ScopeBand}, or `undefined` when none/mixed.
+ */
+export function deriveBand(
+  harnesses: readonly DetectedHarness[],
+): ScopeBand | undefined {
+  const bands = new Set<ScopeBand>();
+  for (const detected of harnesses) bands.add(defaultBandOf(detected.harness));
+  return bands.size === 1 ? bands.values().next().value : undefined;
+}