@canonical/pragma-cli 0.31.0 → 0.32.0

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

@@ -1,49 +0,0 @@
-/**
- * Bundled generator packs.
- *
- * The generator sets pragma ships by default, statically imported so the
- * single-file build embeds them. Each package's full generator set is exposed —
- * every generator, always — grouped into `create <noun>` commands and
- * `create_<noun>` MCP tools by {@link compileGeneratorPack}.
- *
- * This is the write-side counterpart of the bundled story packs. In a later
- * slice these move into the packages themselves (declared, dynamically
- * resolved) so the core ships no generator wiring at all; today they are
- * bundled transitional entries, like the story packs.
- */
-
-import { generators as applicationGenerators } from "@canonical/summon-application";
-import { generators as componentGenerators } from "@canonical/summon-component";
-import { generators as packageGenerators } from "@canonical/summon-package";
-import compileGeneratorPack, {
-  type CompiledGeneratorPack,
-  type GeneratorSet,
-} from "./compileGeneratorPack.js";
-
-/** Every generator set pragma bundles, in surface order. */
-const BUNDLED_GENERATOR_SETS: readonly GeneratorSet[] = [
-  componentGenerators,
-  packageGenerators,
-  applicationGenerators,
-];
-
-let cached: CompiledGeneratorPack | undefined;
-
-/**
- * Compile every bundled generator pack into its CLI commands and MCP specs.
- *
- * Memoized — the generator sets are static, and both the CLI and MCP
- * registration paths call this.
- *
- * @returns The merged commands and specs across all bundled packs.
- */
-export default function bundledGeneratorPacks(): CompiledGeneratorPack {
-  cached ??= BUNDLED_GENERATOR_SETS.map(compileGeneratorPack).reduce(
-    (merged, pack) => ({
-      commands: [...merged.commands, ...pack.commands],
-      specs: [...merged.specs, ...pack.specs],
-    }),
-    { commands: [], specs: [] },
-  );
-  return cached;
-}

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

