@canonical/pragma-cli 0.33.0 → 0.34.0

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

@@ -1,29 +1,42 @@
 /**
- * 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.
+ * PROTECTED — pragma's side of the byte-equality 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) the REFERENCE — summon-core `execute` with `autoPrompt`,
+ * run through `runGeneratorTask` + the shared stamp. They match because both
+ * derive the StampConfig from `createGeneratorStamp` (displayName + version) and
+ * run the SAME `generator.generate` with the SAME answers.
+ *
+ * The reference producer, the tree snapshot/diff, and the answer sets are NOT
+ * defined here any more: they are `@canonical/summon-core/testing`, the named
+ * conformance suite both bins run (L-OPEN-10). This file supplies what only
+ * pragma can — its kernel dispatch path, and the mapping from a fixture's
+ * logical generator id to the bundled generator plus the CLI param names the
+ * `create` verbs take. No new package edge: pragma already depends on
+ * summon-core, and never on the summon bin.
  *
  * 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 { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import {
+  CONFORMANCE_FIXTURES,
+  diffTrees,
+  formatTreeDiff,
+  isIdentical,
+  produceReference,
+  snapshotTree,
+  type TreeSnapshot,
+} from "@canonical/summon-core/testing";
 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 { createVerbs } from "./create.verb.js";
 import type { CreateKind } from "./types.js";
 
 const FLAGS: GlobalFlags = {
@@ -34,39 +47,17 @@ const FLAGS: GlobalFlags = {
 };
 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>> {
+): Promise<TreeSnapshot> {
   const dir = freshCwd();
   const prev = process.cwd();
   process.chdir(dir);
   try {
     const outcome = await executeVerb(
-      verbFor[kind],
+      createVerbs[kind] as VerbSpec,
       params,
       { dryRun: false, undo: false, yes: true },
       bootRuntime(FLAGS, dir),
@@ -75,44 +66,38 @@ async function producePragma(
   } finally {
     process.chdir(prev);
   }
-  return snapshot(dir);
+  return snapshotTree(dir);
 }
 
-/** Producer (2): summon-core execute + autoPrompt + the shared stamp core. */
+/**
+ * Producer (2): the shared conformance REFERENCE, over pragma's own generator.
+ *
+ * The fixture names its generator logically; `pickGenerator` is what turns that
+ * into the bundled definition. The suite never imports a generator itself —
+ * summon-core sits below both bins.
+ */
 async function produceSummon(
   kind: CreateKind,
   framework: string,
-  answers: Record<string, unknown>,
-): Promise<Map<string, string>> {
+  answers: Readonly<Record<string, unknown>>,
+): Promise<TreeSnapshot> {
   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);
+  return produceReference({
+    generator: pickGenerator(kind, { framework }),
+    answers,
+  });
 }
 
