@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/capabilities/config/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Data shapes for `pragma config show`.
+ */
+
+import type { ConfigOrigins, PragmaConfig } from "../../kernel/config/types.js";
+
+/** The resolved configuration plus per-field provenance and layer locations. */
+export interface ConfigShowData {
+  readonly config: PragmaConfig;
+  readonly origins: ConfigOrigins;
+  readonly projectConfigPath?: string;
+  readonly globalConfigPath: string;
+  readonly projectExists: boolean;
+  readonly globalExists: boolean;
+}
+
+/** The outcome of a `config <field>` setter (set, or reset via sentinel). */
+export interface ConfigFieldResult {
+  /** The config field written (`tier` / `channel` / `detail`). */
+  readonly field: string;
+  /** The value written, or absent when the field was reset (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. */
+  readonly reset: boolean;
+}

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

@@ -0,0 +1,88 @@
+/**
+ * PROTECTED — the cross-binary subprocess guard (one representative generator):
+ * the real `pragma` bin's `create component … --yes` vs an independently
+ * launched summon-core `execute` process (the summon bin's exact core path).
+ * A byte-for-byte match across two SEPARATE processes catches bin-level stamp /
+ * version / path divergence that an in-process test could mask.
+ *
+ * NOTE: the summon side runs summon-core `execute` directly rather than the
+ * summon bin — this repo's summon bin ships only its `init`/`example` builtins,
+ * not the canonical component generators — but it is the identical core the bin
+ * uses, in its own process.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../../../../../..");
+const pragmaBin = join(repoRoot, "packages/cli/pragma/src/bin.ts");
+const summonCore = join(repoRoot, "packages/summon/core/dist/esm/index.js");
+const pickGen = join(here, "pickGenerator.ts");
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-xbin-"));
+
+function snapshot(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string, base: string): void => {
+    for (const entry of readdirSync(d, { withFileTypes: true })) {
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(d, entry.name), rel);
+      else out.set(rel, readFileSync(join(d, entry.name), "utf-8"));
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+describe("cross-binary byte-equality (PROTECTED)", () => {
+  it("pragma bin create ≡ summon-core execute across two processes", () => {
+    // (1) The real pragma bin, run in its own process.
+    const pragmaDir = freshCwd();
+    execFileSync(
+      "bun",
+      [
+        pragmaBin,
+        "create",
+        "component",
+        "src/components/Button",
+        "--framework",
+        "react",
+        "--yes",
+      ],
+      { cwd: pragmaDir, stdio: "pipe" },
+    );
+
+    // (2) A separate summon-core execute process (the summon bin's core path).
+    const summonDir = freshCwd();
+    const script = join(freshCwd(), "produce.mjs");
+    writeFileSync(
+      script,
+      `
+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" });
+await runGeneratorTask(execute(gen, { prompt: autoPrompt(answers), params: answers }), {
+  cwd: dir,
+  promptHandler: autoPrompt(answers),
+  onEffectStart: createStampOnEffectStart(createGeneratorStamp(gen)),
+  onLog: () => {},
+});
+`,
+    );
+    execFileSync("bun", [script, summonDir], { stdio: "pipe" });
+
+    const a = snapshot(pragmaDir);
+    const b = snapshot(summonDir);
+    expect(a.size).toBeGreaterThan(0);
+    expect([...a.keys()].sort()).toEqual([...b.keys()].sort());
+    for (const [path, content] of a) {
+      expect(b.get(path), `content of ${path}`).toBe(content);
+    }
+  }, 60000);
+});

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

@@ -0,0 +1,225 @@
+/**
+ * PROTECTED — the permanent seam contract: every `create` tree is produced TWO
+ * ways and diffed byte-for-byte (path set + contents, incl. the "Generated by"
+ * stamp): (1) `pragma create <verb> --yes` through the kernel dispatcher, and
+ * (2) summon-core `execute` with `autoPrompt`, run through `runGeneratorTask` +
+ * the shared stamp — the summon bin's path. They match because both derive the
+ * StampConfig from `createGeneratorStamp` (displayName + version) and run the
+ * SAME `generator.generate` with the SAME answers.
+ *
+ * Five generators are covered: component × {react, svelte, lit}, package, and
+ * application. A cross-binary subprocess guard lives in byteEquality.subprocess.test.ts.
+ */
+
+import { mkdtempSync, readdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import {
+  createApplicationVerb,
+  createComponentVerb,
+  createPackageVerb,
+} from "./create.verb.js";
+import type { CreateKind } from "./types.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const freshCwd = (): string => mkdtempSync(join(tmpdir(), "pragma-golden-"));
+
+/** Read a directory tree into a sorted map of relative path → contents. */
+function snapshot(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string, base: string): void => {
+    for (const entry of readdirSync(d, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(d, entry.name), rel);
+      else out.set(rel, readFileSync(join(d, entry.name), "utf-8"));
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+const verbFor: Record<CreateKind, VerbSpec> = {
+  component: createComponentVerb as VerbSpec,
+  package: createPackageVerb as VerbSpec,
+  application: createApplicationVerb as VerbSpec,
+};
+
+/** Producer (1): the full pragma kernel path — dispatcher runs the create verb. */
+async function producePragma(
+  kind: CreateKind,
+  params: Record<string, unknown>,
+): Promise<Map<string, string>> {
+  const dir = freshCwd();
+  const prev = process.cwd();
+  process.chdir(dir);
+  try {
+    const outcome = await executeVerb(
+      verbFor[kind],
+      params,
+      { dryRun: false, undo: false, yes: true },
+      bootRuntime(FLAGS, dir),
+    );
+    expect(outcome.exitCode).toBe(0);
+  } finally {
+    process.chdir(prev);
+  }
+  return snapshot(dir);
+}
+
+/** Producer (2): summon-core execute + autoPrompt + the shared stamp core. */
+async function produceSummon(
+  kind: CreateKind,
+  framework: string,
+  answers: Record<string, unknown>,
+): Promise<Map<string, string>> {
+  const { pickGenerator } = await import("./pickGenerator.js");
+  const {
+    execute,
+    autoPrompt,
+    runGeneratorTask,
+    createGeneratorStamp,
+    createStampOnEffectStart,
+  } = await import("@canonical/summon-core");
+  const generator = pickGenerator(kind, { framework });
+  const dir = freshCwd();
+  await runGeneratorTask(
+    execute(generator, { prompt: autoPrompt(answers), params: answers }),
+    {
+      cwd: dir,
+      promptHandler: autoPrompt(answers),
+      onEffectStart: createStampOnEffectStart(createGeneratorStamp(generator)),
+      onLog: () => {},
+    },
+  );
+  return snapshot(dir);
+}
+
+/** One golden case: the create-verb params, and the equivalent summon answers. */
+interface Case {
+  readonly name: string;
+  readonly kind: CreateKind;
+  readonly framework: string;
+  readonly params: Record<string, unknown>;
+  readonly answers: Record<string, unknown>;
+}
+
+const componentAnswers = {
+  withStyles: true,
+  withStories: true,
+  withSsrTests: false,
+};
+
+const cases: Case[] = [
+  {
+    name: "component/react",
+    kind: "component",
+    framework: "react",
+    params: {
+      framework: "react",
+      componentPath: "src/components/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/components/Button", ...componentAnswers },
+  },
+  {
+    name: "component/svelte",
+    kind: "component",
+    framework: "svelte",
+    params: {
+      framework: "svelte",
+      componentPath: "src/lib/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/lib/Button", ...componentAnswers },
+  },
+  {
+    name: "component/lit",
+    kind: "component",
+    framework: "lit",
+    params: {
+      framework: "lit",
+      componentPath: "src/lib/Button",
+      ...componentAnswers,
+    },
+    answers: { componentPath: "src/lib/Button", ...componentAnswers },
+  },
+  {
+    name: "package",
+    kind: "package",
+    framework: "",
+    params: {
+      name: "@canonical/my-lib",
+      type: "library",
+      description: "A library.",
+      withReact: false,
+      withStorybook: false,
+      withCli: false,
+      withPrTemplate: false,
+      runInstall: false,
+    },
+    answers: {
+      name: "@canonical/my-lib",
+      type: "library",
+      description: "A library.",
+      withReact: false,
+      withStorybook: false,
+      withCli: false,
+      withPrTemplate: false,
+      runInstall: false,
+    },
+  },
+  {
+    name: "application",
+    kind: "application",
+    framework: "",
+    // The pragma path receives the CLI `--with-X` params (AV-228 B8); the summon
+    // path receives the generator's bare prompt names. runCreate's boundary remap
+    // (`withSsr` -> `ssr`, ...) makes both produce the byte-identical tree.
+    params: {
+      appPath: "my-app",
+      withSsr: true,
+      withRouter: true,
+      withForms: true,
+      withRelay: false,
+      runInstall: false,
+    },
+    answers: {
+      appPath: "my-app",
+      ssr: true,
+      router: true,
+      forms: true,
+      relay: false,
+      runInstall: false,
+    },
+  },
+];
+
+describe("byte-equality goldens — pragma create ≡ summon execute (PROTECTED)", () => {
+  for (const testCase of cases) {
+    it(`${testCase.name}: both producers write byte-identical trees`, async () => {
+      const pragma = await producePragma(testCase.kind, testCase.params);
+      const summon = await produceSummon(
+        testCase.kind,
+        testCase.framework,
+        testCase.answers,
+      );
+      expect(pragma.size).toBeGreaterThan(0);
+      expect([...pragma.keys()].sort()).toEqual([...summon.keys()].sort());
+      for (const [path, content] of pragma) {
+        expect(summon.get(path), `content of ${path}`).toBe(content);
+      }
+    });
+  }
+});

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

@@ -0,0 +1,152 @@
+/**
+ * PROTECTED — the compiled-binary `create` guard.
+ *
+ * Builds the real standalone `dist/pragma` (`bun build --compile`) and spawns
+ * `pragma create component … --yes` for react, svelte AND lit, asserting each
+ * tree is BYTE-IDENTICAL to a source run of the same generator (`bun src/bin.ts
+ * …`, which reads the `.ejs` templates from disk).
+ *
+ * This is what proves PR7's two compiled-`create` fixes end-to-end:
+ *   1. Summon is bundled — a computed-specifier import used to keep summon-core +
+ *      the generators OUT of the binary; static dynamic imports now include them.
+ *   2. The templates are embedded AND resolved by DIRECTORY-QUALIFIED path. The
+ *      svelte + lit cases are load-bearing: `types.ts.ejs` / `index.ts.ejs` /
+ *      `styles.css.ejs` / `stories.ts.ejs` exist in react/, svelte/ AND lit/, so
+ *      the old basename-matching fallback could emit the WRONG framework's file
+ *      in the binary. A wrong file would differ from the source run → red here.
+ *
+ * On base (summon not bundled, templates not embedded) the binary's `create`
+ * writes nothing (it errors), so `compiled.size > 0` already fails.
+ */
+
+import { execFileSync, spawnSync } from "node:child_process";
+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";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(here, "../../../../../..");
+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);
+
+/** Read a directory tree into a sorted map of relative path → contents. */
+function snapshot(dir: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const walk = (d: string, base: string): void => {
+    for (const entry of readdirSync(d, { withFileTypes: true }).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    )) {
+      const rel = base ? `${base}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) walk(join(d, entry.name), rel);
+      else out.set(rel, readFileSync(join(d, entry.name), "utf-8"));
+    }
+  };
+  walk(dir, "");
+  return out;
+}
+
+/** Run a `create component` in its own cwd and snapshot what it wrote. */
+function createComponent(
+  bin: string,
+  args: readonly string[],
+  framework: string,
+): Map<string, string> {
+  const dir = freshCwd();
+  execFileSync(
+    bin,
+    [
+      ...args,
+      "create",
+      "component",
+      "src/components/Widget",
+      "--framework",
+      framework,
+      "--yes",
+    ],
+    { cwd: dir, stdio: "pipe" },
+  );
+  return snapshot(dir);
+}
+
+describe("compiled pragma create component (PROTECTED)", () => {
+  for (const framework of ["react", "svelte", "lit"] as const) {
+    it(`${framework}: compiled binary ≡ source run, byte-for-byte`, () => {
+      // (1) The real standalone binary — templates come from the embedded manifest.
+      const compiled = createComponent(compiledBin, [], framework);
+      // (2) A source run — templates come from disk. The reference output.
+      const source = createComponent("bun", [pragmaBin], framework);
+
+      // Wrote something (fails on base, where the binary's create errors out).
+      expect(compiled.size).toBeGreaterThan(0);
+      // Same file set …
+      expect([...compiled.keys()].sort()).toEqual([...source.keys()].sort());
+      // … and byte-identical contents (the collision fix: svelte/lit must NOT
+      // carry react's template text).
+      for (const [path, content] of compiled) {
+        expect(source.get(path), `content of ${path}`).toBe(content);
+      }
+    }, 120_000);
+  }
+});
+
+/**
+ * PROTECTED — the compiled-binary READ guard (U1-orig).
+ *
+ * A READ command (`block list`, `--help`) never calls a generator's
+ * `generate()`, so — with the generators loading their templates LAZILY on first
+ * `generate()` rather than at module-eval — it must never touch a `.ejs`
+ * template that the standalone binary lacks. This is the exact gap the
+ * create-only smoke above missed: the component generators used to load
+ * templates via a top-level `await`, so a READ crashed with `Template not found`
+ * on any bun version whose `--compile` code-splitting did not keep the generator
+ * modules lazy. The lazy load makes a READ template-free regardless of bun.
+ */
+describe("compiled pragma READ smoke (PROTECTED)", () => {
+  // A cold store cleanly reports STORE_UNAVAILABLE (exit 3); `--help` never needs
+  // a store (exit 0). Both fully exercise startup + dispatch — the phase where an
+  // eager generator template load would have crashed — without a store or writes.
+  const READS: ReadonlyArray<{
+    args: readonly string[];
+    okExit: readonly number[];
+  }> = [
+    { args: ["block", "list"], okExit: [0, 3] },
+    { args: ["--help"], okExit: [0] },
+  ];
+
+  for (const { args, okExit } of READS) {
+    it(`\`${args.join(" ")}\` runs without a Template-not-found crash`, () => {
+      const result = spawnSync(compiledBin, [...args], {
+        cwd: freshCwd(),
+        stdio: "pipe",
+        encoding: "utf-8",
+      });
+      const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+      // The exact crash the lazy-template fix closes: a READ never loads a
+      // generator, so it never touches a `.ejs` the standalone binary lacks.
+      expect(output).not.toMatch(/Template not found/);
+      // Nor does it collapse to the internal-bug path (the crash's other tell).
+      expect(output).not.toMatch(/Internal error/);
+      // It reaches a clean dispatch outcome, not an uncaught startup crash.
+      expect(okExit).toContain(result.status);
+    }, 30_000);
+  }
+});

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

