@canonical/pragma-cli 0.30.0 → 0.31.0

package/src/domains/create/generatorPack/compileGeneratorPack.ts

@@ -0,0 +1,312 @@
+/**
+ * Generator packs — the write-side analog of story packs.
+ *
+ * A generator pack is a set of summon generators (a package's `generators`
+ * export). This compiler enumerates them, groups by noun, and emits `create
+ * <noun>` CLI commands and `create_<noun>` MCP tools — the same data-driven
+ * surface story packs give read commands. The core stops hardcoding which
+ * generators exist; a package's full set is exposed automatically.
+ *
+ * Key convention (summon's own): `"<noun>/<variant>"` (e.g. `component/react`)
+ * groups under `<noun>` with a `<variant>` discriminator; a bare `"<noun>"`
+ * (e.g. `package`) is a single generator. A noun with one variant collapses to
+ * `create <noun>`; a noun with several becomes `create <noun> <variant>`.
+ */
+
+import {
+  type CommandDefinition,
+  executeGenerator,
+  generatorToCommand,
+  type ParameterDefinition,
+} from "@canonical/cli-core";
+import type { AnyGenerator, PromptDefinition } from "@canonical/summon-core";
+import { PragmaError } from "#error";
+import type { ToolParamDef, ToolSpec } from "../../shared/ToolSpec.js";
+import renderGeneratorUi from "../renderGeneratorUi.js";
+
+/** A package's generator set: generator key → generator. */
+export type GeneratorSet = Readonly<Record<string, AnyGenerator>>;
+
+/** Compiled surfaces for one generator pack. */
+export interface CompiledGeneratorPack {
+  readonly commands: readonly CommandDefinition[];
+  readonly specs: readonly ToolSpec[];
+}
+
+/** A generator grouped under a noun, with its optional variant. */
+interface GroupedGenerator {
+  readonly variant?: string;
+  readonly gen: AnyGenerator;
+}
+
+/** Split a generator key into `{ noun, variant? }` on the first slash. */
+function parseGeneratorKey(key: string): { noun: string; variant?: string } {
+  const slash = key.indexOf("/");
+  if (slash === -1) return { noun: key };
+  return { noun: key.slice(0, slash), variant: key.slice(slash + 1) };
+}
+
+/** Group a generator set by noun, preserving declaration order. */
+function groupByNoun(
+  generators: GeneratorSet,
+): Map<string, GroupedGenerator[]> {
+  const groups = new Map<string, GroupedGenerator[]>();
+  for (const [key, gen] of Object.entries(generators)) {
+    const { noun, variant } = parseGeneratorKey(key);
+    const group = groups.get(noun) ?? [];
+    group.push(variant !== undefined ? { variant, gen } : { gen });
+    groups.set(noun, group);
+  }
+  return groups;
+}
+
+/** Prompt type → tool param type, mirroring cli-core's `promptToParameter`. */
+const PROMPT_TYPE_MAP: Record<PromptDefinition["type"], ToolParamDef["type"]> =
+  {
+    text: "string",
+    confirm: "boolean",
+    select: "string",
+    multiselect: "string[]",
+  };
+
+/** Map a summon prompt to a neutral MCP tool parameter. */
+function promptToToolParam(prompt: PromptDefinition): ToolParamDef {
+  const enumValues =
+    prompt.type === "confirm"
+      ? undefined
+      : prompt.choices?.map((choice) => choice.value);
+  return {
+    type: PROMPT_TYPE_MAP[prompt.type],
+    description: prompt.message,
+    // A prompt with a default or a `when` condition is answerable without
+    // input; only an unconditional, defaultless prompt is required.
+    optional: prompt.default !== undefined || prompt.when !== undefined,
+    ...(enumValues ? { enum: enumValues } : {}),
+  };
+}
+
+/**
+ * Generator answers the MCP tool runner pins to fixed values.
+ *
+ * MCP create tools always produce a dry-run plan, so `runInstall` is forced
+ * off regardless of input. This one map drives BOTH the schema (pinned
+ * answers are excluded from the advertised params — a tool must not
+ * advertise a parameter it ignores) and the runtime override in
+ * {@link runGeneratorTool}, so the two can never drift.
+ */
+const PINNED_TOOL_ANSWERS: Readonly<Record<string, unknown>> = {
+  runInstall: false,
+};
+
+/**
+ * Build the MCP param map for a generator from its prompts, omitting
+ * prompts whose answers are pinned by {@link PINNED_TOOL_ANSWERS}.
+ */
+function toolParamsFor(gen: AnyGenerator): Record<string, ToolParamDef> {
+  return Object.fromEntries(
+    gen.prompts
+      .filter((prompt) => !(prompt.name in PINNED_TOOL_ANSWERS))
+      .map((prompt) => [prompt.name, promptToToolParam(prompt)]),
+  );
+}
+
+/**
+ * Run one generator as an MCP tool call: json-mode dry-run plan.
+ *
+ * A generator that throws (e.g. an unmet hard requirement such as
+ * application's ssr/router pairing) is mapped to a typed INVALID_INPUT
+ * carrying the generator's own message as the recovery hint — the generic
+ * replacement for the per-generator validation the hand-written specs did.
+ */
+async function runGeneratorTool(
+  gen: AnyGenerator,
+  rt: { cwd: string },
+  params: Record<string, unknown>,
+  discriminator?: string,
+): Promise<{ data: unknown }> {
+  const batchCtx = {
+    cwd: rt.cwd,
+    globalFlags: { llm: false, format: "json" as const, verbose: false },
+  };
+  // Apply the pinned answers (never install during a dry-run plan); the
+  // discriminator is dispatch metadata, not a generator answer.
+  const genParams: Record<string, unknown> = {
+    ...params,
+    ...PINNED_TOOL_ANSWERS,
+  };
+  if (discriminator) delete genParams[discriminator];
+  try {
+    const result = await executeGenerator(gen, genParams, batchCtx);
+    if (result.tag === "output") {
+      // json mode: result.value is already the structured plan.
+      return { data: result.value };
+    }
+    throw PragmaError.invalidInput("parameters", "(no plan produced)", {
+      recovery: { message: `The ${gen.meta.name} generator rejected them.` },
+    });
+  } catch (error) {
+    if (error instanceof PragmaError) throw error;
+    throw PragmaError.invalidInput("parameters", "(rejected)", {
+      recovery: {
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+/**
+ * Build the variant → generator resolver shared by the CLI and MCP dispatch.
+ *
+ * @returns A function resolving a raw `variant` param to its generator.
+ * @throws PragmaError with code INVALID_INPUT for a missing/unknown variant.
+ */
+function buildVariantResolver(
+  group: readonly GroupedGenerator[],
+  variants: readonly string[],
+): (variant: unknown) => AnyGenerator {
+  const byVariant = new Map(group.map((g) => [g.variant, g.gen]));
+  return (variant) => {
+    const gen =
+      typeof variant === "string" ? byVariant.get(variant) : undefined;
+    if (!gen) {
+      throw PragmaError.invalidInput(
+        "variant",
+        typeof variant === "string" ? variant : "(missing)",
+        { validOptions: [...variants] },
+      );
+    }
+    return gen;
+  };
+}
+
+/**
+ * Compile a package's generator set into `create <noun>` commands and
+ * `create_<noun>` MCP tools.
+ *
+ * @note Impure — warns on stderr when a degenerate group (duplicate noun
+ *   with mixed bare/variant keys) forces generators to be skipped.
+ */
+export default function compileGeneratorPack(
+  generators: GeneratorSet,
+): CompiledGeneratorPack {
+  const commands: CommandDefinition[] = [];
+  const specs: ToolSpec[] = [];
+
+  for (const [noun, group] of groupByNoun(generators)) {
+    const [first, ...rest] = group;
+    if (!first) continue; // groupByNoun never emits empty groups
+
+    const variants = group
+      .map((g) => g.variant)
+      .filter((v): v is string => v !== undefined);
+
+    if (rest.length > 0 && variants.length === group.length) {
+      commands.push(buildVariantCommand(noun, first.gen, group, variants));
+      specs.push(buildVariantSpec(noun, first.gen, group, variants));
+      continue;
+    }
+
+    if (rest.length > 0) {
+      // Mixed bare/variant keys under one noun is a malformed set — expose
+      // the first generator rather than none, but never drop the rest
+      // silently.
+      process.stderr.write(
+        `Warning: generator noun "${noun}" mixes bare and variant keys; ` +
+          `only "${first.gen.meta.name}" is exposed.\n`,
+      );
+    }
+    commands.push(buildSingleCommand(noun, first.gen));
+    specs.push(buildSingleSpec(noun, first.gen));
+  }
+
+  return { commands, specs };
+}
+
+/** `create <noun>` for a single generator, with summon's rich Ink UI. */
+function buildSingleCommand(
+  noun: string,
+  gen: AnyGenerator,
+): CommandDefinition {
+  const base = generatorToCommand(["create", noun], gen);
+  return {
+    ...base,
+    execute: (params, ctx) => renderGeneratorUi(gen, params, ctx),
+  };
+}
+
+/**
+ * `create <noun> <variant>` dispatch over several generators.
+ *
+ * Help and parameters project from the reference (first-declared) generator —
+ * variants of one noun are assumed prompt-compatible, the same assumption the
+ * hand-written component command made.
+ */
+function buildVariantCommand(
+  noun: string,
+  reference: AnyGenerator,
+  group: readonly GroupedGenerator[],
+  variants: readonly string[],
+): CommandDefinition {
+  const resolve = buildVariantResolver(group, variants);
+  const base = generatorToCommand(["create", noun], reference);
+  const variantParam: ParameterDefinition = {
+    name: "variant",
+    description: `Which ${noun} to scaffold (${variants.join(", ")})`,
+    type: "select",
+    choices: variants.map((v) => ({ label: v, value: v })),
+    positional: true,
+    required: true,
+  };
+  return {
+    ...base,
+    parameters: [variantParam, ...base.parameters],
+    // async so an unknown variant rejects instead of throwing synchronously.
+    execute: async (params, ctx) =>
+      renderGeneratorUi(resolve(params.variant), params, ctx),
+  };
+}
+
+/** `create_<noun>` MCP tool for a single generator. */
+function buildSingleSpec(noun: string, gen: AnyGenerator): ToolSpec {
+  return {
+    name: `create_${noun}`,
+    description: `${gen.meta.description} Returns a JSON generation plan (dry-run).`,
+    params: toolParamsFor(gen),
+    readOnly: false,
+    destructive: false,
+    execute: (rt, params) => runGeneratorTool(gen, rt, params),
+  };
+}
+
+/**
+ * `create_<noun>` MCP tool with a `variant` discriminator.
+ *
+ * The param schema projects from the reference generator's prompts (see
+ * {@link buildVariantCommand} for the compatibility assumption).
+ */
+function buildVariantSpec(
+  noun: string,
+  reference: AnyGenerator,
+  group: readonly GroupedGenerator[],
+  variants: readonly string[],
+): ToolSpec {
+  const resolve = buildVariantResolver(group, variants);
+  return {
+    name: `create_${noun}`,
+    description: `${reference.meta.description} Returns a JSON generation plan (dry-run).`,
+    params: {
+      variant: {
+        type: "string",
+        description: `Which ${noun} to scaffold`,
+        optional: false,
+        enum: [...variants],
+      },
+      ...toolParamsFor(reference),
+    },
+    readOnly: false,
+    destructive: false,
+    // async so an unknown variant rejects instead of throwing synchronously.
+    execute: async (rt, params) =>
+      runGeneratorTool(resolve(params.variant), rt, params, "variant"),
+  };
+}

package/src/domains/create/index.ts

@@ -1,15 +1,21 @@
-/** @module Create domain -- generator commands for `pragma create` (component and package). */
+/**
+ * Create domain — generator-pack-driven `create <noun>` commands.
+ *
+ * The create surface is compiled from bundled generator packs (a package's
+ * `generators` export), not hardcoded per generator. Every generator each
+ * bundled package ships is exposed as a `create <noun>` command and a
+ * `create_<noun>` MCP tool. See {@link ./generatorPack/compileGeneratorPack}.
+ */
 
 import type { CommandDefinition } from "@canonical/cli-core";
-import { componentCommand, packageCommand } from "./commands/index.js";
+import bundledGeneratorPacks from "./generatorPack/bundled.js";
 
 /**
- * Return all create command definitions.
- *
- * @returns An array of CommandDefinitions for component and package generators.
+ * Return all create command definitions, compiled from the bundled
+ * generator packs.
  */
-export function commands(): CommandDefinition[] {
-  return [componentCommand(), packageCommand()];
+export function commands(): readonly CommandDefinition[] {
+  return bundledGeneratorPacks().commands;
 }
 
 export { specs as mcpSpecs } from "./mcp/index.js";

package/src/domains/create/mcp/specs.ts

@@ -1,168 +1,13 @@
 /**
- * MCP tool specs for create domain — create_component, create_package.
+ * MCP tool specs for the create domain.
+ *
+ * Compiled from the bundled generator packs — one `create_<noun>` tool per
+ * generator noun — rather than hand-written per generator.
  */
 
-import { executeGenerator } from "@canonical/cli-core";
-import type { AnyGenerator } from "@canonical/summon-core";
-import { generators as packageGenerators } from "@canonical/summon-package";
-import { PragmaError } from "#error";
 import type { ToolSpec } from "../../shared/ToolSpec.js";
-import { COMPONENT_GENERATORS } from "../generators.js";
+import bundledGeneratorPacks from "../generatorPack/bundled.js";
 
-const specs: readonly ToolSpec[] = [
-  {
-    name: "create_component",
-    description:
-      "Generate a design system component with TypeScript, tests, stories, and styles. Returns a JSON generation plan (dry-run).",
-    params: {
-      framework: {
-        type: "string",
-        description: "Component framework",
-        optional: false,
-        enum: ["react", "svelte", "lit"],
-      },
-      componentPath: {
-        type: "string",
-        description:
-          "Path for the component directory (e.g. 'src/components/Button')",
-        optional: false,
-      },
-      withStyles: {
-        type: "boolean",
-        description: "Include CSS styles (default: true)",
-        optional: true,
-      },
-      withStories: {
-        type: "boolean",
-        description: "Include Storybook stories (default: true)",
-        optional: true,
-      },
-      withSsrTests: {
-        type: "boolean",
-        description: "Include SSR tests (default: true)",
-        optional: true,
-      },
-    },
-    readOnly: false,
-    destructive: false,
-    async execute(rt, params) {
-      const batchCtx = {
-        cwd: rt.cwd,
-        globalFlags: {
-          llm: false,
-          format: "json" as const,
-          verbose: false,
-        },
-      };
-
-      const framework = params.framework as string;
-      const gen = COMPONENT_GENERATORS[framework];
-      if (!gen) {
-        throw PragmaError.invalidInput("framework", framework, {
-          validOptions: Object.keys(COMPONENT_GENERATORS),
-        });
-      }
-
-      const genParams: Record<string, unknown> = {
-        componentPath: params.componentPath,
-        ...(params.withStyles !== undefined && {
-          withStyles: params.withStyles,
-        }),
-        ...(params.withStories !== undefined && {
-          withStories: params.withStories,
-        }),
-        ...(params.withSsrTests !== undefined && {
-          withSsrTests: params.withSsrTests,
-        }),
-      };
-
-      const result = await executeGenerator(gen, genParams, batchCtx);
-      if (result.tag === "output") {
-        const text = result.render.plain(result.value);
-        return { data: JSON.parse(text) };
-      }
-
-      throw PragmaError.invalidInput(
-        "componentPath",
-        String(params.componentPath),
-      );
-    },
-  },
-  {
-    name: "create_package",
-    description:
-      "Generate a new npm package with proper configuration. Returns a JSON generation plan (dry-run).",
-    params: {
-      name: {
-        type: "string",
-        description: "Full package name (e.g. '@canonical/my-package')",
-        optional: false,
-      },
-      type: {
-        type: "string",
-        description: "Package type",
-        optional: false,
-        enum: ["tool-ts", "library", "css"],
-      },
-      description: {
-        type: "string",
-        description: "Package description",
-        optional: true,
-      },
-      withReact: {
-        type: "boolean",
-        description: "Add React dependencies (default: false)",
-        optional: true,
-      },
-      withStorybook: {
-        type: "boolean",
-        description: "Add Storybook config (default: false)",
-        optional: true,
-      },
-      withCli: {
-        type: "boolean",
-        description: "Add CLI entry point (default: false)",
-        optional: true,
-      },
-    },
-    readOnly: false,
-    destructive: false,
-    async execute(rt, params) {
-      const batchCtx = {
-        cwd: rt.cwd,
-        globalFlags: {
-          llm: false,
-          format: "json" as const,
-          verbose: false,
-        },
-      };
-
-      const gen = packageGenerators.package as AnyGenerator | undefined;
-      if (!gen) throw PragmaError.internalError("Package generator not found");
-
-      const genParams: Record<string, unknown> = {
-        name: params.name,
-        type: params.type,
-        ...(params.description !== undefined && {
-          description: params.description,
-        }),
-        ...(params.withReact !== undefined && { withReact: params.withReact }),
-        ...(params.withStorybook !== undefined && {
-          withStorybook: params.withStorybook,
-        }),
-        ...(params.withCli !== undefined && { withCli: params.withCli }),
-        runInstall: false,
-      };
-
-      const result = await executeGenerator(gen, genParams, batchCtx);
-      if (result.tag === "output") {
-        const text = result.render.plain(result.value);
-        return { data: JSON.parse(text) };
-      }
-
-      throw PragmaError.invalidInput("name", String(params.name));
-    },
-  },
-];
+const specs: readonly ToolSpec[] = bundledGeneratorPacks().specs;
 
 export default specs;

package/src/domains/create/renderGeneratorUi.test.ts

@@ -0,0 +1,103 @@
+import type { CommandContext } from "@canonical/cli-core";
+import type { GeneratorDefinition } from "@canonical/summon-core";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const executeGeneratorMock = vi.fn(async () => ({
+  tag: "output" as const,
+  value: "",
+  render: { plain: () => "" },
+}));
+const renderAppMock = vi.fn(async () => {});
+
+vi.mock("@canonical/cli-core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@canonical/cli-core")>();
+  return {
+    ...actual,
+    executeGenerator: executeGeneratorMock,
+    createGeneratorStamp: () => ({ generatorName: "g", version: "1" }),
+  };
+});
+
+vi.mock("@canonical/summon/ui", () => ({ renderApp: renderAppMock }));
+
+const gen = {
+  meta: {},
+  prompts: [],
+  generate: () => ({}),
+} as unknown as GeneratorDefinition;
+
+function makeCtx(overrides: Partial<CommandContext["globalFlags"]> = {}) {
+  return {
+    cwd: "/tmp",
+    globalFlags: { llm: false, format: "text", verbose: false, ...overrides },
+  } as CommandContext;
+}
+
+async function withTty<T>(
+  stdin: boolean,
+  stdout: boolean,
+  run: () => Promise<T>,
+): Promise<T> {
+  const inPrev = process.stdin.isTTY;
+  const outPrev = process.stdout.isTTY;
+  Object.defineProperty(process.stdin, "isTTY", {
+    value: stdin,
+    configurable: true,
+  });
+  Object.defineProperty(process.stdout, "isTTY", {
+    value: stdout,
+    configurable: true,
+  });
+  try {
+    return await run();
+  } finally {
+    Object.defineProperty(process.stdin, "isTTY", {
+      value: inPrev,
+      configurable: true,
+    });
+    Object.defineProperty(process.stdout, "isTTY", {
+      value: outPrev,
+      configurable: true,
+    });
+  }
+}
+
+describe("renderGeneratorUi", () => {
+  afterEach(() => vi.clearAllMocks());
+
+  it("renders summon's Ink UI on an interactive terminal", async () => {
+    const { default: renderGeneratorUi } = await import(
+      "./renderGeneratorUi.js"
+    );
+    const result = await withTty(true, true, () =>
+      renderGeneratorUi(gen, {}, makeCtx()),
+    );
+    expect(renderAppMock).toHaveBeenCalledTimes(1);
+    expect(executeGeneratorMock).not.toHaveBeenCalled();
+    expect(result).toEqual({ tag: "exit", code: 0 });
+  });
+
+  it("falls back to executeGenerator on a non-interactive terminal", async () => {
+    const { default: renderGeneratorUi } = await import(
+      "./renderGeneratorUi.js"
+    );
+    await withTty(false, false, () => renderGeneratorUi(gen, {}, makeCtx()));
+    expect(executeGeneratorMock).toHaveBeenCalledTimes(1);
+    expect(renderAppMock).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["--yes", { yes: true }],
+    ["--dry-run", { dryRun: true }],
+    ["--undo", { undo: true }],
+    ["--llm", { llm: true }],
+    ["--format json", { format: "json" }],
+  ])("falls back to executeGenerator for %s even on a TTY", async (_label, params) => {
+    const { default: renderGeneratorUi } = await import(
+      "./renderGeneratorUi.js"
+    );
+    await withTty(true, true, () => renderGeneratorUi(gen, params, makeCtx()));
+    expect(executeGeneratorMock).toHaveBeenCalledTimes(1);
+    expect(renderAppMock).not.toHaveBeenCalled();
+  });
+});

package/src/domains/create/renderGeneratorUi.ts

@@ -0,0 +1,65 @@
+/**
+ * Route a generator run to the right front-end.
+ *
+ * On an interactive terminal (no `--yes`, not a machine-output or preview-only
+ * mode), render summon's Ink `App` — the same colored prompt sequence,
+ * operations recap, and "Proceed?" confirmation the `summon` binary shows — so
+ * `pragma create`/`setup` match summon exactly without duplicating the UI. In
+ * every other case (piped/CI, `--yes`, `--llm`/`--format json`, `--dry-run`,
+ * `--undo`) fall back to the shared UI-free {@link executeGenerator}, which owns
+ * the batch, preview, and machine-readable paths.
+ */
+
+import {
+  type CommandContext,
+  type CommandResult,
+  createExitResult,
+  createGeneratorStamp,
+  executeGenerator,
+} from "@canonical/cli-core";
+import type { GeneratorDefinition } from "@canonical/summon-core";
+
+/** Whether both stdin and stdout are attached to an interactive terminal. */
+function isInteractiveTerminal(): boolean {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
+/**
+ * Run a generator, preferring summon's rich Ink UI when interactive.
+ *
+ * @param gen - The generator to run.
+ * @param params - Parsed CLI params (flags + positional answers).
+ * @param ctx - The command context (global flags, cwd).
+ * @returns A CommandResult; the Ink path exits 0 after the UI closes.
+ * @note Impure — may take over the terminal via Ink and perform the run.
+ */
+export default async function renderGeneratorUi(
+  gen: GeneratorDefinition,
+  params: Record<string, unknown>,
+  ctx: CommandContext,
+): Promise<CommandResult> {
+  const isLlm = params.llm === true || ctx.globalFlags.llm;
+  const isJson = params.format === "json" || ctx.globalFlags.format === "json";
+  const wantsBatch =
+    params.yes === true ||
+    params.dryRun === true ||
+    params.undo === true ||
+    isLlm ||
+    isJson;
+
+  // Machine/preview/batch modes and non-interactive terminals stay on the
+  // UI-free executor.
+  if (wantsBatch || !isInteractiveTerminal()) {
+    return executeGenerator(gen, params, ctx);
+  }
+
+  const { renderApp } = await import("@canonical/summon/ui");
+  const stampEnabled = params.generatedStamp !== false;
+  await renderApp({
+    generator: gen,
+    preview: params.preview !== false,
+    verbose: ctx.globalFlags.verbose === true,
+    stamp: stampEnabled ? createGeneratorStamp(gen) : undefined,
+  });
+  return createExitResult(0);
+}