@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/capabilities/config/set.verb.ts

@@ -0,0 +1,70 @@
+/**
+ * `config set <key> <value>` — the one-command config setter (ADDITIVE).
+ *
+ * The user-facing primary form for writing config: `pragma config set tier
+ * apps/lxd` instead of the per-field `pragma config tier apps/lxd`. It is purely
+ * additive — the frozen `config tier`/`channel`/`detail` verbs stay — and shares
+ * their exact write path (`runField` via `runSet`), so it inherits reset
+ * sentinels, enum re-validation, and the global-layer-only write for free.
+ *
+ * Covenant shape: `<key>` is an ENUM over the field names (better completion +
+ * validation; the token still emits as `<key>`), `<value>` a free string, so
+ * the verb emits `{ v:"set", args:["<key>","<value>"], mutates:true,
+ * mcp:"config_set" }` — no flags, storeless, exposed to MCP.
+ */
+
+import type { Task } from "@canonical/task";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { configFieldFormatters } from "./field.render.js";
+import { CONFIG_FIELDS } from "./fields.js";
+import type { ConfigFieldResult } from "./types.js";
+
+/** The writable field names, in covenant order — the `<key>` enum. */
+const CONFIG_KEYS = CONFIG_FIELDS.map((field) => field.field);
+
+const setVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
+  path: ["config", "set"],
+  summary: "Set a config field by name.",
+  doc: "Write a global config field by name — the one-command form of the per-field setters. `key` is one of `tier`, `channel`, or `detail`; the field's own reset rules apply (e.g. `set tier none` clears it). Written to the global layer only — project configs are authored by hand.",
+  params: [
+    {
+      kind: "enum",
+      name: "key",
+      doc: "The config field to write.",
+      values: CONFIG_KEYS,
+      required: true,
+      positional: true,
+    },
+    {
+      kind: "string",
+      name: "value",
+      doc: "The value to write (or a field's reset sentinel, e.g. `none`).",
+      required: true,
+      positional: true,
+    },
+  ],
+  output: { formatters: configFieldFormatters },
+  examples: [
+    { cmd: "pragma config set tier apps/lxd", note: "scope reads to a tier" },
+    { cmd: "pragma config set channel experimental" },
+    { cmd: "pragma config set tier none", note: "clear the tier" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: true,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: false, openWorldHint: false },
+    },
+  },
+  // Lazily import the write body (off the fast path); the `Task` arm is the same
+  // honest cast the per-field verbs use — see fields.ts.
+  run: (params) =>
+    import("./runSet.js").then((m) =>
+      m.runSet(params),
+    ) as unknown as Task<ConfigFieldResult>,
+};
+
+/** The `config set` verb. */
+export const configSetVerb = asVerb(setVerb);

package/src/capabilities/config/show.render.ts

@@ -0,0 +1,61 @@
+/**
+ * Formatters for `pragma config show` — plain, llm, json (no ink).
+ *
+ * Each resolved field carries a `[global]`/`[project]` origin marker so the
+ * user sees which layer won; default values carry no marker. Ported from the
+ * v1 config-show formatters.
+ */
+
+import type { ConfigOrigin } from "../../kernel/config/types.js";
+import type { Formatters } from "../../kernel/spec/types.js";
+import type { ConfigShowData } from "./types.js";
+
+/** A `[layer]` marker for values a config file supplied (blank for defaults). */
+function originMarker(origin: ConfigOrigin): string {
+  return origin === "default" ? "" : ` [${origin}]`;
+}
+
+/** Summarize the `packages` list as a comma-separated set of names. */
+function packageNames(data: ConfigShowData): string {
+  const packages = data.config.packages ?? [];
+  const names = packages.map((entry) =>
+    typeof entry === "string" ? entry : entry.name,
+  );
+  return names.length > 0 ? names.join(", ") : "(none)";
+}
+
+export const configShowFormatters: Formatters<ConfigShowData> = {
+  plain(data) {
+    const { config, origins } = data;
+    const lines = [
+      `tier: ${config.tier ?? "(none — all tiers visible)"}${originMarker(origins.tier)}`,
+      `channel: ${config.channel}${originMarker(origins.channel)}`,
+      `detail: ${config.detail ?? "standard"}${originMarker(origins.detail)}`,
+      `packages: ${packageNames(data)}${originMarker(origins.packages)}`,
+      `global config: ${data.globalConfigPath}${data.globalExists ? "" : " (not found)"}`,
+      `project config: ${data.projectConfigPath ?? "(not found)"}`,
+    ];
+    return lines.join("\n");
+  },
+
+  llm(data) {
+    const { config, origins } = data;
+    const lines = [
+      "## Configuration",
+      "",
+      `- **Tier:** ${config.tier ?? "none (all tiers)"}${originMarker(origins.tier)}`,
+      `- **Channel:** ${config.channel}${originMarker(origins.channel)}`,
+      `- **Detail:** ${config.detail ?? "standard"}${originMarker(origins.detail)}`,
+      `- **Packages:** ${packageNames(data)}${originMarker(origins.packages)}`,
+      `- **Global config:** \`${data.globalConfigPath}\``,
+    ];
+    if (data.projectConfigPath) {
+      lines.push(`- **Project config:** \`${data.projectConfigPath}\``);
+    }
+    return lines.join("\n");
+  },
+
+  json(data) {
+    return JSON.stringify(data);
+  },
+};