@@ -0,0 +1,139 @@
+/**
+ * PROTECTED — MCP plan-first + confirm parity for `create`:
+ * a tool call WITHOUT `confirm` returns a plan (`planOnly`/`confirmRequired`)
+ * and writes nothing; WITH `confirm: true` it runs for real. The plan mirrors
+ * the CLI `--dry-run` preview (both filter out Prompt effects).
+ */
+
+import { existsSync, mkdtempSync, readdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { executeVerb } from "../../kernel/project/cli/dispatch.js";
+import { bootRuntime } from "../../kernel/runtime/boot.js";
+import type { GlobalFlags } from "../../kernel/runtime/types.js";
+import type { VerbSpec } from "../../kernel/spec/types.js";
+import { projectMcp } from "../../testing/helpers/projectMcp.js";
+import { createComponentVerb } from "./create.verb.js";
+import { createModule } from "./index.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const freshCwd = (): string =>
+  mkdtempSync(join(tmpdir(), "pragma-create-mcp-"));
+
+let cleanup: (() => Promise<void>) | undefined;
+afterEach(async () => {
+  await cleanup?.();
+  cleanup = undefined;
+});
+
+describe("create over MCP (PROTECTED)", () => {
+  it("exposes create_component as mutating but NON-destructive", 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");
+    expect(component).toBeDefined();
+    expect(component?.annotations).toMatchObject({
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: false,
+    });
+    // Explicit: create only writes NEW files. An unset destructiveHint on a
+    // non-read-only tool defaults to `true`, so it must be emitted as false —
+    // agents otherwise treat scaffolding as a destructive operation (D4).
+    expect(component?.annotations?.destructiveHint).toBe(false);
+  });
+
+  it("plan-first: no confirm → a plan, no files written", async () => {
+    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: "src/components/Button",
+      });
+      expect(result.ok).toBe(true);
+      expect(result.meta).toMatchObject({
+        planOnly: true,
+        confirmRequired: true,
+      });
+      const plan = (result.data as { plan: string[] }).plan;
+      expect(plan.some((line) => line.includes("Button.tsx"))).toBe(true);
+      expect(plan.some((line) => line.includes("Prompt"))).toBe(false);
+      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();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const result = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "src/components/Button",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+        confirm: true,
+      });
+      expect(result.ok).toBe(true);
+      expect(existsSync(join(dir, "src/components/Button/Button.tsx"))).toBe(
+        true,
+      );
+    } finally {
+      process.chdir(prev);
+    }
+  });
+
+  it("the MCP plan matches the CLI --dry-run preview", async () => {
+    const dir = freshCwd();
+    const prev = process.cwd();
+    process.chdir(dir);
+    try {
+      const mcp = await projectMcp([createModule], dir);
+      cleanup = mcp.cleanup;
+      const mcpResult = await mcp.callTool("create_component", {
+        framework: "react",
+        componentPath: "src/components/Button",
+        withStyles: false,
+        withStories: false,
+        withSsrTests: false,
+      });
+      const mcpPlan = (mcpResult.data as { plan: string[] }).plan;
+
+      const cliOutcome = await executeVerb(
+        createComponentVerb as VerbSpec,
+        {
+          framework: "react",
+          componentPath: "src/components/Button",
+          withStyles: false,
+          withStories: false,
+          withSsrTests: false,
+        },
+        { dryRun: true, undo: false, yes: false },
+        bootRuntime(FLAGS, dir),
+      );
+      // Every planned effect line appears in the CLI dry-run preview too.
+      for (const line of mcpPlan) {
+        expect(cliOutcome.stdout ?? "").toContain(line);
+      }
+    } finally {
+      process.chdir(prev);
+    }
+  });
+});

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

