@canonical/pragma-cli 0.29.0 → 0.31.0

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

package/src/domains/doctor/formatters/doctor.test.ts

@@ -48,6 +48,26 @@ const mixed: DoctorData = {
   skipped: 1,
 };
 
+const withItems: DoctorData = {
+  checks: [
+    {
+      name: "package refs",
+      status: "pass",
+      detail: "1 package resolved",
+      items: [
+        {
+          label: "@canonical/design-system",
+          status: "pass",
+          detail: "git v0.1.2 · 362 graphs, 3 skills",
+        },
+      ],
+    },
+  ],
+  passed: 1,
+  failed: 0,
+  skipped: 0,
+};
+
 describe("doctor formatters", () => {
   describe("plain", () => {
     it("renders passing checks with ✓", () => {
@@ -74,6 +94,29 @@ describe("doctor formatters", () => {
       const output = formatters.plain(allPass);
       expect(output).not.toContain("Run ");
     });
+
+    it("renders a summary tally", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("1 passed");
+      expect(output).toContain("2 failed");
+      expect(output).toContain("1 skipped");
+    });
+
+    it("renders sub-items indented under a check", () => {
+      const output = formatters.plain(withItems);
+      expect(output).toContain("@canonical/design-system");
+      expect(output).toContain("git v0.1.2 · 362 graphs, 3 skills");
+      // sub-item lines are indented beneath the check headline
+      const lines = output.split("\n");
+      const sub = lines.find((l) => l.includes("@canonical/design-system"));
+      expect(sub?.startsWith("     ")).toBe(true);
+    });
+
+    it("renders the remedy inline with a fix label", () => {
+      const output = formatters.plain(mixed);
+      expect(output).toContain("fix:");
+      expect(output).toContain("pragma config tier <tier>");
+    });
   });
 
   describe("llm", () => {
@@ -87,12 +130,17 @@ describe("doctor formatters", () => {
       expect(output).toContain("- ✓ **Node version**: v24.1.0");
     });
 
-    it("includes remedial section for failures", () => {
+    it("includes inline fixes for failures", () => {
       const output = formatters.llm(mixed);
-      expect(output).toContain("### Remedial");
+      expect(output).toContain("_fix:_");
       expect(output).toContain("`pragma config tier <tier>`");
       expect(output).toContain("`pragma setup completions`");
     });
+
+    it("renders sub-items as nested bullets", () => {
+      const output = formatters.llm(withItems);
+      expect(output).toContain("  - ✓ @canonical/design-system");
+    });
   });
 
   describe("json", () => {

package/src/domains/doctor/formatters/doctor.ts

@@ -1,78 +1,130 @@
 import chalk from "chalk";
 import type { Formatters } from "../../shared/formatters.js";
-import type { CheckResult, DoctorData } from "../operations/types.js";
+import type {
+  CheckResult,
+  CheckStatus,
+  DoctorData,
+} from "../operations/types.js";
 
-/** Status icons for pass/fail/skip check results. */
-const STATUS_ICONS = {
+/** Status icons for pass/fail/skip results (checks and sub-items). */
+const STATUS_ICONS: Record<CheckStatus, string> = {
   pass: chalk.green("✓"),
   fail: chalk.red("✗"),
   skip: chalk.yellow("○"),
-} as const;
+};
+
+const SUB_BULLET = chalk.dim("·");
+const FIX_ARROW = chalk.cyan("↳");
+const INDENT = "     "; // aligns sub-lines under the check name
 
 /**
- * Format a single check result as a styled terminal line.
+ * Render one check as terminal lines: a headline row (icon, aligned name,
+ * detail), an optional indented breakdown of sub-items, and — for failures —
+ * an inline remedial instruction.
  *
- * @param check - The check result to format.
- * @returns A single-line string with status icon, name, and detail.
+ * @param check - The check result to render.
+ * @param nameWidth - Width to pad check names to so details align in a column.
+ * @returns The lines for this check.
  */
-function formatCheckPlain(check: CheckResult): string {
-  return `${STATUS_ICONS[check.status]} ${check.name} ${chalk.dim(check.detail)}`;
+function formatCheckPlain(check: CheckResult, nameWidth: number): string[] {
+  const name = check.name.padEnd(nameWidth);
+  const label = check.status === "fail" ? chalk.red(name) : chalk.bold(name);
+  const lines = [
+    `  ${STATUS_ICONS[check.status]}  ${label}  ${chalk.dim(check.detail)}`,
+  ];
+
+  if (check.items && check.items.length > 0) {
+    const itemWidth = Math.max(...check.items.map((i) => i.label.length));
+    const anyStatus = check.items.some((i) => i.status !== undefined);
+    for (const item of check.items) {
+      const icon = anyStatus
+        ? item.status
+          ? `${STATUS_ICONS[item.status]} `
+          : "  "
+        : "";
+      const itemLabel = item.detail ? item.label.padEnd(itemWidth) : item.label;
+      const detail = item.detail ? `  ${chalk.dim(item.detail)}` : "";
+      lines.push(`${INDENT}${SUB_BULLET} ${icon}${itemLabel}${detail}`);
+    }
+  }
+
+  if (check.status === "fail" && check.remedy) {
+    lines.push(`${INDENT}${FIX_ARROW} ${chalk.cyan("fix:")} ${check.remedy}`);
+  }
+
+  return lines;
+}
+
+/** Render the pass/fail/skip tally, coloring non-zero fail/skip. */
+function formatSummary(data: DoctorData): string {
+  const parts = [chalk.green(`${data.passed} passed`)];
+  parts.push(
+    data.failed > 0
+      ? chalk.red(`${data.failed} failed`)
+      : chalk.dim(`${data.failed} failed`),
+  );
+  parts.push(
+    data.skipped > 0
+      ? chalk.yellow(`${data.skipped} skipped`)
+      : chalk.dim(`${data.skipped} skipped`),
+  );
+  return `  ${parts.join(chalk.dim(" · "))}`;
 }
 
 /**
  * Formatters for `pragma doctor` output.
  *
- * - **plain** renders a check list with chalk icons and remedial commands.
- * - **llm** renders a markdown list with remedial section.
- * - **json** serializes the raw DoctorData.
+ * - **plain** renders an aligned check list with indented sub-items and
+ *   inline remedies, followed by a summary tally.
+ * - **llm** renders a Markdown list with nested sub-items and inline fixes.
+ * - **json** serializes the raw DoctorData (including `items`).
  */
 const formatters: Formatters<DoctorData> = {
   plain(data) {
-    const lines: string[] = [];
+    const nameWidth = Math.max(...data.checks.map((c) => c.name.length), 0);
+    const lines: string[] = [chalk.bold("pragma doctor"), ""];
 
     for (const check of data.checks) {
-      lines.push(formatCheckPlain(check));
+      lines.push(...formatCheckPlain(check, nameWidth));
     }
 
-    const remedies = data.checks.filter(
-      (c): c is CheckResult & { remedy: string } =>
-        c.status === "fail" && c.remedy !== undefined,
-    );
-
-    if (remedies.length > 0) {
-      lines.push("");
-      for (const r of remedies) {
-        lines.push(
-          `Run ${chalk.cyan(`\`${r.remedy}\``)} to fix ${chalk.dim(r.name)}.`,
-        );
-      }
-    }
+    lines.push("");
+    lines.push(formatSummary(data));
 
     return lines.join("\n");
   },
 
   llm(data) {
-    const lines: string[] = [];
-
-    lines.push("## Doctor");
-    lines.push("");
+    const lines: string[] = ["## Doctor", ""];
 
     for (const check of data.checks) {
       const icon =
         check.status === "pass" ? "✓" : check.status === "fail" ? "✗" : "○";
       lines.push(`- ${icon} **${check.name}**: ${check.detail}`);
-    }
 
-    const remedies = data.checks.filter((c) => c.status === "fail" && c.remedy);
+      for (const item of check.items ?? []) {
+        const itemIcon =
+          item.status === "pass"
+            ? "✓ "
+            : item.status === "fail"
+              ? "✗ "
+              : item.status === "skip"
+                ? "○ "
+                : "";
+        const detail = item.detail ? `: ${item.detail}` : "";
+        lines.push(`  - ${itemIcon}${item.label}${detail}`);
+      }
 
-    if (remedies.length > 0) {
-      lines.push("");
-      lines.push("### Remedial");
-      for (const r of remedies) {
-        lines.push(`- \`${r.remedy}\``);
+      if (check.status === "fail" && check.remedy) {
+        lines.push(`  - _fix:_ \`${check.remedy}\``);
       }
     }
 
+    lines.push("");
+    lines.push(
+      `_${data.passed} passed, ${data.failed} failed, ${data.skipped} skipped_`,
+    );
+
     return lines.join("\n");
   },
 

package/src/domains/doctor/operations/checks/checkConfigFile.ts

@@ -1,21 +1,35 @@
-import { configExists } from "#config";
+import { readConfigLayers } from "#config";
 import type { CheckContext, CheckResult } from "../types.js";
 
 /**
- * Check that `pragma.config.json` exists in the working directory.
+ * Check which config layer is active for the working directory.
+ *
+ * Passes when a project `pragma.config.json` is found up the tree, or —
+ * pragma is global-first — when only the global XDG config exists. Fails
+ * only when neither layer is configured.
  *
  * @param ctx - Check context with the working directory.
- * @returns A CheckResult indicating pass or fail.
+ * @returns A CheckResult indicating pass or fail with the active layer.
  * @note Impure
  */
 export default async function checkConfigFile(
   ctx: CheckContext,
 ): Promise<CheckResult> {
-  if (configExists(ctx.cwd)) {
+  const layers = readConfigLayers(ctx.cwd);
+
+  if (layers.project.exists) {
+    return {
+      name: "pragma.config.json",
+      status: "pass",
+      detail: `found (${layers.project.path})`,
+    };
+  }
+
+  if (layers.global.exists) {
     return {
       name: "pragma.config.json",
       status: "pass",
-      detail: "found",
+      detail: `no project config — global config active (${layers.global.path})`,
     };
   }