@canonical/pragma-cli 0.32.0 → 0.34.0

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

@@ -24,29 +24,20 @@ 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, "../../../../../..");
-const cliNextDir = join(repoRoot, "packages/cli/next");
+const cliNextDir = join(repoRoot, "packages/cli/pragma");
 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",

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

@@ -25,13 +25,14 @@ import {
 import { bootRuntime } from "../../kernel/runtime/boot.js";
 import type { GlobalFlags } from "../../kernel/runtime/types.js";
 import type { ParamSpec } from "../../kernel/spec/types.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import {
-  createApplicationVerb,
-  createComponentVerb,
-  createPackageVerb,
+  createVerbs,
+  INCLUDE_FLAG_ALIASES,
   isModuleNotFound,
 } from "./create.verb.js";
 import { generatorToParams } from "./generatorToVerbSpec.js";
+import { createModule } from "./index.js";
 
 const FLAGS: GlobalFlags = {
   llm: false,
@@ -52,7 +53,7 @@ async function runIn(
   process.chdir(dir);
   try {
     return await executeVerb(
-      createComponentVerb,
+      createVerbs.component,
       params,
       mutation,
       bootRuntime(FLAGS, dir),
@@ -85,7 +86,11 @@ describe("create — real generation + stamp", () => {
     expect(readFileSync(main, "utf-8").split("\n")[0]).toBe(
       "// Generated by @canonical/summon-component:react v0.1.0",
     );
-  });
+    // Explicit timeout, like the package's other real-run gates: this drives a
+    // full generator run (~2.4s idle), and under a contended CI matrix the 5s
+    // vitest default fails it on load, not on a defect — both build-matrix
+    // legs timed out at 5000ms on a run whose import phase alone took 88s.
+  }, 60_000);
 
   it("--dry-run writes nothing and previews effects (no Prompt lines)", async () => {
     const dir = freshCwd();
@@ -100,6 +105,45 @@ describe("create — real generation + stamp", () => {
     expect(walk(dir)).toEqual([]); // nothing written
   });
 
+  it("--dry-run reports the bytes the real run writes (post-stamp)", async () => {
+    // The mock previewer never called `onEffectStart`, so summon's stamping
+    // transform did not run and every planned byte count under-reported the
+    // written file by the stamp's length. The honest previewer runs it.
+    const params = {
+      framework: "react",
+      componentPath: "src/components/Widget",
+      withStyles: true,
+      withStories: false,
+      withSsrTests: false,
+    };
+    const previewDir = freshCwd();
+    const preview = await runIn(previewDir, params, {
+      dryRun: true,
+      undo: false,
+      yes: false,
+    });
+    expect(preview.exitCode).toBe(0);
+    expect(walk(previewDir)).toEqual([]);
+
+    const planned = new Map<string, number>();
+    for (const line of (preview.stdout ?? "").split("\n")) {
+      const match = /^ {2}- Write file: (.+) \((\d+) bytes\)$/.exec(line);
+      if (match) planned.set(match[1] as string, Number(match[2]));
+    }
+    expect(planned.size).toBeGreaterThan(0);
+
+    const realDir = freshCwd();
+    expect((await runIn(realDir, params)).exitCode).toBe(0);
+    for (const [relative, bytes] of planned) {
+      expect({
+        file: relative,
+        bytes: readFileSync(join(realDir, relative), "utf-8").length,
+      }).toEqual({ file: relative, bytes });
+    }
+    // Same set of files, not just the same counts for the ones checked.
+    expect(walk(realDir).sort()).toEqual([...planned.keys()].sort());
+  });
+
   it("--undo reverses a run", async () => {
     const dir = freshCwd();
     await runIn(dir, {
@@ -122,7 +166,9 @@ describe("create — real generation + stamp", () => {
     );
     expect(outcome.exitCode).toBe(0);
     expect(outcome.stdout).toMatch(/Undid \d+ step/);
-  });
+    // TWO real runs (generate, then undo) — the same load-sensitivity as the
+    // stamp test above, doubled; same explicit ceiling.
+  }, 60_000);
 
   it("rejects an unknown framework with INVALID_INPUT", async () => {
     const dir = freshCwd();
@@ -130,7 +176,7 @@ describe("create — real generation + stamp", () => {
     // framework param to exercise pickGenerator's own guard too.
     const runtime = bootRuntime(FLAGS, dir);
     await expect(
-      createComponentVerb.run({ framework: "vue" }, {
+      createVerbs.component.run({ framework: "vue" }, {
         ...runtime,
         interaction: { isTTY: false, transport: "cli", yes: true },
       } as never),
@@ -216,9 +262,19 @@ describe("lazy-React discipline (PROTECTED)", () => {
       "@canonical/summon-component",
       "@canonical/summon-package",
       "@canonical/summon-application",
+      // The generators pull summon-core, and summon-core is what costs the
+      // fast paths (+43 MB RSS once it loads). Dropping the `type` from one of
+      // the four `import type … from "@canonical/summon-core"` lines in this
+      // directory is a one-word regression nothing else catches.
+      "@canonical/summon-core",
     ];
     for (const file of graph) {
-      const src = readFileSync(file, "utf-8");
+      // Type-only imports are erased before runtime, so they load nothing —
+      // strip them before asking what the file actually pulls in.
+      const src = readFileSync(file, "utf-8").replace(
+        /\bimport\s+type\b[^;]*;/g,
+        "",
+      );
       for (const pkg of forbidden) {
         const esc = pkg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
         expect(
@@ -284,7 +340,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
       (generators as Record<string, { prompts: unknown[] }>)["component/react"]
         .prompts as never,
     );
-    const verb = createComponentVerb.params;
+    const verb = createVerbs.component.params;
 
     // The verb SYNTHESIZES a `framework` enum (the 3 framework generators
     // collapse to one verb): react|svelte|lit, default react — no generator
@@ -327,7 +383,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
         .prompts as never,
     );
     // The package verb's grammar IS generatorToParams(PACKAGE_MIRROR).
-    expect(behavioural(createPackageVerb.params)).toEqual(
+    expect(behavioural(createVerbs.package.params)).toEqual(
       behavioural(applyRunInstallOverride(real)),
     );
 
@@ -335,7 +391,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
     const realRunInstall = real.find((p) => p.name === "runInstall") as
       | Record<string, unknown>
       | undefined;
-    const mirrorRunInstall = createPackageVerb.params.find(
+    const mirrorRunInstall = createVerbs.package.params.find(
       (p) => p.name === "runInstall",
     ) as Record<string, unknown> | undefined;
     expect(realRunInstall?.default).toBe(true);
@@ -350,6 +406,18 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
     });
   });
 
+  /** Map a mirror's CLI `--with-X` include-flag names back to the generator
+   * prompt names (AV-228 B8) so the parity comparison still checks kinds and
+   * defaults against the real generator despite the deliberate flag rename. */
+  const toGeneratorNames = (
+    kind: "application",
+    params: readonly ParamSpec[],
+  ): ParamSpec[] =>
+    params.map((p) => {
+      const generatorName = INCLUDE_FLAG_ALIASES[kind][p.name];
+      return generatorName ? ({ ...p, name: generatorName } as ParamSpec) : p;
+    });
+
   it("application: mirror matches the application/react generator (defaults)", async () => {
     const { generators } = await import("@canonical/summon-application");
     const real = generatorToParams(
@@ -357,14 +425,30 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
         "application/react"
       ].prompts as never,
     );
-    expect(behavioural(createApplicationVerb.params)).toEqual(
-      behavioural(applyRunInstallOverride(real)),
-    );
+    // Bridge the B8 include-flag rename before comparing: the CLI grammar
+    // exposes `withSsr`/`withRouter`/`withForms`, which map back to the
+    // generator's `ssr`/`router`/`forms`.
+    expect(
+      behavioural(
+        toGeneratorNames("application", createVerbs.application.params),
+      ),
+    ).toEqual(behavioural(applyRunInstallOverride(real)));
+
+    // Guard the B8 rename itself: ALL application include-flags ARE on the
+    // `--with-X` convention (params `withSsr`/`withRouter`/`withForms`/
+    // `withRelay`), not the bare `ssr`/`router`/`forms`/`relay` booleans.
+    const names = createVerbs.application.params.map((p) => p.name);
+    expect(names).toContain("withSsr");
+    expect(names).toContain("withRouter");
+    expect(names).toContain("withForms");
+    expect(names).toContain("withRelay");
+    expect(names).not.toContain("ssr");
+    expect(names).not.toContain("relay");
 
     const realRunInstall = real.find((p) => p.name === "runInstall") as
       | Record<string, unknown>
       | undefined;
-    const mirrorRunInstall = createApplicationVerb.params.find(
+    const mirrorRunInstall = createVerbs.application.params.find(
       (p) => p.name === "runInstall",
     ) as Record<string, unknown> | undefined;
     expect(realRunInstall?.default).toBe(true);
@@ -372,7 +456,7 @@ describe("generator→grammar adapter parity (PROTECTED)", () => {
 
     // appPath is the positional entry point (its default carries across).
     expect(
-      createApplicationVerb.params.find((p) => p.name === "appPath"),
+      createVerbs.application.params.find((p) => p.name === "appPath"),
     ).toMatchObject({ kind: "string", positional: true, default: "my-app" });
   });
 });
@@ -401,3 +485,95 @@ describe("compiled-binary create gate (M4)", () => {
     expect(isModuleNotFound("nope")).toBe(false);
   });
 });
+
+describe("declared generator bindings (PROTECTED)", () => {
+  // CREATE_GENERATORS is the one place the create surface's generator facts are
+  // written down. What is checkable against something outside itself — the live
+  // generator maps and the embedded manifest — is checked here.
+
+  it("every binding resolves to the generator it names", async () => {
+    const { pickGenerator } = await import("./pickGenerator.js");
+    // `meta.name` is the generator's OWN identity, so a swapped `key` or a
+    // framework the map does not carry turns this red — which `toBeDefined()`
+    // on a non-nullable return could not.
+    for (const framework of CREATE_GENERATORS.component.frameworks) {
+      expect(pickGenerator("component", { framework }).meta.name).toBe(
+        `component/${framework}`,
+      );
+    }
+    expect(pickGenerator("package", {}).meta.name).toBe("package");
+    expect(pickGenerator("application", {}).meta.name).toBe(
+      "application/react",
+    );
+  });
+
+  it("exactly the two source-run-only verbs publish the availability caveat", () => {
+    // A LITERAL list, for the same reason `compiledCreate.subprocess.test.ts`
+    // uses one: the caveat is DERIVED from `readsEmbeddedTemplates`, so an
+    // assertion derived from the same bit would agree with itself no matter
+    // which way the bit was flipped. These two are the nouns that test proves
+    // refuse on a real compiled binary, so this is what the reference is held
+    // to — and flipping the bit turns this red, along with the reference
+    // drift-guard, in the same run.
+    const caveated = createModule.verbs
+      .filter((verb) => verb.summary.includes("Source-run only."))
+      .map((verb) => verb.path.at(1));
+    expect(caveated).toEqual(["package", "application"]);
+    for (const verb of createModule.verbs) {
+      const kind = verb.path.at(1);
+      const gated = caveated.includes(kind);
+      // The `doc` is what `tools.md` and the MCP tool description render, so
+      // the explanation has to travel with the marker, and it quotes the
+      // command it is about — a copy-paste between bindings is then visible.
+      expect(verb.doc?.includes("UNSUPPORTED") ?? false, kind).toBe(gated);
+      if (gated) {
+        expect(verb.doc).toContain(`create ${kind}`);
+        // And it still says what the verb MAKES. `doc ?? summary` means a doc
+        // REPLACES the summary on the MCP surface, so a caveat alone left an
+        // agent no statement anywhere of what `create_package` scaffolds.
+        expect(verb.doc).toContain(
+          verb.summary.replace(" Source-run only.", ""),
+        );
+      }
+    }
+  });
+
+  it("the --framework enum offers the declared frameworks and defaults to one of them", () => {
+    const framework = createVerbs.component.params.find(
+      (p) => p.name === "framework",
+    );
+    // A `values: []` enum with a `default` would leave every `--framework`
+    // rejected while `--help` still advertises a default — the hazard this names.
+    // (That every value resolves is the test above.)
+    expect(framework?.kind).toBe("enum");
+    const values = (framework as { values: readonly string[] }).values;
+    expect(values.length).toBeGreaterThan(0);
+    expect(values).toContain(framework?.default);
+  });
+
+  it("embeds only the templates the component loader can key", async () => {
+    const { TEMPLATES } = await import("./templates.embedded.generated.js");
+    const keys = Object.keys(TEMPLATES);
+    // summon-component's `qualifiedKey()` prefixes EVERY lookup with
+    // `component/`, so any other entry ships dead weight the binary can never
+    // read — and a binding embedded without a manifest-reading generator would
+    // put one here. Non-empty first: `.every()` over an empty list is vacuous.
+    expect(keys.length).toBeGreaterThan(0);
+    expect(keys.filter((k) => !k.startsWith("component/"))).toEqual([]);
+  });
+
+  it("create surfaces exactly the three declared nouns", () => {
+    // A LITERAL surface pin, deliberately not derived from CREATE_GENERATORS:
+    // 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 of what
+    // the declared packages ship (`@canonical/summon-application` also ships
+    // `domain`, `route` and `wrapper`). Pinning OUR three nouns rather than any
+    // third-party package's generator list keeps an upstream release from
+    // turning this red.
+    expect(createModule.verbs.map((v) => v.path[1])).toEqual([
+      "component",
+      "package",
+      "application",
+    ]);
+  });
+});