@@ -0,0 +1,50 @@
+/**
+ * Formatters for `create` — plain / llm / json over a {@link GeneratorResult}.
+ *
+ * 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.
+ */
+
+import type { GeneratorResult } from "@canonical/summon-core";
+import { type Effect, getAffectedFiles } from "@canonical/task";
+import type { Formatters } from "../../kernel/spec/types.js";
+
+/** The user-visible mutating effects, de-duplicated by path for MakeDir. */
+function created(effects: readonly Effect[]): string[] {
+  return getAffectedFiles([...effects]);
+}
+
+/** The generation's outcome formatters. */
+export const createFormatters: Formatters<GeneratorResult> = {
+  plain(result) {
+    const files = created(result.effects);
+    const header = `Created with ${result.generator.meta.name} v${result.generator.meta.version}.`;
+    if (files.length === 0) return header;
+    return [header, ...files.map((file) => `  + ${file}`)].join("\n");
+  },
+
+  llm(result) {
+    const files = created(result.effects);
+    const lines = [
+      `# create — ${result.generator.meta.name}`,
+      "",
+      `Generated ${files.length} path${files.length === 1 ? "" : "s"}:`,
+      ...files.map((file) => `- \`${file}\``),
+    ];
+    return lines.join("\n");
+  },
+
+  json(result) {
+    return JSON.stringify({
+      generator: {
+        name: result.generator.meta.name,
+        version: result.generator.meta.version,
+      },
+      answers: result.answers,
+      created: created(result.effects),
+    });
+  },
+};