package/src/capabilities/config/show.verb.ts

@@ -0,0 +1,45 @@
+/**
+ * The `config show` verb spec (noun `config`, verb `show`).
+ *
+ * Storeless read; `run` lazily imports the collector. Config *setters* are a
+ * later PR — this ships only the reader.
+ */
+
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { CapabilityModule, VerbSpec } from "../../kernel/spec/types.js";
+import { configFieldVerbs } from "./fields.js";
+import { configSetVerb } from "./set.verb.js";
+import { configShowFormatters } from "./show.render.js";
+import type { ConfigShowData } from "./types.js";
+
+const showVerb: VerbSpec<Record<string, unknown>, ConfigShowData> = {
+  path: ["config", "show"],
+  summary: "Show the resolved config and per-field provenance.",
+  doc: "Merges built-in defaults, the global XDG config, and the nearest pragma.config.ts, marking which layer supplied each value.",
+  params: [],
+  output: { formatters: configShowFormatters },
+  examples: [
+    { cmd: "pragma config show" },
+    { cmd: "pragma config show --format json" },
+  ],
+  capability: {
+    needsStore: false,
+    mutates: false,
+    mcp: {
+      expose: true,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+  },
+  run: (_params, runtime) =>
+    import("./collectConfigShow.js").then((m) => m.collectConfigShow(runtime)),
+};
+
+/**
+ * The `config` capability module: the `show` reader (PR1), the storeless
+ * `tier`/`channel`/`detail` setters (PR6), and the additive one-command `set`
+ * verb (PR9), emitted in covenant order.
+ */
+export const configModule: CapabilityModule = {
+  name: "config",
+  verbs: [asVerb(showVerb), ...configFieldVerbs, configSetVerb],
+};

package/src/capabilities/config/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Data shapes for `pragma config show`.
+ */
+
+import type { ConfigOrigins, PragmaConfig } from "../../kernel/config/types.js";
+
+/** The resolved configuration plus per-field provenance and layer locations. */
+export interface ConfigShowData {
+  readonly config: PragmaConfig;
+  readonly origins: ConfigOrigins;
+  readonly projectConfigPath?: string;
+  readonly globalConfigPath: string;
+  readonly projectExists: boolean;
+  readonly globalExists: boolean;
+}
+
+/** The outcome of a `config <field>` setter (set, or reset via sentinel). */
+export interface ConfigFieldResult {
+  /** The config field written (`tier` / `channel` / `detail`). */
+  readonly field: string;
+  /** The value written, or absent when the field was reset (removed). */
+  readonly value?: string;
+  /** The global config file the write landed in. */
+  readonly path: string;
+  /** True when a reset sentinel removed the field rather than setting a value. */
+  readonly reset: boolean;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * PROTECTED — the cross-binary subprocess guard (one representative generator):
+ * the real `pragma` bin's `create component … --yes` vs an independently
+ * launched summon-core `execute` process (the summon bin's exact core path).
+ * A byte-for-byte match across two SEPARATE processes catches bin-level stamp /
+ * version / path divergence that an in-process test could mask.
+ *
+ * NOTE: the summon side runs summon-core `execute` directly rather than the
+ * summon bin — this repo's summon bin ships only its `init`/`example` builtins,
+ * not the canonical component generators — but it is the identical core the bin
+ * uses, in its own process.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, writeFileSync } 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 pragmaBin = join(repoRoot, "packages/cli/next/src/bin.ts");
+const summonCore = join(repoRoot, "packages/summon/core/dist/esm/index.js");
+const pickGen = join(here, "pickGenerator.ts");
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-xbin-"));
+
+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 })) {
+      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;
+}
+
+describe("cross-binary byte-equality (PROTECTED)", () => {
+  it("pragma bin create ≡ summon-core execute across two processes", () => {
+    // (1) The real pragma bin, run in its own process.
+    const pragmaDir = freshCwd();
+    execFileSync(
+      "bun",
+      [
+        pragmaBin,
+        "create",
+        "component",
+        "src/components/Button",
+        "--framework",
+        "react",
+        "--yes",
+      ],
+      { cwd: pragmaDir, stdio: "pipe" },
+    );
+
+    // (2) A separate summon-core execute process (the summon bin's core path).
+    const summonDir = freshCwd();
+    const script = join(freshCwd(), "produce.mjs");
+    writeFileSync(
+      script,
+      `
+import { pickGenerator } from ${JSON.stringify(`file://${pickGen}`)};
+import { execute, autoPrompt, runGeneratorTask, createGeneratorStamp, createStampOnEffectStart } from ${JSON.stringify(`file://${summonCore}`)};
+const dir = process.argv[2];
+const answers = { componentPath: "src/components/Button", withStyles: true, withStories: true, withSsrTests: true };
+const gen = pickGenerator("component", { framework: "react" });
+await runGeneratorTask(execute(gen, { prompt: autoPrompt(answers), params: answers }), {
+  cwd: dir,
+  promptHandler: autoPrompt(answers),
+  onEffectStart: createStampOnEffectStart(createGeneratorStamp(gen)),
+  onLog: () => {},
+});
+`,
+    );
+    execFileSync("bun", [script, summonDir], { stdio: "pipe" });
+
+    const a = snapshot(pragmaDir);
+    const b = snapshot(summonDir);
+    expect(a.size).toBeGreaterThan(0);
+    expect([...a.keys()].sort()).toEqual([...b.keys()].sort());
+    for (const [path, content] of a) {
+      expect(b.get(path), `content of ${path}`).toBe(content);
+    }
+  }, 60000);
+});

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

@@ -0,0 +1,222 @@
+/**
+ * PROTECTED — the permanent seam contract: every `create` tree is produced TWO
+ * ways and diffed byte-for-byte (path set + contents, incl. the "Generated by"
+ * stamp): (1) `pragma create <verb> --yes` through the kernel dispatcher, and
+ * (2) summon-core `execute` with `autoPrompt`, run through `runGeneratorTask` +
+ * the shared stamp — the summon bin's path. They match because both derive the
+ * StampConfig from `createGeneratorStamp` (displayName + version) and run the
+ * SAME `generator.generate` with the SAME answers.
+ *
+ * Five generators are covered: component × {react, svelte, lit}, package, and
+ * application. A cross-binary subprocess guard lives in byteEquality.subprocess.test.ts.
+ */
+
+import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  createApplicationVerb,
+  createComponentVerb,
+  createPackageVerb,
+} from "./create.verb.js";
+import type { CreateKind } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-golden-"));
+
+/** 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;
+}
+
+const verbFor: Record<CreateKind, VerbSpec> = {
+  component: createComponentVerb as VerbSpec,
+  package: createPackageVerb as VerbSpec,
+  application: createApplicationVerb as VerbSpec,
+};
+
+/** Producer (1): the full pragma kernel path — dispatcher runs the create verb. */
+async function producePragma(
+  kind: CreateKind,
+  params: Record<string, unknown>,
+): Promise<Map<string, string>> {
+  const dir = freshCwd();
+  const prev = process.cwd();
+  process.chdir(dir);
+  try {
+    const outcome = await executeVerb(
+      verbFor[kind],
+      params,
+      { dryRun: false, undo: false, yes: true },
+      bootRuntime(FLAGS, dir),
+    );
+    expect(outcome.exitCode).toBe(0);
+  } finally {
+    process.chdir(prev);
+  }
+  return snapshot(dir);
+}
+
+/** Producer (2): summon-core execute + autoPrompt + the shared stamp core. */
+async function produceSummon(
+  kind: CreateKind,
+  framework: string,
+  answers: Record<string, unknown>,
+): Promise<Map<string, string>> {
+  const { pickGenerator } = await import("./pickGenerator.js");
+  const {
+    execute,
+    autoPrompt,
+    runGeneratorTask,
+    createGeneratorStamp,
+    createStampOnEffectStart,
+  } = await import("@canonical/summon-core");
+  const generator = pickGenerator(kind, { framework });
+  const dir = freshCwd();
+  await runGeneratorTask(
+    execute(generator, { prompt: autoPrompt(answers), params: answers }),
+    {
+      cwd: dir,
+      promptHandler: autoPrompt(answers),
+      onEffectStart: createStampOnEffectStart(createGeneratorStamp(generator)),
+      onLog: () => {},
+    },
+  );
+  return snapshot(dir);
+}
+
+/** One golden case: the create-verb params, and the equivalent summon answers. */
+interface Case {
+  readonly name: string;
+  readonly kind: CreateKind;
+  readonly framework: string;
+  readonly params: Record<string, unknown>;
+  readonly answers: Record<string, unknown>;
+}
+
+const componentAnswers = {
+  withStyles: true,
+  withStories: true,
+  withSsrTests: false,
+};
+
+const cases: Case[] = [
+  {
+    name: "component/react",
+    kind: "component",
+    framework: "react",
+    params: {
+      framework: "react",
+      componentPath: "src/components/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/components/Button", ...componentAnswers },
+  },
+  {
+    name: "component/svelte",
+    kind: "component",
+    framework: "svelte",
+    params: {
+      framework: "svelte",
+      componentPath: "src/lib/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/lib/Button", ...componentAnswers },
+  },
+  {
+    name: "component/lit",
+    kind: "component",
+    framework: "lit",
+    params: {
+      framework: "lit",
+      componentPath: "src/lib/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/lib/Button", ...componentAnswers },
+  },
+  {
+    name: "package",
+    kind: "package",
+    framework: "",
+    params: {
+      name: "@canonical/my-lib",
+      type: "library",
+      description: "A library.",
+      withReact: false,
+      withStorybook: false,
+      withCli: false,
+      withPrTemplate: false,
+      runInstall: false,
+    },
+    answers: {
+      name: "@canonical/my-lib",
+      type: "library",
+      description: "A library.",
+      withReact: false,
+      withStorybook: false,
+      withCli: false,
+      withPrTemplate: false,
+      runInstall: false,
+    },
+  },
+  {
+    name: "application",
+    kind: "application",
+    framework: "",
+    params: {
+      appPath: "my-app",
+      ssr: true,
+      router: true,
+      forms: true,
+      relay: false,
+      runInstall: false,
+    },
+    answers: {
+      appPath: "my-app",
+      ssr: true,
+      router: true,
+      forms: true,
+      relay: false,
+      runInstall: false,
+    },
+  },
+];
+
+describe("byte-equality goldens — pragma create ≡ summon execute (PROTECTED)", () => {
+  for (const testCase of cases) {
+    it(`${testCase.name}: both producers write byte-identical trees`, async () => {
+      const pragma = await producePragma(testCase.kind, testCase.params);
+      const summon = await produceSummon(
+        testCase.kind,
+        testCase.framework,
+        testCase.answers,
+      );
+      expect(pragma.size).toBeGreaterThan(0);
+      expect([...pragma.keys()].sort()).toEqual([...summon.keys()].sort());
+      for (const [path, content] of pragma) {
+        expect(summon.get(path), `content of ${path}`).toBe(content);
+      }
+    });
+  }
+});

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

@@ -0,0 +1,152 @@
+/**
+ * PROTECTED — the compiled-binary `create` guard.
+ *
+ * Builds the real standalone `dist/pragma` (`bun build --compile`) and spawns
+ * `pragma create component … --yes` for react, svelte AND lit, asserting each
+ * tree is BYTE-IDENTICAL to a source run of the same generator (`bun src/bin.ts
+ * …`, which reads the `.ejs` templates from disk).
+ *
+ * This is what proves PR7's two compiled-`create` fixes end-to-end:
+ *   1. Summon is bundled — a computed-specifier import used to keep summon-core +
+ *      the generators OUT of the binary; static dynamic imports now include them.
+ *   2. The templates are embedded AND resolved by DIRECTORY-QUALIFIED path. The
+ *      svelte + lit cases are load-bearing: `types.ts.ejs` / `index.ts.ejs` /
+ *      `styles.css.ejs` / `stories.ts.ejs` exist in react/, svelte/ AND lit/, so
+ *      the old basename-matching fallback could emit the WRONG framework's file
+ *      in the binary. A wrong file would differ from the source run → red here.
+ *
+ * On base (summon not bundled, templates not embedded) the binary's `create`
+ * writes nothing (it errors), so `compiled.size > 0` already fails.
+ */
+
+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 { beforeAll, describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../../../../../..");
+const cliNextDir = join(repoRoot, "packages/cli/next");
+const pragmaBin = join(cliNextDir, "src/bin.ts");
+const compiledBin = join(cliNextDir, "dist/pragma");
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-compiled-"));
+
+// Build the standalone binary ONCE for every describe in this file (create +
+// the READ smoke share it), so the tests always exercise the current bundle +
+// embedded manifest rather than a stale `dist/pragma`.
+beforeAll(() => {
+  const result = spawnSync("bun", ["run", "scripts/build.ts"], {
+    cwd: cliNextDir,
+    stdio: "pipe",
+  });
+  if (result.status !== 0) {
+    throw new Error(
+      `failed to build dist/pragma:\n${result.stderr?.toString() ?? ""}`,
+    );
+  }
+}, 180_000);
+
+/** 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;
+}
+
+/** Run a `create component` in its own cwd and snapshot what it wrote. */
+function createComponent(
+  bin: string,
+  args: readonly string[],
+  framework: string,
+): Map<string, string> {
+  const dir = freshCwd();
+  execFileSync(
+    bin,
+    [
+      ...args,
+      "create",
+      "component",
+      "src/components/Widget",
+      "--framework",
+      framework,
+      "--yes",
+    ],
+    { cwd: dir, stdio: "pipe" },
+  );
+  return snapshot(dir);
+}
+
+describe("compiled pragma create component (PROTECTED)", () => {
+  for (const framework of ["react", "svelte", "lit"] as const) {
+    it(`${framework}: compiled binary ≡ source run, byte-for-byte`, () => {
+      // (1) The real standalone binary — templates come from the embedded manifest.
+      const compiled = createComponent(compiledBin, [], framework);
+      // (2) A source run — templates come from disk. The reference output.
+      const source = createComponent("bun", [pragmaBin], framework);
+
+      // Wrote something (fails on base, where the binary's create errors out).
+      expect(compiled.size).toBeGreaterThan(0);
+      // Same file set …
+      expect([...compiled.keys()].sort()).toEqual([...source.keys()].sort());
+      // … and byte-identical contents (the collision fix: svelte/lit must NOT
+      // carry react's template text).
+      for (const [path, content] of compiled) {
+        expect(source.get(path), `content of ${path}`).toBe(content);
+      }
+    }, 120_000);
+  }
+});
+
+/**
+ * PROTECTED — the compiled-binary 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`
+ * template that the standalone binary lacks. 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`
+ * on any bun version whose `--compile` code-splitting did not keep the generator
+ * modules lazy. The lazy load makes a READ template-free regardless of bun.
+ */
+describe("compiled 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(compiledBin, [...args], {
+        cwd: freshCwd(),
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+      // The exact crash the lazy-template fix closes: a READ never loads a
+      // generator, so it never touches a `.ejs` the standalone binary lacks.
+      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);
+  }
+});