@@ -1,159 +0,0 @@
-import type { AnyGenerator } from "@canonical/summon-core";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import type { PragmaRuntime } from "../../shared/types/index.js";
-import bundledGeneratorPacks from "./bundled.js";
-import compileGeneratorPack from "./compileGeneratorPack.js";
-
-describe("compileGeneratorPack (bundled)", () => {
-  const { commands, specs } = bundledGeneratorPacks();
-  const cliPaths = commands.map((c) => c.path.join(" "));
-  const toolNames = specs.map((s) => s.name);
-
-  it("exposes every generator from every bundled package as a create command", () => {
-    // component (react/svelte/lit → one noun), package, and the four
-    // application-package generators.
-    expect(cliPaths).toEqual([
-      "create component",
-      "create package",
-      "create application",
-      "create domain",
-      "create route",
-      "create wrapper",
-    ]);
-  });
-
-  it("emits a matching MCP tool per noun", () => {
-    expect(toolNames).toEqual([
-      "create_component",
-      "create_package",
-      "create_application",
-      "create_domain",
-      "create_route",
-      "create_wrapper",
-    ]);
-  });
-
-  it("dispatches a multi-variant noun via a `variant` positional select", () => {
-    const component = commands.find(
-      (c) => c.path.join(" ") === "create component",
-    );
-    const variant = component?.parameters.find((p) => p.name === "variant");
-    expect(variant?.type).toBe("select");
-    expect(variant?.positional).toBe(true);
-    expect(variant?.choices?.map((ch) => ch.value)).toEqual([
-      "react",
-      "svelte",
-      "lit",
-    ]);
-  });
-
-  it("gives the multi-variant MCP tool a `variant` enum parameter", () => {
-    const component = specs.find((s) => s.name === "create_component");
-    expect(component?.params?.variant?.enum).toEqual([
-      "react",
-      "svelte",
-      "lit",
-    ]);
-  });
-
-  it("collapses a single-variant noun to a plain `create <noun>` (no variant arg)", () => {
-    const application = commands.find(
-      (c) => c.path.join(" ") === "create application",
-    );
-    expect(application?.parameters.some((p) => p.name === "variant")).toBe(
-      false,
-    );
-    // Its prompts still project — appPath comes from the generator.
-    expect(application?.parameters.some((p) => p.name === "appPath")).toBe(
-      true,
-    );
-  });
-
-  it("derives single-generator MCP params from the generator's prompts", () => {
-    const pkg = specs.find((s) => s.name === "create_package");
-    expect(pkg?.params).toBeDefined();
-    // The package generator prompts for a package name.
-    expect(Object.keys(pkg?.params ?? {}).length).toBeGreaterThan(0);
-  });
-
-  it("never advertises params the runner pins (runInstall is forced off)", () => {
-    // The runner always executes a dry-run plan with runInstall: false, so
-    // no create tool may advertise the parameter it would ignore.
-    for (const spec of specs) {
-      expect(spec.params).not.toHaveProperty("runInstall");
-    }
-  });
-});
-
-/** Minimal synthetic generator for edge-case tests. */
-function makeGenerator(name: string, generate?: () => never): AnyGenerator {
-  return {
-    meta: {
-      name,
-      displayName: name,
-      description: `Test generator ${name}`,
-      version: "0.0.0",
-    },
-    prompts: [],
-    generate:
-      generate ??
-      (() => {
-        throw new Error("not exercised");
-      }),
-  } as unknown as AnyGenerator;
-}
-
-describe("compileGeneratorPack — edge cases", () => {
-  let warnings: string[];
-  let warn: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    warnings = [];
-    warn = vi
-      .spyOn(process.stderr, "write")
-      .mockImplementation((chunk: string | Uint8Array) => {
-        warnings.push(String(chunk));
-        return true;
-      });
-  });
-
-  afterEach(() => {
-    warn.mockRestore();
-  });
-
-  it("warns and exposes only the first generator of a mixed bare/variant noun", () => {
-    const { commands, specs } = compileGeneratorPack({
-      thing: makeGenerator("thing"),
-      "thing/extra": makeGenerator("thing/extra"),
-    });
-    expect(commands.map((c) => c.path.join(" "))).toEqual(["create thing"]);
-    expect(specs.map((s) => s.name)).toEqual(["create_thing"]);
-    expect(warnings.join("")).toContain("mixes bare and variant keys");
-  });
-
-  it("maps a generator that throws to INVALID_INPUT with its message as recovery", async () => {
-    const throwing = makeGenerator("boom", () => {
-      throw new Error("boom requires --both flags");
-    });
-    const { specs } = compileGeneratorPack({ boom: throwing });
-    const spec = specs.at(0);
-    const rt = { cwd: "/tmp" } as PragmaRuntime;
-    await expect(spec?.execute(rt, {})).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      recovery: { message: "boom requires --both flags" },
-    });
-  });
-
-  it("rejects an unknown variant with INVALID_INPUT and the valid options", async () => {
-    const { specs } = compileGeneratorPack({
-      "widget/a": makeGenerator("widget/a"),
-      "widget/b": makeGenerator("widget/b"),
-    });
-    const spec = specs.at(0);
-    const rt = { cwd: "/tmp" } as PragmaRuntime;
-    await expect(spec?.execute(rt, { variant: "c" })).rejects.toMatchObject({
-      code: "INVALID_INPUT",
-      validOptions: ["a", "b"],
-    });
-  });
-});

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

@@ -1,312 +0,0 @@
-/**
- * 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,21 +0,0 @@
-/**
- * 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 bundledGeneratorPacks from "./generatorPack/bundled.js";
-
-/**
- * Return all create command definitions, compiled from the bundled
- * generator packs.
- */
-export function commands(): readonly CommandDefinition[] {
-  return bundledGeneratorPacks().commands;
-}
-
-export { specs as mcpSpecs } from "./mcp/index.js";

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

@@ -1,2 +0,0 @@
-/** @module Create domain MCP barrel — create_component, create_package. */
-export { default as specs } from "./specs.js";

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

@@ -1,13 +0,0 @@
-/**
- * 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 type { ToolSpec } from "../../shared/ToolSpec.js";
-import bundledGeneratorPacks from "../generatorPack/bundled.js";
-
-const specs: readonly ToolSpec[] = bundledGeneratorPacks().specs;
-
-export default specs;

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

@@ -1,103 +0,0 @@
-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();
-  });
-});