@canonical/pragma-cli 0.34.0 → 0.36.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.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/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";
 
 /**
@@ -58,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.
  *
@@ -87,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 } : {}),
     };
   }
@@ -101,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/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(
@@ -70,35 +94,58 @@ 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.
-    delete process.env.SHELL;
-    const result = await checkShellCompletions(tmp());
+    // 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>`/);
   });
 });
 
 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 you are in\) — installed, up to date, and completing/,
+    );
   });
 
   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 +157,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 +173,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 +197,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 you are in\) — installed, up to date, and completing/,
+    );
   });
 });