@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/create/cliProjection.ts

@@ -0,0 +1,227 @@
+/**
+ * The `create` module's CLI projection hook — the LIGHT half of the mount.
+ *
+ * This module is on the capabilities barrel, so `--help` and `__complete`
+ * import it on every spawn; it must therefore carry only what those paths
+ * actually read: the completion surface and the reference syntax, both
+ * derived from the build-time projection (`createSurface.generated.ts`) —
+ * the registered flag/positional spellings are BAKED there
+ * (`CREATE_CLI_SYNTAX`), so nothing here calls the projection to re-derive a
+ * token. The registration machinery itself — summon-core's Commander adapter,
+ * the interaction decisions, Commander — lives in `mount.ts` behind the
+ * dynamic import `prepare()` performs, which only a caller about to build the
+ * command tree ever awaits. The lazy-graph guard in `lazy.test.ts` pins this
+ * boundary.
+ */
+
+import type { ProjectedPrompt } from "@canonical/summon-core/projection";
+import { BIN_NAME } from "../../constants.js";
+import type {
+  CliMountHost,
+  CliProjection,
+  CompletionChildFlag,
+  CompletionChildSpec,
+  ReferenceCliSyntax,
+  VerbSpec,
+} from "../../kernel/spec/types.js";
+import { CREATE_GENERATORS } from "./constants.js";
+import {
+  CREATE_CLI_SYNTAX,
+  CREATE_SURFACE,
+} from "./createSurface.generated.js";
+import type { CreateKind, PromptCliSyntax } from "./types.js";
+
+/** Build the mount (the module-level CLI projection hook). */
+export function createCliProjection(): CliProjection {
+  // The registration import is DEFERRED to `prepare()`: only the one caller
+  // that actually builds the command tree (the bin, before `buildProgram`)
+  // pays for summon-core's adapter and Commander — never the
+  // `--help`/`__complete` barrel import. `mount` stays synchronous for
+  // `buildProgram` and throws when the step was skipped, so the coupling
+  // fails loudly instead of registering an empty subtree.
+  let mountCreateTree: typeof import("./mount.js").mountCreateTree | undefined;
+  return {
+    prepare: async (): Promise<void> => {
+      ({ mountCreateTree } = await import("./mount.js"));
+    },
+    mount: (parent, host: CliMountHost): void => {
+      if (!mountCreateTree) {
+        throw new Error(
+          "create mount used before prepare() — await CliProjection.prepare() before buildProgram",
+        );
+      }
+      mountCreateTree(parent, host);
+    },
+    completionChildren,
+    referenceIntro: REFERENCE_INTRO,
+    referenceSyntax,
+  };
+}
+
+/**
+ * The baked registered spelling for a prompt, from the first declared path
+ * that carries it (a prompt's spelling derives from its own shape, so every
+ * declaring path bakes the same tokens).
+ */
+function syntaxFor(
+  paths: readonly string[],
+  promptName: string,
+): PromptCliSyntax {
+  for (const commandPath of paths) {
+    const syntax = CREATE_CLI_SYNTAX[commandPath]?.[promptName];
+    if (syntax) return syntax;
+  }
+  throw new Error(
+    `createSurface.generated.ts bakes no CLI syntax for prompt "${promptName}" — rerun the build`,
+  );
+}
+
+/** The leaves' prompts, unioned by first-seen name (the binding param order). */
+function unionPrompts(paths: readonly string[]): ProjectedPrompt[] {
+  const seen = new Set<string>();
+  const union: ProjectedPrompt[] = [];
+  for (const commandPath of paths) {
+    for (const prompt of CREATE_SURFACE[commandPath]?.prompts ?? []) {
+      if (seen.has(prompt.name)) continue;
+      seen.add(prompt.name);
+      union.push(prompt);
+    }
+  }
+  return union;
+}
+
+/**
+ * The REGISTERED reference syntax for one binding verb (the mounted spelling
+ * the generated reference prints): the usage line carries the real tree
+ * segment (`create application react …`, `<framework>` for the multi-leaf
+ * binding — its values live in the Args table) and the registered kebab
+ * positional, which is also handed over as the per-param positional token so
+ * the Arguments table prints the SAME spelling; each flag token is the one
+ * the mount actually registers (a default-true confirm registers ONLY its
+ * `--no-` form), read from the BAKED syntax the build derived with the same
+ * flag-shape authority the mount registers through. Reached only through
+ * {@link createCliProjection} — one seam, THREE consumers, all speaking
+ * registration: the kernel's reference emitter (the reference pins read the
+ * committed pages it produced), `emitSurface` (the covenant's mounted-noun
+ * flag + positional tokens, L-CIS-2), and the `docExamples` gate's
+ * valid-token vocabulary. A change of meaning here moves all three together —
+ * the covenant conformance and derivation-tie cells in surface.test.ts are
+ * the tripwire.
+ */
+function referenceSyntax(
+  verbPath: VerbSpec["path"],
+): ReferenceCliSyntax | undefined {
+  const kind = verbPath[1] as CreateKind | undefined;
+  const binding = kind ? CREATE_GENERATORS[kind] : undefined;
+  if (verbPath[0] !== "create" || !binding) return undefined;
+  const paths = binding.paths as readonly string[];
+  const first = paths[0] as string;
+
+  const tokens: string[] = ["create", kind as string];
+  if (paths.length > 1) tokens.push("<framework>");
+  else if (first.includes("/")) tokens.push(first.split("/")[1] as string);
+  const prompts = unionPrompts(paths);
+  const positional = prompts.find((prompt) => prompt.positional === true);
+  const positionalTokens: Record<string, string> = {};
+  if (positional) {
+    const token = `[${syntaxFor(paths, positional.name).kebabName}]`;
+    tokens.push(token);
+    positionalTokens[positional.name] = token;
+  }
+  tokens.push("[options]");
+
+  const flagTokens: Record<string, string> = {};
+  for (const prompt of prompts) {
+    if (prompt.positional === true) continue;
+    flagTokens[prompt.name] = syntaxFor(paths, prompt.name).flag;
+  }
+  return { usage: tokens.join(" "), flagTokens, positionalTokens };
+}
+
+/**
+ * One leaf's completion node, derived from its projected prompts. EVERY
+ * prompt is a flag — `addPromptOptions` registers positional prompts as
+ * options too (`--component-path` is as real as `--no-with-styles`), the
+ * positional argument being an additional spelling, not a replacement.
+ */
+function leafChild(label: string, commandPath: string): CompletionChildSpec {
+  const surface = CREATE_SURFACE[commandPath];
+  const prompts = surface?.prompts ?? [];
+  return {
+    label,
+    flags: prompts.map((prompt) => promptFlag(commandPath, prompt)),
+    positionals: prompts
+      .filter((prompt) => prompt.positional === true)
+      .map((prompt) => ({
+        name: prompt.name,
+        required: false,
+        files: /(path|dir)$/i.test(prompt.name),
+      })),
+  };
+}
+
+/** A prompt's completion flag: the REGISTERED token (`--no-` for default-true). */
+function promptFlag(
+  commandPath: string,
+  prompt: ProjectedPrompt,
+): CompletionChildFlag {
+  const syntax = syntaxFor([commandPath], prompt.name);
+  return {
+    flag: syntax.flag,
+    takesValue: syntax.takesValue,
+    ...(prompt.type === "select" && prompt.choices && prompt.choices.length > 0
+      ? { values: prompt.choices.map((choice) => choice.value) }
+      : {}),
+  };
+}
+
+/**
+ * The completion surface per verb label: leaves carry their prompt-derived
+ * flags in their REGISTERED spelling; a namespace node offers its segment
+ * values at position 0, the shared leaf positional after it, and the leaf
+ * children for the dynamic tier's precise walk — but NO prompt flags of its
+ * own: Commander registers those on the leaves, so a pre-segment offer
+ * (`create component --use-ts-stories svelte`) completes an ordering the
+ * CLI rejects as an unknown option.
+ */
+function completionChildren(): Readonly<Record<string, CompletionChildSpec>> {
+  const record: Record<string, CompletionChildSpec> = {};
+  for (const [kind, binding] of Object.entries(CREATE_GENERATORS)) {
+    const paths = binding.paths as readonly string[];
+    const first = paths[0] as string;
+    if (paths.length === 1 && !first.includes("/")) {
+      record[kind] = leafChild(kind, first);
+      continue;
+    }
+    const children = paths.map((commandPath) =>
+      leafChild(commandPath.split("/")[1] as string, commandPath),
+    );
+    // The shared tail: every declared leaf carries the same positional shape.
+    const tail = children[0]?.positionals ?? [];
+    record[kind] = {
+      label: kind,
+      flags: [],
+      positionals: [
+        {
+          name: "framework",
+          required: true,
+          values: children.map((child) => child.label),
+        },
+        ...tail,
+      ],
+      children,
+    };
+  }
+  return record;
+}
+
+/** The generated-reference intro under the `create` heading (the pointer). */
+const REFERENCE_INTRO =
+  "The `create` surface is a PROJECTION of the summon generator tree: " +
+  `\`${BIN_NAME} create <path...>\` ≡ \`summon <path...>\` over the declared bindings — ` +
+  "same grammar, same flags, same wizard, byte-identical trees. Tree segments are " +
+  "subcommands (`create component react|svelte|lit`, `create application react`), and " +
+  "every flag derives from the generators' own prompts (a default-on confirm registers " +
+  "only its `--no-` form). The contract is EXECUTED, not written down: " +
+  "`crossCli.subprocess.test.ts` runs both CLIs over the same argv and compares " +
+  "what they emit.";

