@canonical/pragma-cli 0.32.0 → 0.34.0

package/src/capabilities/create/create.verb.ts

@@ -1,11 +1,11 @@
 /**
  * The `create` verbs — `component` / `package` / `application` (path capped at
- * two segments; the three component frameworks collapse to one verb + a
+ * two segments; the declared component frameworks collapse to one verb + a
  * `--framework` enum). Each is a mutating, interactive, storeless verb.
  *
  * LAZY DISPATCH (R9 + lazy-React): the params are STATIC — built by the
  * generator→grammar adapter over static prompt MIRRORS, never the live
- * generators (importing a generator runs a top-level `await loadTemplate`). The
+ * generators (importing a generator pulls summon-core, and with it React). The
  * `run` body lazily `import()`s `pickGenerator` + summon-core, so `buildProgram`
  * / `--help` / `__complete` / reads never load summon-core or the generators —
  * and `create --yes` never loads React (the Ink UI is dynamic-only, and only the
@@ -15,9 +15,11 @@
 
 import type { GeneratorResult, PromptDefinition } from "@canonical/summon-core";
 import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
 import type { PragmaRuntime } from "../../kernel/runtime/types.js";
 import type { ParamSpec, VerbSpec } from "../../kernel/spec/types.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import { createFormatters } from "./create.render.js";
 import { generatorToParams } from "./generatorToVerbSpec.js";
 import { assertInsideWorkspace } from "./pathJail.js";
@@ -27,13 +29,14 @@ import type { CreateKind } from "./types.js";
 // Static params (mirrors of the generators' prompts — see the module doc)
 // =============================================================================
 
-/** `--framework` — the three component generators collapsed to one enum. */
+/** `--framework` — the declared component generators collapsed to one enum. */
 const FRAMEWORK_PARAM: ParamSpec = {
   kind: "enum",
   name: "framework",
   doc: "Component framework.",
-  values: ["react", "svelte", "lit"],
-  default: "react",
+  values: CREATE_GENERATORS.component.frameworks,
+  // The FIRST declared framework, so the default is always inside the enum.
+  default: CREATE_GENERATORS.component.frameworks[0],
 };
 
 /**
@@ -129,6 +132,13 @@ const PACKAGE_MIRROR: PromptDefinition[] = [
   },
 ];
 
+// The include-flag prompts carry the CLI grammar's `--with-X` names
+// (`withSsr`/`withRouter`/`withForms`/`withRelay`, AV-228 B8) rather than the
+// summon generator's bare prompt names (`ssr`/`router`/`forms`/`relay`). {@link
+// INCLUDE_FLAG_ALIASES} maps them back at the CLI↔generator boundary so the
+// generator prompt names — and their embedded templates + byte-equality
+// goldens — stay stable. `--run-install` (default false) is an action flag, not
+// an include, so it keeps its spelling.
 const APPLICATION_MIRROR: PromptDefinition[] = [
   {
     name: "appPath",
@@ -137,21 +147,21 @@ const APPLICATION_MIRROR: PromptDefinition[] = [
     default: "my-app",
     positional: true,
   },
-  { name: "ssr", type: "confirm", message: "Include SSR?", default: true },
+  { name: "withSsr", type: "confirm", message: "Include SSR?", default: true },
   {
-    name: "router",
+    name: "withRouter",
     type: "confirm",
     message: "Include router?",
     default: true,
   },
   {
-    name: "forms",
+    name: "withForms",
     type: "confirm",
     message: "Include form components?",
     default: true,
   },
   {
-    name: "relay",
+    name: "withRelay",
     type: "confirm",
     message: "Include a Relay (GraphQL) data layer?",
     default: false,
@@ -164,6 +174,50 @@ const APPLICATION_MIRROR: PromptDefinition[] = [
   },
 ];
 
+/**
+ * CLI include-flag names → summon generator prompt names, per create kind
+ * (AV-228 B8). All four `create application` include-flags are exposed on the
+ * unified `--with-X` convention, so their params arrive keyed `withSsr`/
+ * `withRouter`/`withForms`/`withRelay`; the summon generator reads the bare
+ * `ssr`/`router`/`forms`/`relay`. We normalize at the ONE CLI↔generator seam
+ * ({@link toGeneratorAnswers}), keeping the generator prompt names (and their
+ * templates/goldens) untouched. Component and package already use `--with-X`
+ * names that match their prompts, so their maps are empty.
+ */
+export const INCLUDE_FLAG_ALIASES: Record<
+  CreateKind,
+  Readonly<Record<string, string>>
+> = {
+  component: {},
+  package: {},
+  application: {
+    withSsr: "ssr",
+    withRouter: "router",
+    withForms: "forms",
+    withRelay: "relay",
+  },
+};
+
+/**
+ * Re-key a param bag's CLI include-flag aliases to the generator prompt names,
+ * so the summon generator reads `ssr` where the CLI grammar exposes `--with-ssr`.
+ *
+ * @param kind - The create noun (selects the alias map).
+ * @param params - The coerced CLI/MCP param bag.
+ * @returns A new bag with aliased keys renamed to the generator prompt names.
+ */
+export function toGeneratorAnswers(
+  kind: CreateKind,
+  params: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const aliases = INCLUDE_FLAG_ALIASES[kind];
+  const answers: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(params)) {
+    answers[aliases[key] ?? key] = value;
+  }
+  return answers;
+}
+
 const componentParams: ParamSpec[] = [
   FRAMEWORK_PARAM,
   COMPONENT_PATH_PARAM,
@@ -183,20 +237,16 @@ const PATH_PARAM: Record<CreateKind, string | undefined> = {
 // The lazy run — the one-line summon↔pragma seam per invocation
 // =============================================================================
 
-/**
- * Build the `create` Task for one invocation: pick the generator, jail its
- * output path, pre-validate flag/arg answers, pick the prompt strategy against
- * the interaction context, wire `runtime.exec`, and return `execute`.
- *
- * @returns A `Promise<Task<GeneratorResult>>` (the union's third arm) the
- *   dispatcher/MCP handler awaits into a Task before interpreting.
- */
 /**
  * The standalone `bun build --compile` binary resolves every bundled module
  * under the virtual `/$bunfs` filesystem — a marker absent from any source or
- * `bun`-run module URL. `create component` is fully embedded and runs from the
- * binary; `create package` / `create application` are NOT (application also
- * copies non-`.ejs` assets), so they are gated to a source run below.
+ * `bun`-run module URL. Only a generator that routes its template reads through
+ * the embedded manifest can run there
+ * (`CREATE_GENERATORS[kind].readsEmbeddedTemplates`);
+ * the others call `template({ source })`, which falls through to
+ * `readFile(source)` and dies with `ENOENT … /$bunfs/…` after `mkdir` has
+ * already run, leaving partially-created files behind.
+ * `compiledCreate.subprocess.test.ts` pins the refusal AND the empty cwd.
  */
 const IS_COMPILED_BINARY = import.meta.url.includes("/$bunfs/");
 
@@ -230,23 +280,22 @@ export function isModuleNotFound(cause: unknown): boolean {
  * `--compile` bundler includes them — they stay behind this lazy boundary, so
  * the fast paths and `create --yes` still load neither summon-core nor React).
  *
- * The manifest is injected BEFORE `pickGenerator` — importing the generator
- * packages runs a top-level `await loadTemplate`, and the component loader
- * consults the manifest when its disk read fails (the compiled binary). It is
- * imported from summon-component's `loadTemplate` submodule so this does not
- * evaluate the generator index first. In a source run the disk read wins and the
- * manifest is inert.
+ * The manifest is injected BEFORE `pickGenerator` — the component loader
+ * consults it when its disk read fails (the compiled binary), and the generators
+ * load their templates on first `generate()`. It is imported from
+ * summon-component's `loadTemplate` submodule so this does not evaluate the
+ * generator index first. In a source run the disk read wins and the manifest is
+ * inert.
  *
- * `create package` / `create application` are not yet embedded for the compiled
- * binary (application also copies non-`.ejs` assets), so they are gated to a
- * source run here. A stale resolution failure is a defensive backstop
- * {@link isModuleNotFound} turns into the same clean gate.
+ * A binding whose generator does not read through that manifest is gated to a
+ * source run here ({@link IS_COMPILED_BINARY}). A stale resolution failure is a
+ * defensive backstop {@link isModuleNotFound} turns into the same clean gate.
  */
 async function loadCreateRuntime(kind: CreateKind) {
-  if (IS_COMPILED_BINARY && kind !== "component") {
+  if (IS_COMPILED_BINARY && !CREATE_GENERATORS[kind].readsEmbeddedTemplates) {
     throw new PragmaError({
       code: "UNSUPPORTED",
-      message: `\`create ${kind}\` is not available in the compiled pragma binary yet — only \`create component\` is embedded. Run it from a source checkout, or use the \`summon\` CLI.`,
+      message: `\`create ${kind}\` is not available in the compiled ${BIN_NAME} binary — ${SOURCE_ONLY_REASON}. Run it from a source checkout, or use the \`summon\` CLI.`,
       recovery: {
         message: `Run \`create ${kind}\` from a source checkout, or use \`summon\`.`,
       },
@@ -280,26 +329,42 @@ async function loadCreateRuntime(kind: CreateKind) {
   }
 }
 
+/**
+ * Build the `create` Task for one invocation: pick the generator, jail its
+ * output path, pre-validate flag/arg answers, pick the prompt strategy against
+ * the interaction context, wire `runtime.exec`, and return `execute`.
+ *
+ * @param kind - The create noun.
+ * @param params - The coerced params for this invocation.
+ * @param rt - The pragma runtime.
+ * @returns A `Promise<Task<GeneratorResult>>` (the union's third arm) the
+ *   dispatcher/MCP handler awaits into a Task before interpreting.
+ */
 async function runCreate(
   kind: CreateKind,
   params: Record<string, unknown>,
   rt: PragmaRuntime,
 ): Promise<Task<GeneratorResult>> {
-  // Lazy: importing these runs the generators' top-level template loads and
-  // pulls summon-core — kept off every non-create path. Now STATIC dynamic
-  // imports so `--compile` bundles them; the generators' `.ejs` are embedded and
-  // injected here. `package`/`application` stay a source-run feature in the binary.
+  // Lazy: importing these pulls summon-core (and with it React) — kept off every
+  // non-create path. Now STATIC dynamic imports so `--compile` bundles them; the
+  // embedded `.ejs` manifest is injected here. A binding that does not read
+  // through it stays a source-run feature in the binary.
   const { pickGenerator, summon } = await loadCreateRuntime(kind);
 
-  const generator = pickGenerator(kind, params);
+  // Normalize the CLI/MCP `--with-X` include-flags to the generator prompt names
+  // (AV-228 B8) once, at this seam; every summon interaction below reads the
+  // generator-facing `answers` bag so the generator prompt names stay stable.
+  const answers = toGeneratorAnswers(kind, params);
+
+  const generator = pickGenerator(kind, answers);
 
   // SEC-2: reject a path escaping the workspace BEFORE any effect runs.
   const pathParam = PATH_PARAM[kind];
-  if (pathParam) assertInsideWorkspace(pathParam, params[pathParam], rt.cwd);
+  if (pathParam) assertInsideWorkspace(pathParam, answers[pathParam], rt.cwd);
 
   // Reject a flag/arg-provided answer that fails its prompt's own constraint,
   // with a clean INVALID_INPUT (execute re-validates as a backstop).
-  const invalid = summon.validateAnswers(generator.prompts, params);
+  const invalid = summon.validateAnswers(generator.prompts, answers);
   if (invalid !== null) {
     throw new PragmaError({ code: "INVALID_INPUT", message: invalid });
   }
@@ -318,7 +383,13 @@ async function runCreate(
     // `onCancel` (H2): an in-Ink Ctrl-C during execution aborts the run so the
     // interpreter stops writing — raw mode swallows the SIGINT, so the wizard
     // drives the abort. Shared with setup by construction.
-    const session = summon.inkPrompt(generator, { signal, onCancel: abort });
+    // `cwd` also reaches the wizard: its confirm-gate preview reads the same
+    // jail-checked write root the interpreter resolves effect paths against.
+    const session = summon.inkPrompt(generator, {
+      signal,
+      onCancel: abort,
+      cwd: rt.cwd,
+    });
     // Thread the per-call write root: the interpreter resolves the generator's
     // relative output paths against `rt.cwd` — the SAME dir the SEC-2 jail
     // validated above — so the write can never escape the checked directory.
@@ -336,14 +407,16 @@ async function runCreate(
     };
     return summon.execute(generator, {
       prompt: session.promptHandler,
-      params,
+      params: answers,
       signal,
     });
   }
 
   // Non-interactive: MCP → params-or-error; CLI/--yes/CI → flags+defaults.
   const prompt =
-    transport === "mcp" ? summon.mcpPrompt(params) : summon.autoPrompt(params);
+    transport === "mcp"
+      ? summon.mcpPrompt(answers)
+      : summon.autoPrompt(answers);
   // Same per-call write root as the Ink branch: `rt.cwd` feeds both the SEC-2
   // jail and the interpreter's effect-path base, atomically.
   rt.exec = {
@@ -353,7 +426,7 @@ async function runCreate(
     onLog: (_level, message) => process.stderr.write(`${message}\n`),
     signal,
   };
-  return summon.execute(generator, { prompt, params, signal });
+  return summon.execute(generator, { prompt, params: answers, signal });
 }
 
 /**
@@ -375,10 +448,51 @@ const CREATE_CAPABILITY = {
   },
 };
 
+/**
+ * Why a binding is source-run only — the ONE authoring of it, shared by the
+ * documentation below and by {@link loadCreateRuntime}'s `UNSUPPORTED` refusal,
+ * so what the reference promises and what the binary does cannot disagree.
+ */
+const SOURCE_ONLY_REASON =
+  "its generator reads templates from disk, which the binary does not carry";
+
+/**
+ * The published caveat for a binding the compiled binary cannot run. DERIVED
+ * from `CREATE_GENERATORS[kind].readsEmbeddedTemplates` — flipping that bit
+ * moves the caveat, `docs/reference/*.md`, and `create.test.ts`'s binding
+ * assertion together.
+ *
+ * It LEADS WITH THE PURPOSE, because `tools.md` and the MCP tool description
+ * both render `doc ?? summary` — so a caveat alone REPLACED the only sentence
+ * saying what the tool makes, and an agent enumerating tools could not learn
+ * that `create_package` scaffolds a package. The tool works from a source
+ * checkout; describing nothing but its refusal made a live tool
+ * undiscoverable. The repeated sentence in `commands.md`'s section is the
+ * cheaper of the two costs.
+ *
+ * It names no CLI flag (`mcp/toolDescriptions.test.ts` forbids one, and an
+ * agent has no flags): the plan-only refusal is stated in the terms BOTH
+ * surfaces share.
+ *
+ * @param kind - The create binding.
+ * @param summary - The verb's own one-liner, which the `doc` replaces on MCP.
+ * @returns The `doc` for a source-run-only binding, or `undefined`.
+ */
+function buildAvailabilityDoc(
+  kind: CreateKind,
+  summary: string,
+): string | undefined {
+  if (CREATE_GENERATORS[kind].readsEmbeddedTemplates) return undefined;
+  return `${summary} From the compiled ${BIN_NAME} binary, \`create ${kind}\` refuses with \`UNSUPPORTED\` and writes nothing. Asking it only to PLAN refuses too — the gate runs while the plan is built — so a successful plan is never evidence it would run. The cause is that ${SOURCE_ONLY_REASON}. Run it from a source checkout, or use the \`summon\` CLI.`;
+}
+
 /**
  * Build a create verb. `run` presents `Promise<Task<R>>` through the `Task<R>`
  * arm by an honest cast at this one site (mirroring `sources update`): a literal
  * `Promise<Task<R>>` arm in the union would poison async read-verb inference.
+ *
+ * A binding the compiled binary cannot run says so in its `summary` (which is
+ * what `--help` and the noun listing show) and explains itself in its `doc`.
  */
 function createVerb(
   kind: CreateKind,
@@ -386,9 +500,11 @@ function createVerb(
   params: ParamSpec[],
   examples: VerbSpec["examples"],
 ): VerbSpec<Record<string, unknown>, GeneratorResult> {
+  const doc = buildAvailabilityDoc(kind, summary);
   return {
     path: ["create", kind],
-    summary,
+    summary: doc ? `${summary} Source-run only.` : summary,
+    ...(doc ? { doc } : {}),
     params,
     output: { formatters: createFormatters },
     examples,
@@ -398,38 +514,51 @@ function createVerb(
   };
 }
 
-export const createComponentVerb = createVerb(
-  "component",
-  "Scaffold a React, Svelte, or Lit component.",
-  componentParams,
-  [
-    {
-      cmd: "pragma create component src/components/Button --framework react",
-      note: "React component with tests, stories, and styles",
-    },
-    {
-      cmd: "pragma create component src/lib/Card --framework svelte --dry-run",
-      note: "preview the files without writing",
-    },
-  ],
-);
-
-export const createPackageVerb = createVerb(
-  "package",
-  "Scaffold a new npm package for the monorepo.",
-  packageParams,
-  [
-    { cmd: "pragma create package --name @canonical/my-lib --type library" },
-    { cmd: "pragma create package --name @canonical/my-tool --run-install" },
-  ],
-);
-
-export const createApplicationVerb = createVerb(
-  "application",
-  "Scaffold a full React application with SSR and routing.",
-  applicationParams,
-  [
-    { cmd: "pragma create application my-app" },
-    { cmd: "pragma create application my-app --relay" },
-  ],
-);
+/**
+ * The `create` verbs, one per declared generator binding — so adding a binding
+ * to {@link CREATE_GENERATORS} without surfacing it is a type error rather than
+ * a silent no-op. Key order is authoring order, which `index.ts` preserves into
+ * the command tree, `--help` and the emitted surface.
+ */
+export const createVerbs: Record<
+  CreateKind,
+  VerbSpec<Record<string, unknown>, GeneratorResult>
+> = {
+  component: createVerb(
+    "component",
+    "Scaffold a React, Svelte, or Lit component.",
+    componentParams,
+    [
+      {
+        cmd: `${BIN_NAME} create component src/components/Button --framework react`,
+        note: "React component with tests, stories, and styles",
+      },
+      {
+        cmd: `${BIN_NAME} create component src/lib/Card --framework svelte --dry-run`,
+        note: "preview the files without writing",
+      },
+    ],
+  ),
+  package: createVerb(
+    "package",
+    "Scaffold a new npm package for the monorepo.",
+    packageParams,
+    [
+      {
+        cmd: `${BIN_NAME} create package --name @canonical/my-lib --type library`,
+      },
+      {
+        cmd: `${BIN_NAME} create package --name @canonical/my-tool --run-install`,
+      },
+    ],
+  ),
+  application: createVerb(
+    "application",
+    "Scaffold a full React application with SSR and routing.",
+    applicationParams,
+    [
+      { cmd: `${BIN_NAME} create application my-app` },
+      { cmd: `${BIN_NAME} create application my-app --with-relay` },
+    ],
+  ),
+};

package/src/capabilities/create/index.ts

@@ -8,18 +8,10 @@
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
 import type { CapabilityModule } from "../../kernel/spec/types.js";
-import {
-  createApplicationVerb,
-  createComponentVerb,
-  createPackageVerb,
-} from "./create.verb.js";
+import { createVerbs } from "./create.verb.js";
 
 /** The `create` capability module. */
 export const createModule: CapabilityModule = {
   name: "create",
-  verbs: [
-    asVerb(createComponentVerb),
-    asVerb(createPackageVerb),
-    asVerb(createApplicationVerb),
-  ],
+  verbs: Object.values(createVerbs).map(asVerb),
 };

package/src/capabilities/create/pickGenerator.ts

@@ -1,38 +1,46 @@
-/**
- * Select the summon generator for a `create` invocation.
- *
- * This module statically imports the summon generator packages' `generators`
- * maps — and importing them runs a top-level `await loadTemplate` that reads
- * every template file from disk. So this module MUST stay behind `create`'s
- * lazy `import()` (R9): the fast paths (`buildProgram` / `__complete` / `--help`
- * / reads) never load it, and `create --yes` never loads React either (the
- * generators pull summon-core, whose Ink UI is dynamic-only).
- */
-
 import { generators as applicationGenerators } from "@canonical/summon-application";
 import { generators as componentGenerators } from "@canonical/summon-component";
 import type { GeneratorDefinition } from "@canonical/summon-core";
 import { generators as packageGenerators } from "@canonical/summon-package";
 import { PragmaError } from "../../kernel/error/PragmaError.js";
+import { CREATE_GENERATORS } from "./constants.js";
 import type { CreateKind } from "./types.js";
 
-/** The component frameworks that collapse to one `create component` verb. */
-export const FRAMEWORKS = ["react", "svelte", "lit"] as const;
+type GeneratorMap = Record<string, GeneratorDefinition | undefined>;
 
 /**
- * The generators' `generate` is invariant in its (specific) answer type, so the
- * strongly-typed maps are erased to the base definition via `unknown`. This is
- * runtime-safe: `execute` calls `generate(answers)` with the resolved answers,
- * which carry the fields the specific generator reads.
+ * The declared packages' generator maps, bound by noun. The STATIC imports above
+ * are load-bearing: `bun build --compile` bundles only statically analysable
+ * specifiers, so `import(CREATE_GENERATORS[kind].name)` would leave the
+ * generators out of the binary (measured: `Cannot find module
+ * '@canonical/summon-component' from '/$bunfs/root/…'`). The declaration decides
+ * WHICH generator runs; it cannot decide which module is linked.
+ *
+ * The maps' `generate` is invariant in its (specific) answer type, so they are
+ * erased to the base definition via `unknown` — runtime-safe because `execute`
+ * calls `generate(answers)` with the resolved answers, which carry the fields
+ * the specific generator reads.
  */
-type GeneratorMap = Record<string, GeneratorDefinition | undefined>;
-const componentMap = componentGenerators as unknown as GeneratorMap;
-const packageMap = packageGenerators as unknown as GeneratorMap;
-const applicationMap = applicationGenerators as unknown as GeneratorMap;
+const GENERATOR_MAPS: Record<CreateKind, GeneratorMap> = {
+  component: componentGenerators as unknown as GeneratorMap,
+  package: packageGenerators as unknown as GeneratorMap,
+  application: applicationGenerators as unknown as GeneratorMap,
+};
 
 /**
  * Pick the generator for a `create <kind>` run.
  *
+ * The module this lives in statically imports the summon generator packages'
+ * `generators` maps — and importing them pulls summon-core. So it MUST stay
+ * behind `create`'s lazy `import()` (R9): the fast paths (`buildProgram` /
+ * `__complete` / `--help` / reads) never load it, and `create --yes` never loads
+ * React either (summon-core's Ink UI is dynamic-only).
+ *
+ * `component` is branched on literally: it is the only noun with a framework
+ * axis (which is why the verb synthesises a `--framework` enum), and narrowing
+ * on `kind` here lets `CREATE_GENERATORS[kind].key` type-check over the
+ * remaining nouns without `in`-narrowing gymnastics.
+ *
  * @param kind - The create noun.
  * @param params - The coerced params (used for `--framework` on `component`).
  * @returns The selected generator definition.
@@ -43,19 +51,17 @@ export function pickGenerator(
   params: Readonly<Record<string, unknown>>,
 ): GeneratorDefinition {
   if (kind === "component") {
-    const framework = String(params.framework ?? "react");
-    const generator = componentMap[`component/${framework}`];
+    const { frameworks } = CREATE_GENERATORS.component;
+    const framework = String(params.framework ?? frameworks[0]);
+    const generator = GENERATOR_MAPS.component[`component/${framework}`];
     if (!generator) {
       throw PragmaError.invalidInput("framework", framework, {
-        validOptions: [...FRAMEWORKS],
+        validOptions: [...frameworks],
       });
     }
     return generator;
   }
-  const generator =
-    kind === "package"
-      ? packageMap.package
-      : applicationMap["application/react"];
+  const generator = GENERATOR_MAPS[kind][CREATE_GENERATORS[kind].key];
   if (!generator) {
     throw PragmaError.internalError(`missing ${kind} generator`);
   }