@canonical/pragma-cli 0.34.0 → 0.36.0

package/src/capabilities/config/types.ts

@@ -2,7 +2,11 @@
  * Data shapes for `pragma config show`.
  */
 
-import type { ConfigOrigins, PragmaConfig } from "../../kernel/config/types.js";
+import type {
+  ConfigOrigin,
+  ConfigOrigins,
+  PragmaConfig,
+} from "../../kernel/config/types.js";
 
 /** The resolved configuration plus per-field provenance and layer locations. */
 export interface ConfigShowData {
@@ -22,14 +26,24 @@ export interface ConfigShowData {
   readonly globalExists: boolean;
 }
 
-/** The outcome of a `config <field>` setter (set, or reset via sentinel). */
+/** The outcome of a config write (`set` writes a value, `unset` clears one). */
 export interface ConfigFieldResult {
   /** The config field written (`tier` / `channel` / `detail`). */
   readonly field: string;
-  /** The value written, or absent when the field was reset (removed). */
+  /** The value written, or absent when the field was cleared (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. */
+  /** True when `unset` removed the field rather than setting a value. */
   readonly reset: boolean;
 }
+
+/** The payload of `config get <key>` — one resolved value with provenance. */
+export interface ConfigGetData {
+  /** The config field read (`tier` / `channel` / `detail`). */
+  readonly field: string;
+  /** The effective value after layering, absent when the field is unset. */
+  readonly value?: unknown;
+  /** The layer that supplied the value (`default` / `global` / `project`). */
+  readonly source: ConfigOrigin;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * `config unset <key>` — clear one config field.
+ *
+ * Clearing is a COMMAND, not a magic value: `config set` refuses the values
+ * that used to double as clear-markers, and this verb owns the job. Removes
+ * the field from the global layer so the built-in default (or a project
+ * config) applies again; project configs are authored by hand and never
+ * written here.
+ */
+
+import type { Task } from "@canonical/task";
+import { BIN_NAME } from "../../constants.js";
+import { asVerb } from "../../kernel/spec/asVerb.js";
+import type { VerbSpec } from "../../kernel/spec/index.js";
+import { configFieldFormatters } from "./field.render.js";
+import { CONFIG_FIELDS } from "./fields.js";
+import type { ConfigFieldResult } from "./types.js";
+
+/** The clearable field names — the `<key>` enum, in covenant order. */
+const CONFIG_KEYS = CONFIG_FIELDS.map((field) => field.field);
+
+const unsetVerb: VerbSpec<Record<string, unknown>, ConfigFieldResult> = {
+  path: ["config", "unset"],
+  summary: "Clear a config field by name.",
+  doc: "Removes a field from the global config so the built-in default (or a project config) applies again. The counterpart of `config set` — setting writes a value, unsetting removes one; no value doubles as a remove-marker.",
+  params: [
+    {
+      kind: "enum",
+      name: "key",
+      doc: "The config field to clear.",
+      values: CONFIG_KEYS,
+      required: true,
+      positional: true,
+    },
+  ],
+  output: { formatters: configFieldFormatters },
+  examples: [
+    { cmd: `${BIN_NAME} config unset tier`, note: "read the full graph again" },
+    { cmd: `${BIN_NAME} config unset channel` },
+  ],
+  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 `config set` uses.
+  run: (params) =>
+    import("./runSet.js").then((m) =>
+      m.runUnset(params),
+    ) as unknown as Task<ConfigFieldResult>,
+};
+
+/** The `config unset` verb. */
+export const configUnsetVerb = asVerb(unsetVerb);

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

@@ -48,9 +48,8 @@ describe("cross-binary byte-equality (PROTECTED)", () => {
         pragmaBin,
         "create",
         "component",
-        "src/components/Button",
-        "--framework",
         "react",
+        "src/components/Button",
         "--yes",
       ],
       { cwd: pragmaDir, stdio: "pipe" },
@@ -66,7 +65,7 @@ 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" });
+const gen = pickGenerator("component/react");
 await runGeneratorTask(execute(gen, { prompt: autoPrompt(answers), params: answers }), {
   cwd: dir,
   promptHandler: autoPrompt(answers),

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

@@ -36,6 +36,7 @@ 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 { blankCanonicalRanges } from "../../testing/helpers/blankCanonicalRanges.js";
 import { createVerbs } from "./create.verb.js";
 import type { CreateKind } from "./types.js";
 
@@ -82,8 +83,16 @@ async function produceSummon(
   answers: Readonly<Record<string, unknown>>,
 ): Promise<TreeSnapshot> {
   const { pickGenerator } = await import("./pickGenerator.js");
+  // pickGenerator is keyed by FULL COMMAND PATH now; this surface still
+  // thinks in kind+framework, so map first (exactly as runCreate does).
+  const commandPath =
+    kind === "component"
+      ? `component/${framework}`
+      : kind === "package"
+        ? "package"
+        : "application/react";
   return produceReference({
-    generator: pickGenerator(kind, { framework }),
+    generator: pickGenerator(commandPath),
     answers,
   });
 }
@@ -156,16 +165,13 @@ const cases: Case[] = [
     fixture: "application",
     kind: "application",
     framework: "",
-    // 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.
+    // The prompt names ARE the param names now (the B8 alias seam is gone):
+    // the pragma path takes the generator's own `forms`/`relay` (ssr/router
+    // are always-on facts, no longer prompts).
     params: {
       appPath: "my-app",
-      withSsr: true,
-      withRouter: true,
-      withForms: true,
-      withRelay: false,
+      forms: true,
+      relay: false,
       runInstall: false,
     },
   },
@@ -186,12 +192,20 @@ describe("byte-equality goldens — pragma create \u2261 the conformance referen
         (entry) => entry.name === testCase.fixture,
       );
       if (!shared) throw new Error(`no fixture "${testCase.fixture}"`);
-      const pragma = await producePragma(testCase.kind, testCase.params);
-      const reference = await produceSummon(
+      let pragma = await producePragma(testCase.kind, testCase.params);
+      let reference = await produceSummon(
         testCase.kind,
         testCase.framework,
         shared.answers,
       );
+      // Two independent `npm view` resolutions feed the application tree
+      // (one per producer); blank the @canonical/* ranges identically so an
+      // asymmetric registry outcome cannot red this template-surface cell —
+      // range truth lives in the offline subprocess cells.
+      if (testCase.kind === "application") {
+        pragma = blankCanonicalRanges(pragma);
+        reference = blankCanonicalRanges(reference);
+      }
       expect(pragma.size).toBeGreaterThan(0);
       const diff = diffTrees(pragma, reference);
       expect(

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

@@ -1,75 +1,50 @@
 /**
- * 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.
+ * 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 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.
+ * 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.
  *
- * `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.
+ * 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`).
+ * 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,
+    /** The command paths this binding runs (generator-map keys). */
+    paths: ["component/react", "component/svelte", "component/lit"],
   },
   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,
+    paths: ["package"],
   },
   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,
+    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

@@ -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();
@@ -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);
     }