package/src/capabilities/create/constants.ts

@@ -0,0 +1,50 @@
+/**
+ * The command-path ALLOWLIST of the `create` surface — the one list the
+ * surface's mechanical copies derive from: the `CreateKind` union
+ * (`types.ts`) and the generator lookup (`pickGenerator.ts`). Prose is NOT
+ * derived: the verb summaries in `create.verb.ts` 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 command PATHS it
+ * runs (the generator-map keys, `component/react` … `application/react`).
+ * Templates are NOT this package's concern — each generator package ships
+ * its own under its `dist/esm` tree and loads them itself. The binding is
+ * hand-written because it cannot be discovered:
+ *  - surfacing a noun also needs prose 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;
+ *  - `pickGenerator` imports all three generators STATICALLY. A computed
+ *    `import(name)` is opaque to every bundler and analyser; the historical
+ *    cost was measured under `bun build --compile`, which left the
+ *    generators out of the artifact entirely.
+ *
+ * Every declared path RUNS from a published install. `create.test.ts` pins
+ * what is checkable: every declared path resolves to a generator whose
+ * `meta.name` equals the path.
+ *
+ * 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 command paths this binding runs (generator-map keys). */
+    paths: ["component/react", "component/svelte", "component/lit"],
+  },
+  package: {
+    paths: ["package"],
+  },
+  application: {
+    paths: ["application/react"],
+  },
+} as const;
+
+/**
+ * The component frameworks, DERIVED from the declared tree segments — the
+ * second path segment of each `component/<framework>` binding.
+ */
+export const COMPONENT_FRAMEWORKS: readonly string[] =
+  CREATE_GENERATORS.component.paths.map(
+    (commandPath) => commandPath.split("/")[1] as string,
+  );

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 = {
@@ -51,6 +51,46 @@ describe("create over MCP (PROTECTED)", () => {
     expect(component?.annotations?.destructiveHint).toBe(false);
   });
 
+  it("schemas DERIVE from the prompts: framework is a required enum with no default; application args are the bare prompt names (L-CIS)", async () => {
+    const dir = freshCwd();
+    const mcp = await projectMcp([createModule], dir);
+    cleanup = mcp.cleanup;
+    const tools = await mcp.listTools();
+
+    const component = tools.find((t) => t.name === "create_component");
+    const componentSchema = component?.inputSchema as {
+      properties?: Record<string, { enum?: string[]; default?: unknown }>;
+      required?: string[];
+    };
+    // The framework enum derives from the tree segments — REQUIRED, no default.
+    expect(componentSchema.properties?.framework?.enum).toEqual([
+      "react",
+      "svelte",
+      "lit",
+    ]);
+    expect(componentSchema.properties?.framework?.default).toBeUndefined();
+    expect(componentSchema.required ?? []).toContain("framework");
+    // The svelte-only prompt joins the union.
+    expect(Object.keys(componentSchema.properties ?? {})).toContain(
+      "useTsStories",
+    );
+
+    const application = tools.find((t) => t.name === "create_application");
+    const applicationSchema = application?.inputSchema as {
+      properties?: Record<string, unknown>;
+    };
+    const names = Object.keys(applicationSchema.properties ?? {});
+    // The B8 --with-X aliases are gone: prompt names ARE the arg names — and
+    // ssr/router are gone WITH their prompts (always-on facts, not questions).
+    expect(names).toEqual(
+      expect.arrayContaining(["appPath", "forms", "relay", "runInstall"]),
+    );
+    expect(names).not.toContain("withSsr");
+    expect(names).not.toContain("withRelay");
+    expect(names).not.toContain("ssr");
+    expect(names).not.toContain("router");
+  });
+
   it("plan-first: no confirm → a plan, no files written", async () => {
     const dir = freshCwd();
     const prev = process.cwd();
@@ -76,6 +116,44 @@ describe("create over MCP (PROTECTED)", () => {
     }
   });
 
+  it("the plan payload is the FILTERED plan, not the interpreter transcript", async () => {
+    // This payload is read by an LLM on a token budget. Every internal probe
+    // and every repeat of the output directory spent tokens burying the real
+    // artifacts, so the rows pass the shared `visiblePlanEffects` filter — the
+    // same one the CLI preview applies — and stay `describeEffect` strings,
+    // which is what makes them comparable to the CLI's own `--format json`
+    // plan rather than to its terminal rendering.
+    const dir = freshCwd();
+    const prev = process.cwd();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const result = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "Button",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+      });
+      const plan = (result.data as { plan: string[] }).plan;
+      const body = plan.join("\n");
+      // The interpreter's own bookkeeping is gone: no existence probes, and
+      // no debug commentary (this run is not verbose).
+      expect(body).not.toContain("Check exists:");
+      expect(body).not.toContain("Log [debug]");
+      // The output directory is planned ONCE, however many files it holds.
+      expect(plan.filter((line) => line.startsWith("Created "))).toEqual([
+        "Created Button/",
+      ]);
+      // What the generator meant to say survives; what it whispered does not.
+      expect(plan.at(-1)).toContain("Log [info]: ");
+      expect(readdirSync(dir)).toEqual([]); // nothing written
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
   it("confirm: true → runs for real and writes files", async () => {
     const dir = freshCwd();
     const prev = process.cwd();
@@ -117,7 +195,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",
@@ -126,12 +204,18 @@ describe("create over MCP (PROTECTED)", () => {
           withSsrTests: false,
         },
         { dryRun: true, undo: false, yes: false },
-        bootRuntime(FLAGS, dir),
+        bootRuntime({ ...FLAGS, format: "json" }, dir),
       );
-      // Every planned effect line appears in the CLI dry-run preview too.
-      for (const line of mcpPlan) {
-        expect(cliOutcome.stdout ?? "").toContain(line);
-      }
+      // The two STRUCTURED surfaces carry one plan, string for string. They
+      // are compared against each other rather than against the terminal
+      // rendering, which is deliberately a different shape: a person reads
+      // kind-columned rows, a machine reads the described effects.
+      const cliPlan = (
+        JSON.parse(cliOutcome.stdout as string) as {
+          data: { plan: string[] };
+        }
+      ).data.plan;
+      expect(mcpPlan).toEqual(cliPlan);
     } finally {
       process.chdir(prev);
     }

package/src/capabilities/create/create.render.ts

@@ -1,22 +1,86 @@
 /**
- * Formatters for `create` — plain / llm / json over a {@link GeneratorResult}.
+ * Formatters for `create` — plain / llm / json over a {@link GeneratorResult},
+ * plus the dry-run plan render.
  *
- * Deliberately free of any runtime summon-core (and any Ink) import: the
- * `GeneratorResult` type is imported type-only (erased), and the effect
- * inspection uses `@canonical/task`, which the kernel already loads. So a verb
- * spec carrying these formatters never pulls summon-core onto the
- * `buildProgram` / `--help` / `__complete` fast paths — and never pulls React.
+ * Free of any RUNTIME summon-core import, and of any Ink import: the
+ * `GeneratorResult` type is imported type-only (erased) and the effect
+ * inspection uses `@canonical/task`, which the kernel already loads. This
+ * module sits on the capabilities barrel, so `--help` and `__complete` pay its
+ * import cost on every spawn — the same reason `create.verb.ts` keeps even the
+ * UI-free projection subpath off its static graph. So a verb spec carrying
+ * these formatters never pulls summon-core onto the `buildProgram` / `--help`
+ * / `__complete` fast paths, and never pulls React.
+ *
+ * The plan render matters because pragma and summon scaffold through the SAME
+ * projection: the two bins write byte-identical trees, so a preview that
+ * described that work differently in each was a difference with nothing behind
+ * it. {@link formatCreatePlan} therefore consumes summon's own rules rather
+ * than restating them — the rows, the connectors and the closing line are
+ * whatever `@canonical/summon-core/format` says they are.
  */
 
 import type { GeneratorResult } from "@canonical/summon-core";
 import { type Effect, getAffectedFiles } from "@canonical/task";
-import type { Formatters } from "../../kernel/spec/types.js";
+import { defaultStyle, type RenderStyle } from "../../kernel/render/style.js";
+import type { Formatters } from "../../kernel/spec/index.js";
 
 /** The user-visible mutating effects, de-duplicated by path for MakeDir. */
 function created(effects: readonly Effect[]): string[] {
   return getAffectedFiles([...effects]);
 }
 
+/**
+ * Render a `create --dry-run` plan: the generation summon would describe.
+ *
+ * The kernel's default render dumps every effect the interpreter recorded,
+ * which for a generator means the internal `Exists` probes, the output
+ * directory once per file it holds, and the generator's own log lines — a
+ * transcript rather than a plan. {@link visiblePlanEffects} is the filter that
+ * already exists for exactly this, and {@link formatEffectLine} the row.
+ *
+ * Nothing is stashed on the runtime for this: a generator's plan is not known
+ * until the preview interpreter has walked the Task, so the effects ARE the
+ * plan data. That also keeps `--dry-run --format json` untouched, since the
+ * kernel adds its `targets` key only for a verb that stashed something.
+ *
+ * ASYNC because the formatter is loaded LAZILY, from the light `/format`
+ * subpath — the same dynamic edge `registerVerb.ts` uses for the MCP plan
+ * payload, so both surfaces reach one module and neither puts it on the fast
+ * paths. A dry run is already several filesystem reads deep by the time this
+ * is called; a `--help` spawn never calls it at all.
+ *
+ * COLOUR is decided HERE and handed to the formatter, never left to chalk's
+ * own environment detection. pragma's gate is `defaultStyle()`, which demands
+ * an attended stdout as well as a usable chalk level: nx exports `FORCE_COLOR`
+ * to every test task, so a piped preview would otherwise carry escapes that
+ * the rest of pragma's renderers — and `doctor.render.test.ts`'s pin on
+ * redirected output — do not.
+ *
+ * @param effects - The effects the previewed run recorded, in order.
+ * @param verbose - If true, the generator's debug logs stay in the plan.
+ * @param style - The colour decision; defaults to pragma's own render gate.
+ * @returns The rendered plan, without a trailing newline.
+ */
+export async function formatCreatePlan(
+  effects: readonly Effect[],
+  verbose: boolean,
+  style: RenderStyle = defaultStyle(),
+): Promise<string> {
+  const { effectStyleFor, formatEffectLine, visiblePlanEffects } = await import(
+    "@canonical/summon-core/format"
+  );
+  const rowStyle = effectStyleFor(style.enabled);
+  const rows = visiblePlanEffects(effects, verbose);
+  return [
+    "Plan:",
+    ...rows.map((effect, index) =>
+      formatEffectLine(effect, index === rows.length - 1, rowStyle),
+    ),
+    "",
+    "Dry-run complete. No files were modified.",
+  ].join("\n");
+}
+
 /** The generation's outcome formatters. */
 export const createFormatters: Formatters<GeneratorResult> = {
   plain(result) {