-/** One golden case: the create-verb params, and the equivalent summon answers. */
+/**
+ * One golden case: the shared fixture, plus what only pragma knows — which
+ * bundled generator the fixture's id names, and the CLI param names the create
+ * verb takes for the same answers.
+ */
 interface Case {
-  readonly name: string;
+  readonly fixture: string;
   readonly kind: CreateKind;
   readonly framework: string;
   readonly params: Record<string, unknown>;
-  readonly answers: Record<string, unknown>;
 }
 
 const componentAnswers = {
@@ -123,7 +108,7 @@ const componentAnswers = {
 
 const cases: Case[] = [
   {
-    name: "component/react",
+    fixture: "component/react",
     kind: "component",
     framework: "react",
     params: {
@@ -131,10 +116,9 @@ const cases: Case[] = [
       componentPath: "src/components/Button",
       ...componentAnswers,
     },
-    answers: { componentPath: "src/components/Button", ...componentAnswers },
   },
   {
-    name: "component/svelte",
+    fixture: "component/svelte",
     kind: "component",
     framework: "svelte",
     params: {
@@ -142,10 +126,9 @@ const cases: Case[] = [
       componentPath: "src/lib/Button",
       ...componentAnswers,
     },
-    answers: { componentPath: "src/lib/Button", ...componentAnswers },
   },
   {
-    name: "component/lit",
+    fixture: "component/lit",
     kind: "component",
     framework: "lit",
     params: {
@@ -153,10 +136,9 @@ const cases: Case[] = [
       componentPath: "src/lib/Button",
       ...componentAnswers,
     },
-    answers: { componentPath: "src/lib/Button", ...componentAnswers },
   },
   {
-    name: "package",
+    fixture: "package",
     kind: "package",
     framework: "",
     params: {
@@ -169,24 +151,15 @@ const cases: Case[] = [
       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",
+    fixture: "application",
     kind: "application",
     framework: "",
-    // The pragma path receives the CLI `--with-X` params (AV-228 B8); the summon
-    // path receives the generator's bare prompt names. runCreate's boundary remap
-    // (`withSsr` -> `ssr`, ...) makes both produce the byte-identical tree.
+    // The pragma path receives the CLI `--with-X` params (AV-228 B8); the shared
+    // fixture carries the generator's bare prompt names. runCreate's boundary
+    // remap (`withSsr` -> `ssr`, ...) makes both produce the identical tree —
+    // which is exactly what this case exists to prove.
     params: {
       appPath: "my-app",
       withSsr: true,
@@ -195,31 +168,36 @@ const cases: Case[] = [
       withRelay: 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)", () => {
+describe("byte-equality goldens — pragma create \u2261 the conformance reference (PROTECTED)", () => {
+  it("covers every shared conformance fixture", () => {
+    // The suite's fixture list is the contract; a fixture added there and not
+    // wired here would silently go unchecked on pragma's side.
+    expect(cases.map((entry) => entry.fixture)).toEqual(
+      CONFORMANCE_FIXTURES.map((entry) => entry.name),
+    );
+  });
+
   for (const testCase of cases) {
-    it(`${testCase.name}: both producers write byte-identical trees`, async () => {
+    it(`${testCase.fixture}: the kernel path matches the reference byte for byte`, async () => {
+      const shared = CONFORMANCE_FIXTURES.find(
+        (entry) => entry.name === testCase.fixture,
+      );
+      if (!shared) throw new Error(`no fixture "${testCase.fixture}"`);
       const pragma = await producePragma(testCase.kind, testCase.params);
-      const summon = await produceSummon(
+      const reference = await produceSummon(
         testCase.kind,
         testCase.framework,
-        testCase.answers,
+        shared.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);
-      }
+      const diff = diffTrees(pragma, reference);
+      expect(
+        isIdentical(diff),
+        formatTreeDiff(diff, "pragma create", "the conformance reference"),
+      ).toBe(true);
     });
   }
 });

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

@@ -24,7 +24,7 @@ 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";
+import { describe, expect, it } from "vitest";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const repoRoot = resolve(here, "../../../../../..");
@@ -33,20 +33,11 @@ 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);
+// The binary is provisioned by `testing/perf/globalSetup.ts`, which rebuilds it
+// whenever it is missing or older than `src/**`, `scripts/**`, `pragma.conf.ts`
+// or `package.json` — so these tests exercise the current bundle + embedded
+// manifest without a second `beforeAll` writing `dist/pragma` in place while
+// another worker's test is spawning it.
 
 /** Read a directory tree into a sorted map of relative path → contents. */
 function snapshot(dir: string): Map<string, string> {
@@ -108,6 +99,52 @@ describe("compiled pragma create component (PROTECTED)", () => {
   }
 });
 
+/**
+ * PROTECTED — the compiled-binary `create` gate.
+ *
+ * `create component` runs from the binary (the describe above proves it byte for
+ * byte) because summon-component routes every template read through
+ * `loadTemplateSync` and passes `content:` into `template()`. `create package` /
+ * `create application` do NOT: they call `template({ source })`, summon-core
+ * falls through to `readFile(options.source)`, and the run dies with `ENOENT …
+ * /$bunfs/templates/package.json.ejs` AFTER `mkdir` has already run — a
+ * half-made package left on the user's disk. Measured against a real
+ * `dist/pragma` with the gate lifted, for both nouns.
+ *
+ * A `--dry-run` does NOT test this: it exits 0 without reading a template and
+ * merely PRINTS `Read file: /$bunfs/templates/package.json.ejs` as a planned
+ * effect. That false positive is why the gate has to be pinned by a real run.
+ *
+ * The `readdirSync(dir)` assertion is the load-bearing one: it fails with the
+ * real symptom if the gate is ever lifted without fixing the generators.
+ */
+describe("compiled pragma create gate (PROTECTED)", () => {
+  // A LITERAL noun list, deliberately not derived from `create`'s own
+  // declaration: changing the gate's input must turn this red rather than
+  // silently drop the case.
+  for (const kind of ["package", "application"] as const) {
+    it(`refuses \`create ${kind}\` and leaves the cwd untouched`, () => {
+      const dir = freshCwd();
+      const result = spawnSync(compiledBin, ["create", kind, "--yes"], {
+        cwd: dir,
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+      // 1, not merely non-zero: UNSUPPORTED is a runtime refusal, which
+      // `kernel/error/constants.ts` maps to the generic runtime exit.
+      expect(result.status).toBe(1);
+      expect(output).toContain("not available in the compiled pragma binary");
+      // The clean refusal, not the crash it exists to prevent.
+      expect(output).not.toMatch(/ENOENT/);
+      expect(output).not.toMatch(/Internal error/);
+      // And nothing half-made on disk: the generator's `mkdir` effects run
+      // BEFORE its first template read, so a lifted gate leaves a stub tree.
+      expect(readdirSync(dir)).toEqual([]);
+    }, 30_000);
+  }
+});
+
 /**
  * PROTECTED — the compiled-binary READ guard (U1-orig).
  *

package/src/capabilities/create/constants.ts

@@ -0,0 +1,75 @@
+/**
+ * The generator bindings the `create` surface exposes — the one list the
+ * surface's mechanical copies derive from: the `CreateKind` union (`types.ts`),
+ * the `--framework` enum and the compiled-binary gate (`create.verb.ts`), the
+ * generator lookup (`pickGenerator.ts`), and the template roots the bundler
+ * embeds (`scripts/build.ts`). Prose is NOT derived: the verb summaries below
+ * `createVerbs` and `capabilities/hints.ts` still name the frameworks by hand.
+ *
+ * This table is the SINGLE authoring point for which generator packages the
+ * distribution ships: it binds each `create` noun to the generator-map key it
+ * runs, and — for the one generator whose templates the binary carries — to
+ * the package `scripts/build.ts` harvests them from. (A parallel `generators`
+ * CONFIG field once declared the same packages; it was validated, layered and
+ * read by nothing, and was removed under the L-OPEN-1 ruling — the config
+ * validator now rejects it loudly.) The binding is hand-written because
+ * neither half can be discovered:
+ *  - surfacing a noun also needs a hand-written prompt mirror, path param and
+ *    examples in `create.verb.ts`, so the surface is a deliberate SUBSET —
+ *    `@canonical/summon-application` ships `application/react`, `domain`, `route`
+ *    and `wrapper`, and `create` exposes one of them;
+ *  - `bun build --compile` bundles only statically analysable import specifiers,
+ *    so a shipped binary can never `import(name)` a declared package (measured:
+ *    `Cannot find module '@canonical/summon-component' from '/$bunfs/root/…'`).
+ *    `pickGenerator` must import all three statically.
+ *
+ * `create.test.ts` pins what is checkable: every binding resolves to the
+ * generator it names, and the embedded manifest carries only the templates of
+ * the binding that reads through it.
+ *
+ * Deliberately free of any import: `create.verb.ts` reads this on the `--help` /
+ * `__complete` fast path (`capabilities/lazy.test.ts`).
+ */
+export const CREATE_GENERATORS = {
+  component: {
+    /**
+     * The declaring package: `scripts/build.ts` harvests its `.ejs` for the
+     * binary.
+     */
+    name: "@canonical/summon-component",
+    /** `--framework <f>` runs `component/<f>`; the FIRST is the enum default. */
+    frameworks: ["react", "svelte", "lit"],
+    /**
+     * Runs from the compiled binary: this generator routes every template read
+     * through `loadTemplateSync` and passes `content:` into `template()`, so the
+     * embedded manifest serves it. That — not the templates' file extensions —
+     * is the property that decides it, and it is a fact about the GENERATOR's
+     * source, not about what this build chooses to embed.
+     */
+    readsEmbeddedTemplates: true,
+  },
+  package: {
+    /** The generator-map key `create package` runs. */
+    key: "package",
+    /**
+     * NOT runnable from the compiled binary: this generator calls
+     * `template({ source })` with no `content:`, so summon-core falls through to
+     * `readFile(options.source)`. Measured against a real `dist/pragma` with the
+     * gate lifted: `ENOENT: no such file or directory, open
+     * '/$bunfs/templates/package.json.ejs'`, after `mkdir` had already created
+     * `my-lib/` and `my-lib/src/` — a half-made package left on disk. A
+     * `--dry-run` exits 0 without reading a template, so it does NOT test this.
+     */
+    readsEmbeddedTemplates: false,
+  },
+  application: {
+    /** The generator-map key `create application` runs. */
+    key: "application/react",
+    /**
+     * NOT runnable from the compiled binary — same cause as `package` (measured:
+     * `ENOENT … '/$bunfs/root/templates/package.json.ejs'`, after the app
+     * directory was created). It also `copy()`s non-`.ejs` assets.
+     */
+    readsEmbeddedTemplates: false,
+  },
+} as const;

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

@@ -14,7 +14,7 @@ import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { VerbSpec } from "../../kernel/spec/types.js";
 import { projectMcp } from "../../testing/helpers/projectMcp.js";
-import { createComponentVerb } from "./create.verb.js";
+import { createVerbs } from "./create.verb.js";
 import { createModule } from "./index.js";
 
 const FLAGS: GlobalFlags = {
@@ -117,7 +117,7 @@ describe("create over MCP (PROTECTED)", () => {
       const mcpPlan = (mcpResult.data as { plan: string[] }).plan;
 
       const cliOutcome = await executeVerb(
-        createComponentVerb as VerbSpec,
+        createVerbs.component as VerbSpec,
         {
           framework: "react",
           componentPath: "src/components/Button",