@canonical/pragma-cli 0.29.0 → 0.31.0

package/src/domains/config/tasks/setTier.ts

@@ -1,39 +1,20 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import { readConfig } from "../../../config/index.js";
-import resolveConfigPath from "../../../config/resolveConfigPath.js";
+import type { Task } from "@canonical/task";
+import type { ConfigScope } from "../../../config/index.js";
+import writeConfigField from "./writeConfigField.js";
 
 /**
  * Build a config-write task for setting or resetting the active tier.
  *
- * @param cwd - Working directory containing pragma.config.json.
+ * @param cwd - Working directory the target config layer is resolved from.
  * @param tier - Tier path to persist, or `undefined` to reset.
- * @returns Task yielding the persisted field/value payload.
- * @note - Impure — reads config and writes to the file system.
+ * @param scope - Optional explicit target layer (`"global"` | `"local"`).
+ * @returns Task yielding the persisted field/value payload and target path.
+ * @note - Impure — reads and writes the target config file.
  */
 export default function setTier(
   cwd: string,
   tier: string | undefined,
-): Task<{
-  field: "tier";
-  value: string | undefined;
-}> {
-  return gen(function* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`,
-    // `trace`) survive. `readConfig` normalises defaults (tier: undefined,
-    // channel: "normal"); strip those to keep the file minimal, then apply
-    // the tier change (`undefined` resets it).
-    const current = readConfig(cwd);
-    const { tier: _current, channel, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { tier } : {}),
-      ...(channel !== "normal" ? { channel } : {}),
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "tier", value: tier };
-  });
+  scope?: ConfigScope,
+): Task<{ field: "tier"; value: string | undefined; path: string }> {
+  return writeConfigField(cwd, "tier", tier, scope);
 }

package/src/domains/config/tasks/setTrace.ts

@@ -1,38 +1,20 @@
-import { $, gen, type Task, writeFile } from "@canonical/task";
-import { readConfig } from "../../../config/index.js";
-import resolveConfigPath from "../../../config/resolveConfigPath.js";
+import type { Task } from "@canonical/task";
+import type { ConfigScope } from "../../../config/index.js";
+import writeConfigField from "./writeConfigField.js";
 
 /**
  * Build a config-write task for enabling or disabling query tracing.
  *
- * @param cwd - Working directory containing pragma.config.json.
+ * @param cwd - Working directory the target config layer is resolved from.
  * @param trace - `true` to enable, `false` to disable.
- * @returns Task yielding the persisted field/value payload.
+ * @param scope - Optional explicit target layer (`"global"` | `"local"`).
+ * @returns Task yielding the persisted field/value payload and target path.
+ * @note - Impure — reads and writes the target config file.
  */
 export default function setTrace(
   cwd: string,
   trace: boolean,
-): Task<{ field: "trace"; value: boolean }> {
-  return gen(function* () {
-    // Merge onto the full existing config so other fields (e.g. `packages`)
-    // survive — rebuilding from a fixed field list silently drops everything
-    // not listed, and `packages` is runtime-consumed, so dropping it is data
-    // loss. `readConfig` normalises defaults (tier: undefined, channel:
-    // "normal"); strip those so we keep the file minimal, matching the
-    // existing convention of not persisting unset defaults.
-    const current = readConfig(cwd);
-    const { tier, channel, ...rest } = current;
-    const next = {
-      ...rest,
-      ...(tier !== undefined ? { tier } : {}),
-      ...(channel !== "normal" ? { channel } : {}),
-      trace,
-    };
-
-    yield* $(
-      writeFile(resolveConfigPath(cwd), `${JSON.stringify(next, null, 2)}\n`),
-    );
-
-    return { field: "trace", value: trace };
-  });
+  scope?: ConfigScope,
+): Task<{ field: "trace"; value: boolean | undefined; path: string }> {
+  return writeConfigField(cwd, "trace", trace, scope);
 }

package/src/domains/config/tasks/writeConfigField.ts

@@ -0,0 +1,41 @@
+import { $, gen, type Task, writeFile } from "@canonical/task";
+import {
+  type ConfigScope,
+  type ConfigUpdate,
+  mergeConfigFileUpdate,
+  resolveWriteConfigPath,
+} from "../../../config/index.js";
+
+/**
+ * Build a config-write task for one field.
+ *
+ * Resolves the target layer with the global-first write rule (explicit
+ * scope wins, else the nearest existing project file, else the global XDG
+ * file), merges the update into that file's own contents — never copying
+ * values from another layer — and writes through the tracked `writeFile`
+ * effect so the change participates in dry-run and undo. `undefined`
+ * removes the field from the target file.
+ *
+ * @param cwd - Working directory the project layer is resolved from.
+ * @param field - Config field to set or remove.
+ * @param value - New value, or `undefined` to remove the field.
+ * @param scope - Optional explicit target layer.
+ * @returns Task yielding the persisted field/value payload and the path written.
+ * @note Impure — resolves and reads the target file, writes via effect.
+ */
+export default function writeConfigField<F extends keyof ConfigUpdate>(
+  cwd: string,
+  field: F,
+  value: ConfigUpdate[F],
+  scope?: ConfigScope,
+): Task<{ field: F; value: ConfigUpdate[F]; path: string }> {
+  return gen(function* () {
+    const path = resolveWriteConfigPath(cwd, scope);
+    const update = { [field]: value } as ConfigUpdate;
+    const content = mergeConfigFileUpdate(path, update);
+
+    yield* $(writeFile(path, content));
+
+    return { field, value, path };
+  });
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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

@@ -0,0 +1,159 @@
+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

@@ -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"),
+  };
+}