@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -0,0 +1,164 @@
+/**
+ * PROTECTED — the shipped-entry `create` guard.
+ *
+ * Spawns the EMITTED entry the published package points at
+ * (`node dist/src/bin.js`) and asserts every `create` noun writes a tree
+ * BYTE-IDENTICAL to a source run of the same generator (`bun src/bin.ts …`).
+ * The source run is the reference: it reads the `.ejs` templates from disk with
+ * no indirection.
+ *
+ * WHAT THIS REPLACES. Until the distribution stopped shipping a
+ * `bun build --compile` executable, this guard covered `create component` only,
+ * and its sibling describe pinned the REFUSAL of `create package` /
+ * `create application`: those generators call `template({ source })`, summon-core
+ * fell through to `readFile(options.source)`, and inside the binary's virtual
+ * filesystem that died with `ENOENT … /$bunfs/templates/package.json.ejs` after
+ * `mkdir` had already run — a half-made package on the user's disk. The gate
+ * existed to turn that crash into a clean refusal.
+ *
+ * There is no virtual filesystem now. Every generator's templates are real
+ * files under its own package, so all three nouns run from the shipped entry and
+ * all three are asserted here. THE REFUSAL CASES ARE GONE ON PURPOSE: a test
+ * asserting `create package` refuses would now be asserting a defect.
+ *
+ * The svelte + lit cases stay load-bearing: `types.ts.ejs` / `index.ts.ejs` /
+ * `styles.css.ejs` / `stories.ts.ejs` exist in react/, svelte/ AND lit/, so a
+ * basename-matching regression could emit the WRONG framework's file. A wrong
+ * file differs from the source run → red here.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../../../../../..");
+const cliNextDir = join(repoRoot, "packages/cli/pragma");
+const sourceEntry = join(cliNextDir, "src/bin.ts");
+const shippedEntry = join(cliNextDir, "dist/src/bin.js");
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-shipped-"));
+
+// `dist/` is provisioned by `testing/perf/globalSetup.ts`, which re-emits it
+// whenever it is missing or older than `src/**`, `scripts/**`, `pragma.conf.ts`
+// or `package.json` — so these tests exercise the current emit without a second
+// `beforeAll` writing `dist/` in place while another worker is spawning it.
+
+/** Read a directory tree into a sorted map of relative path → contents. */
+function snapshot(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string, base: string): void => {
+    for (const entry of readdirSync(d, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(d, entry.name), rel);
+      else out.set(rel, readFileSync(join(d, entry.name), "utf-8"));
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+/**
+ * The create invocations under guard — a LITERAL table, deliberately not derived
+ * from `create`'s own declaration, so dropping a noun from the surface turns
+ * this red rather than silently shrinking the guard.
+ *
+ * No case installs dependencies (`runInstall` defaults false), so every tree is
+ * generator output alone and byte-comparable.
+ */
+const CASES: ReadonlyArray<{ label: string; args: readonly string[] }> = [
+  ...(["react", "svelte", "lit"] as const).map((framework) => ({
+    label: `component ${framework}`,
+    // The framework is a PATH SEGMENT, not a flag — `create` mirrors summon's
+    // own tree (`summon component react <path>`), so the two CLIs take the
+    // same argv.
+    args: ["create", "component", framework, "src/components/Widget", "--yes"],
+  })),
+  {
+    label: "package",
+    args: ["create", "package", "--name", "@canonical/probe", "--yes"],
+  },
+  {
+    label: "application",
+    // `react` is a path segment here too — the declared binding is
+    // `application/react`, and the tree mirrors summon's.
+    args: ["create", "application", "react", "probeapp", "--yes"],
+  },
+];
+
+/** Run one create invocation in its own cwd and snapshot what it wrote. */
+function create(
+  command: string,
+  prefix: readonly string[],
+  args: readonly string[],
+): Map<string, string> {
+  const dir = freshCwd();
+  execFileSync(command, [...prefix, ...args], { cwd: dir, stdio: "pipe" });
+  return snapshot(dir);
+}
+
+describe("shipped pragma create (PROTECTED)", () => {
+  for (const { label, args } of CASES) {
+    it(`${label}: shipped entry ≡ source run, byte-for-byte`, () => {
+      // (1) The shipped entry, exactly as a consumer's `pragma` runs it.
+      const shipped = create(process.execPath, [shippedEntry], args);
+      // (2) A source run — the reference output.
+      const source = create("bun", [sourceEntry], args);
+
+      // Wrote something. Before the distribution stopped shipping a compiled
+      // binary, `package` and `application` wrote NOTHING here — they refused.
+      expect(shipped.size).toBeGreaterThan(0);
+      // Same file set …
+      expect([...shipped.keys()].sort()).toEqual([...source.keys()].sort());
+      // … and byte-identical contents.
+      for (const [path, content] of shipped) {
+        expect(source.get(path), `content of ${path}`).toBe(content);
+      }
+    }, 180_000);
+  }
+});
+
+/**
+ * PROTECTED — the shipped-entry READ guard (U1-orig).
+ *
+ * A READ command (`block list`, `--help`) never calls a generator's
+ * `generate()`, so — with the generators loading their templates LAZILY on first
+ * `generate()` rather than at module-eval — it must never touch a `.ejs` at all.
+ * This is the exact gap the create-only smoke above missed: the component
+ * generators used to load templates via a top-level `await`, so a READ crashed
+ * with `Template not found`. The lazy load makes a READ template-free, and this
+ * pins it at the process boundary where an eager load would resurface.
+ */
+describe("shipped pragma READ smoke (PROTECTED)", () => {
+  // A cold store cleanly reports STORE_UNAVAILABLE (exit 3); `--help` never needs
+  // a store (exit 0). Both fully exercise startup + dispatch — the phase where an
+  // eager generator template load would have crashed — without a store or writes.
+  const READS: ReadonlyArray<{
+    args: readonly string[];
+    okExit: readonly number[];
+  }> = [
+    { args: ["block", "list"], okExit: [0, 3] },
+    { args: ["--help"], okExit: [0] },
+  ];
+
+  for (const { args, okExit } of READS) {
+    it(`\`${args.join(" ")}\` runs without a Template-not-found crash`, () => {
+      const result = spawnSync(process.execPath, [shippedEntry, ...args], {
+        cwd: freshCwd(),
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+      // The exact crash the lazy-template fix closes.
+      expect(output).not.toMatch(/Template not found/);
+      // Nor does it collapse to the internal-bug path (the crash's other tell).
+      expect(output).not.toMatch(/Internal error/);
+      // It reaches a clean dispatch outcome, not an uncaught startup crash.
+      expect(okExit).toContain(result.status);
+    }, 30_000);
+  }
+});

package/src/capabilities/create/types.ts

@@ -10,3 +10,23 @@ import type { CREATE_GENERATORS } from "./constants.js";
  * heavy generator imports — into the static graph.
  */
 export type CreateKind = keyof typeof CREATE_GENERATORS;
+
+/**
+ * The REGISTERED CLI spelling of one generator prompt, baked into
+ * `createSurface.generated.ts` at build time (the build derives it with the
+ * same summon-core helpers the mount registers through). Consumers that need
+ * only the spelling — completion tokens, the reference's usage lines — read
+ * this baked record instead of calling the projection, which keeps the
+ * `--help`/`__complete` fast paths free of the registration machinery.
+ */
+export interface PromptCliSyntax {
+  /**
+   * The registered flag token (`--component-path`; a default-true confirm
+   * registers ONLY its `--no-<kebab>` form).
+   */
+  readonly flag: string;
+  /** Whether the registered flag takes a value (`--styles` does not). */
+  readonly takesValue: boolean;
+  /** The prompt name's kebab-case CLI spelling (`componentPath` → `component-path`). */
+  readonly kebabName: string;
+}

package/src/capabilities/distribution.test.ts

@@ -33,12 +33,14 @@ function declaredShape(verb: VerbSpec): Record<string, unknown> {
 }
 
 describe("the distribution's declared stories (PROTECTED)", () => {
-  it("declares exactly the five domain nouns", () => {
+  it("declares exactly the seven domain nouns", () => {
     // Every domain noun is now nothing BUT its story (L-OPEN-9), so a renamed
     // or dropped noun deletes a whole command rather than shrinking one — it
     // must fail HERE.
     expect([...declaredStories.keys()].sort()).toEqual([
       "block",
+      "concept",
+      "implementation",
       "modifier",
       "standard",
       "tier",

package/src/capabilities/distribution.ts

@@ -3,7 +3,7 @@
  *
  * `pragma.conf.ts` declares them on the packs that supply them; this is the ONE
  * place those declarations become capabilities. They come through the SAME door
- * a third-party story does — {@link compilePack} — so the mechanism the CLI
+ * a third-party story does — {@link compileStoryModule} — so the mechanism the CLI
  * offers forks is the mechanism the CLI itself runs on.
  *
  * They are compiled STATICALLY rather than merged at dispatch on purpose: the
@@ -11,7 +11,7 @@
  * `surface/surface.v2.json` freezes the emitted surface, so a noun that only
  * arrived at dispatch would vanish from help and completion on a fresh install.
  * That is affordable because this module is zod-free and pure — `pragma.conf.ts`
- * is inert data and `compilePack` builds specs without touching the store.
+ * is inert data and the compiler builds specs without touching the store.
  *
  * Config- and package-declared stories still OVERRIDE these at dispatch; the
  * `story` marker on each module is what tells `assembleEffectiveModules` which
@@ -19,13 +19,13 @@
  */
 
 import conf from "../../pragma.conf.js";
-import { compilePack } from "../kernel/packs/compile.js";
+import { compileStoryModule } from "../kernel/packs/compile.js";
 import {
   distributionSource,
   type PackDefinition,
 } from "../kernel/packs/types.js";
-import { DEFAULT_PREFIX_MAP } from "../kernel/render/prefixes.js";
-import type { CapabilityModule } from "../kernel/spec/types.js";
+import { DEFAULT_PREFIX_MAP } from "../kernel/render/index.js";
+import type { CapabilityModule } from "../kernel/spec/index.js";
 
 /** The read stories `pragma.conf.ts` declares on its packs, by noun. */
 export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
@@ -45,15 +45,10 @@ export const declaredStories: ReadonlyMap<string, PackDefinition> = new Map(
 export const storyModules: ReadonlyMap<string, CapabilityModule> = new Map(
   [...declaredStories].map(([noun, story]) => [
     noun,
-    {
-      name: noun,
-      story: true,
-      verbs: compilePack(
-        story,
-        distributionSource("pragma.conf.ts"),
-        DEFAULT_PREFIX_MAP,
-      ),
-      colophon: story.colophon,
-    },
+    compileStoryModule(
+      story,
+      distributionSource("pragma.conf.ts"),
+      DEFAULT_PREFIX_MAP,
+    ),
   ]),
 );

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

@@ -1,10 +1,12 @@
 import { BIN_NAME } from "../../../constants.js";
 import { entityTotal } from "../../../kernel/completion/entitySource.js";
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
 import type { CheckResult } from "../types.js";
 
 /**
- * Check that the ke store boots, reporting the entity total and boot time.
+ * Check that the local store boots, reporting the entity total and boot time.
+ * The check is NAMED "store" in the report — the same word every other surface
+ * uses for it; the ke library it boots through is an implementation detail.
  *
  * This is the ONE check that touches the store — it boots the shared lazy store
  * inside a try/catch, so doctor stays storeless-by-default at the dispatch level
@@ -24,15 +26,15 @@ export async function checkKeStore(rt: PragmaRuntime): Promise<CheckResult> {
     const total = entityTotal(session.index);
     const elapsed = Math.round(performance.now() - start);
     return {
-      name: "ke store",
+      name: "store",
       status: "pass",
       detail: `${total.toLocaleString()} entities in ${elapsed}ms`,
     };
   } catch {
     return {
-      name: "ke store",
+      name: "store",
       status: "fail",
-      detail: "failed to boot",
+      detail: "cannot boot",
       remedy: `Ensure design-system packs are configured and run \`${BIN_NAME} sources update\`.`,
     };
   }

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

@@ -20,13 +20,15 @@ import {
   entityTotal,
   readPackIndex,
 } from "../../../kernel/completion/entitySource.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 { validateStories } from "../../../kernel/packs/index.js";
+import {
+  embeddedManifest,
+  readManifest,
+} from "../../../kernel/runtime/graphpack/index.js";
 import { activeStories } from "../../../kernel/runtime/graphpack/stories.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.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";
 
 /**

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

@@ -1,6 +1,6 @@
 import { BIN_NAME } from "../../../constants.js";
-import type { PragmaRuntime } from "../../../kernel/runtime/types.js";
-import { detectInstallSource } from "../../shared/packageManager.js";
+import type { PragmaRuntime } from "../../../kernel/runtime/index.js";
+import { detectInstallSource } from "../../shared/index.js";
 import type { CheckResult } from "../types.js";
 
 /**

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

@@ -2,7 +2,7 @@
  * `checkShellCompletions` — the doctor check that verifies completions are
  * installed AND up to date AND functional.
  *
- * Runs against an isolated HOME and a controlled `$SHELL` so the three gates —
+ * Runs against an isolated HOME and an injected shell so the gates —
  * 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
@@ -22,7 +22,12 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 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 {
+  completionScriptPath,
+  type ShellDetection,
+  type ShellId,
+} from "../../setup/shell.js";
+import type { CheckResult } from "../types.js";
 import { checkShellCompletions } from "./checkShellCompletions.js";
 
 const roots: string[] = [];
@@ -33,16 +38,21 @@ const tmp = (): string => {
 };
 
 let prevHome: string | undefined;
-let prevShell: string | undefined;
+let prevPath: string | undefined;
 beforeEach(() => {
   prevHome = process.env.HOME;
-  prevShell = process.env.SHELL;
+  prevPath = process.env.PATH;
   process.env.HOME = tmp();
+  // The installed script spawns `pragma` for every name context, and the check
+  // now verifies that it can. Put one on an isolated PATH so these cases are
+  // about the SCRIPT rather than about the host's install.
+  const bin = tmp();
+  writeFileSync(join(bin, "pragma"), "");
+  process.env.PATH = bin;
 });
 afterEach(() => {
   process.env.HOME = prevHome;
-  if (prevShell === undefined) delete process.env.SHELL;
-  else process.env.SHELL = prevShell;
+  process.env.PATH = prevPath;
   for (const dir of roots) rmSync(dir, { recursive: true, force: true });
   roots.length = 0;
 });
@@ -59,6 +69,20 @@ function installScript(shell: ShellId): void {
   writeScript(shell, emitScripts(capabilities)[shell]);
 }
 
+/**
+ * Run the check the way `doctor` does: the `completions` target detects once
+ * per invocation and the check reads that one answer, so the test drives the
+ * same pairing rather than letting the check re-read behind its own back.
+ */
+async function check(cwd: string, shell: ShellId | null): Promise<CheckResult> {
+  // The shell is INJECTED rather than forced through `$SHELL`: detection reads
+  // the process tree now, and a test that set `$SHELL` was only ever asserting
+  // against the login shell — the exact confusion this check exists to catch.
+  const detection: ShellDetection =
+    shell === null ? { kind: "unknown" } : { kind: "detected", shell };
+  return checkShellCompletions(cwd, await detectCompletions(cwd, detection));
+}
+
 /** Write a `.zshrc` that puts ~/.zfunc on fpath. */
 function wireZfunc(): void {
   writeFileSync(
@@ -71,34 +95,55 @@ 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.
-    delete process.env.SHELL;
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), null);
     expect(result.status).toBe("skip");
     expect(result.detail).toMatch(/resolver OK/);
   });
 });
 
 describe("checkShellCompletions — install probe (gate 2)", () => {
-  it("fails when $SHELL is set but no script is installed", async () => {
-    process.env.SHELL = "/usr/bin/bash";
-    const result = await checkShellCompletions(tmp());
-    expect(result.status).toBe("fail");
+  it("a never-installed script is available (opt-in, not a fault) with the setup command", async () => {
+    const result = await check(tmp(), "bash");
+    expect(result.status).toBe("available");
     expect(result.detail).toMatch(/not installed/);
     expect(result.remedy).toBe("pragma setup completions");
   });
 
+  it("does not claim a script is installed when the binary is off PATH", async () => {
+    // This gate runs before the install probe, so it saw only that the binary
+    // does not resolve — and reported `bash script installed, but ...` on a
+    // machine where nothing had ever been installed. Anyone invoking this CLI
+    // by absolute path lands here, and the row invented the file it exists to
+    // report on.
+    process.env.PATH = tmp(); // an empty PATH: no binary to find
+    const result = await check(tmp(), "bash");
+    expect(result.detail).not.toMatch(/script installed/);
+    expect(result.detail).toMatch(/is not on PATH/);
+    // Nothing was installed, so nothing that exists is broken.
+    expect(result.status).toBe("available");
+    expect(result.remedy).toMatch(/on your PATH/);
+  });
+
+  it("fails when an INSTALLED script cannot reach the binary", async () => {
+    installScript("bash");
+    process.env.PATH = tmp();
+    const result = await check(tmp(), "bash");
+    expect(result.status).toBe("fail");
+    expect(result.detail).toMatch(/script installed, but/);
+  });
+
   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());
+    const result = await check(tmp(), "bash");
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/bash up to date and resolving/);
+    expect(result.detail).toMatch(
+      /bash \(the shell in use\) up to date and resolving/,
+    );
   });
 
   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());
+    const result = await check(tmp(), "fish");
     expect(result.status).toBe("pass");
   });
 
@@ -110,9 +155,8 @@ describe("checkShellCompletions — install probe (gate 2)", () => {
     // 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());
+    const result = await check(tmp(), "bash");
     expect(result.status).toBe("fail");
     expect(result.detail).toMatch(/out of date/);
     expect(result.remedy).toBe("pragma setup completions");
@@ -127,23 +171,23 @@ describe("checkShellCompletions — install probe (gate 2)", () => {
     // 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");
+    expect(
+      (await detectCompletions(cwd, { kind: "detected", shell: "bash" })).state,
+    ).toBe("stale");
+    expect((await check(cwd, "bash")).status).toBe("pass");
   });
 });
 
 describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
   it("fails when the zsh script is installed but ~/.zfunc is not on fpath", async () => {
-    process.env.SHELL = "/usr/bin/zsh";
     installScript("zsh");
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), "zsh");
     expect(result.status).toBe("fail");
     expect(result.detail).toMatch(/not on your fpath/);
     // The remedy IS the activation hint — the exact ~/.zshrc lines.
@@ -151,11 +195,12 @@ describe("checkShellCompletions — zsh fpath activation (gate 3)", () => {
   });
 
   it("passes once the zsh script is installed AND ~/.zfunc is on fpath", async () => {
-    process.env.SHELL = "/usr/bin/zsh";
     installScript("zsh");
     wireZfunc();
-    const result = await checkShellCompletions(tmp());
+    const result = await check(tmp(), "zsh");
     expect(result.status).toBe("pass");
-    expect(result.detail).toMatch(/zsh up to date and resolving/);
+    expect(result.detail).toMatch(
+      /zsh \(the shell in use\) up to date and resolving/,
+    );
   });
 });

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 {
@@ -127,19 +139,53 @@ export async function checkShellCompletions(cwd: string): Promise<CheckResult> {
     };
   }
 
-  // 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: `resolver OK; the running shell cannot be identified (SHELL names ${d.detection.login}, the 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: "resolver OK; no bash, zsh, or fish 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`
+        : `resolver OK; \`${BIN_NAME}\` 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",
+      status: "available",
       detail: `resolver OK; ${shell} script not installed`,
       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 in use) up to date and resolving (${candidates} nouns)`,
   };
 }

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 UNBANDED
+ * 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 BANDED rows are derived
+ * per target, per band, 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: `bandedChecks` is the only way
+ * they are meant to be reached, and a row reachable past its band 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 { bandedChecks } from "./targetHealth.js";