@canonical/pragma-cli 0.18.0

package/src/domains/config/operations/validateTier.ts

@@ -0,0 +1,35 @@
+import type { Store } from "@canonical/ke";
+import { PragmaError } from "#error";
+import type { TierEntry } from "../../shared/types.js";
+import { listTiers } from "../../tier/operations/index.js";
+
+/**
+ * Validate a tier path against the ke store ontology.
+ *
+ * @param store - The booted ke store.
+ * @param tierPath - The tier path string to validate.
+ * @returns The matching TierEntry.
+ * @throws PragmaError.invalidInput if the tier path does not exist in the ontology.
+ * @note Queries ke store
+ */
+export default async function validateTier(
+  store: Store,
+  tierPath: string,
+): Promise<TierEntry> {
+  const tiers = await listTiers(store);
+  const match = tiers.find((t) => t.path === tierPath);
+
+  if (!match) {
+    const validPaths = tiers.map((t) => t.path);
+    throw PragmaError.invalidInput("tier", tierPath, {
+      validOptions: validPaths,
+      recovery: {
+        message: "Reset tier configuration.",
+        cli: "pragma config tier --reset",
+        mcp: { tool: "config_tier", params: { reset: true } },
+      },
+    });
+  }
+
+  return match;
+}

package/src/domains/create/commands/component.test.ts

@@ -0,0 +1,166 @@
+import type { CommandContext, CommandDefinition } from "@canonical/cli-core";
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "#error";
+import buildComponentCommand from "./component.js";
+
+const ctx: CommandContext = {
+  cwd: "/tmp",
+  globalFlags: { llm: false, format: "text" as const, verbose: false },
+};
+
+const llmCtx: CommandContext = {
+  cwd: "/tmp",
+  globalFlags: { llm: true, format: "text" as const, verbose: false },
+};
+
+const jsonCtx: CommandContext = {
+  cwd: "/tmp",
+  globalFlags: { llm: false, format: "json" as const, verbose: false },
+};
+
+async function executeOutput(
+  cmd: CommandDefinition,
+  params: Record<string, unknown>,
+  context: CommandContext,
+): Promise<{ value: unknown; text: string }> {
+  const result = await cmd.execute(params, context);
+  expect(result.tag).toBe("output");
+  if (result.tag !== "output") throw new Error("Expected output result");
+  const text = result.render.plain(result.value);
+  return { value: result.value, text };
+}
+
+describe("buildComponentCommand", () => {
+  it("has correct path", () => {
+    const cmd = buildComponentCommand();
+    expect(cmd.path).toEqual(["create", "component"]);
+  });
+
+  it("includes framework as positional required select parameter", () => {
+    const cmd = buildComponentCommand();
+    const framework = cmd.parameters.find((p) => p.name === "framework");
+    expect(framework).toBeDefined();
+    expect(framework?.positional).toBe(true);
+    expect(framework?.required).toBe(true);
+    expect(framework?.type).toBe("select");
+    expect(framework?.choices?.map((c) => c.value)).toEqual([
+      "react",
+      "svelte",
+      "lit",
+    ]);
+  });
+
+  it("includes prompt-derived parameters", () => {
+    const cmd = buildComponentCommand();
+    const names = cmd.parameters.map((p) => p.name);
+    expect(names).toContain("componentPath");
+    expect(names).toContain("withStyles");
+    expect(names).toContain("withStories");
+    expect(names).toContain("withSsrTests");
+  });
+
+  it("includes execution-mode parameters", () => {
+    const cmd = buildComponentCommand();
+    const names = cmd.parameters.map((p) => p.name);
+    expect(names).toContain("dryRun");
+    expect(names).toContain("yes");
+    expect(names).toContain("showFiles");
+    expect(names).toContain("preview");
+    expect(names).toContain("generatedStamp");
+  });
+
+  it("dry-run with react returns output with file paths", async () => {
+    const cmd = buildComponentCommand();
+    const { text } = await executeOutput(
+      cmd,
+      {
+        framework: "react",
+        componentPath: "src/components/Button",
+        dryRun: true,
+        yes: true,
+      },
+      ctx,
+    );
+    expect(text).toContain("Button");
+    expect(text).toContain("src/components/Button");
+  });
+
+  it("dry-run with svelte returns output with svelte files", async () => {
+    const cmd = buildComponentCommand();
+    const { text } = await executeOutput(
+      cmd,
+      {
+        framework: "svelte",
+        componentPath: "src/lib/components/Toggle",
+        dryRun: true,
+        yes: true,
+      },
+      ctx,
+    );
+    expect(text).toContain("Toggle");
+    expect(text).toContain("src/lib/components/Toggle");
+  });
+
+  it("LLM mode returns markdown", async () => {
+    const cmd = buildComponentCommand();
+    const { text } = await executeOutput(
+      cmd,
+      {
+        framework: "react",
+        componentPath: "src/components/Card",
+      },
+      llmCtx,
+    );
+    // LLM markdown output includes generator name header
+    expect(text).toContain("component/react");
+  });
+
+  it("JSON mode returns parseable JSON", async () => {
+    const cmd = buildComponentCommand();
+    const { text } = await executeOutput(
+      cmd,
+      {
+        framework: "react",
+        componentPath: "src/components/Card",
+      },
+      jsonCtx,
+    );
+    const data = JSON.parse(text);
+    expect(data.generator.name).toBe("component/react");
+    expect(Array.isArray(data.plan)).toBe(true);
+  });
+
+  it("throws PragmaError for invalid framework", async () => {
+    const cmd = buildComponentCommand();
+    await expect(cmd.execute({ framework: "angular" }, ctx)).rejects.toThrow(
+      PragmaError,
+    );
+  });
+
+  it("throws PragmaError when framework is missing", async () => {
+    const cmd = buildComponentCommand();
+    await expect(cmd.execute({}, ctx)).rejects.toThrow(PragmaError);
+  });
+
+  it("returns interactive result when required answers are missing", async () => {
+    const cmd = buildComponentCommand();
+    // framework provided but componentPath has a default, so it should NOT
+    // trigger interactive mode — all prompts have defaults
+    const result = await cmd.execute({ framework: "lit", dryRun: true }, ctx);
+    // componentPath has a default, so executeGenerator applies it and proceeds
+    expect(result.tag).toBe("output");
+  });
+
+  it("has parameter groups", () => {
+    const cmd = buildComponentCommand();
+    expect(cmd.parameterGroups).toEqual({
+      Component: ["componentPath"],
+      Options: ["withStyles", "withStories", "withSsrTests"],
+    });
+  });
+
+  it("has examples in meta", () => {
+    const cmd = buildComponentCommand();
+    expect(cmd.meta?.examples?.length).toBeGreaterThan(0);
+  });
+});

package/src/domains/create/commands/component.ts

@@ -0,0 +1,129 @@
+import {
+  type CommandDefinition,
+  executeGenerator,
+  type ParameterDefinition,
+  promptToParameter,
+} from "@canonical/cli-core";
+import { generators } from "@canonical/summon-component";
+import type { AnyGenerator } from "@canonical/summon-core";
+import { PragmaError } from "#error";
+
+const FRAMEWORK_CHOICES = [
+  { label: "react", value: "react" },
+  { label: "svelte", value: "svelte" },
+  { label: "lit", value: "lit" },
+] as const;
+
+const GENERATOR_MAP: Record<string, AnyGenerator> = {
+  react: generators["component/react"],
+  svelte: generators["component/svelte"],
+  lit: generators["component/lit"],
+};
+
+/** Reference generator used to derive shared prompt parameters. */
+const referenceGenerator = generators["component/react"];
+
+/**
+ * Build the `pragma create component` command definition.
+ *
+ * Uses a dispatch pattern: `framework` is a required positional select
+ * parameter. The execute function looks up the matching generator and
+ * delegates to `executeGenerator` from cli-core.
+ *
+ * @returns The command definition for `pragma create component`.
+ * @note Impure
+ */
+export default function buildComponentCommand(): CommandDefinition {
+  const frameworkParam: ParameterDefinition = {
+    name: "framework",
+    description: "Component framework (react, svelte, lit)",
+    type: "select",
+    choices: [...FRAMEWORK_CHOICES],
+    positional: true,
+    required: true,
+  };
+
+  // Derive prompt parameters from the reference generator
+  const promptParams = referenceGenerator.prompts.map(promptToParameter);
+
+  // Execution-mode parameters (same as generatorToCommand appends)
+  const execParams: ParameterDefinition[] = [
+    {
+      name: "dryRun",
+      description: "Preview without writing files",
+      type: "boolean",
+    },
+    {
+      name: "undo",
+      description: "Reverse a previously generated component",
+      type: "boolean",
+    },
+    {
+      name: "yes",
+      description: "Skip confirmation prompts",
+      type: "boolean",
+    },
+    {
+      name: "showFiles",
+      description: "Show file contents in dry-run",
+      type: "boolean",
+    },
+    {
+      name: "preview",
+      description: "Show file preview before writing",
+      type: "boolean",
+      default: true,
+    },
+    {
+      name: "generatedStamp",
+      description: "Add generated file stamps",
+      type: "boolean",
+      default: true,
+    },
+  ];
+
+  const parameters = [frameworkParam, ...promptParams, ...execParams];
+
+  return {
+    path: ["create", "component"],
+    description:
+      "Generate a component with TypeScript, tests, stories, and styles",
+    parameters,
+    execute: async (params, ctx) => {
+      const framework = params.framework as string | undefined;
+      if (!framework) {
+        throw PragmaError.invalidInput("framework", "(missing)", {
+          validOptions: ["react", "svelte", "lit"],
+          recovery: {
+            message: "Provide a framework for component generation.",
+            cli: "pragma create component react --component-path src/components/Button",
+          },
+        });
+      }
+
+      const gen = GENERATOR_MAP[framework];
+      if (!gen) {
+        throw PragmaError.invalidInput("framework", framework, {
+          validOptions: Object.keys(GENERATOR_MAP),
+          recovery: {
+            message: `Valid frameworks: ${Object.keys(GENERATOR_MAP).join(", ")}`,
+          },
+        });
+      }
+
+      return executeGenerator(gen, params, ctx);
+    },
+    meta: {
+      examples: [
+        "pragma create component react --component-path src/components/Button",
+        "pragma create component svelte --component-path src/lib/components/Toggle",
+        "pragma create component lit --component-path src/lib/Accordion",
+        "pragma create component react --component-path src/components/Button --dry-run",
+      ],
+    },
+    parameterGroups: {
+      Component: ["componentPath"],
+      Options: ["withStyles", "withStories", "withSsrTests"],
+    },
+  };
+}

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

@@ -0,0 +1,3 @@
+/** @module Create command definitions for `pragma create`. */
+export { default as componentCommand } from "./component.js";
+export { default as packageCommand } from "./package.js";

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

@@ -0,0 +1,35 @@
+import type { CommandContext } from "@canonical/cli-core";
+import { describe, expect, it } from "vitest";
+import buildPackageCommand from "./package.js";
+
+const ctx: CommandContext = {
+  cwd: "/tmp",
+  globalFlags: { llm: false, format: "text" as const, verbose: false },
+};
+
+describe("buildPackageCommand", () => {
+  it("has correct path", () => {
+    const cmd = buildPackageCommand();
+    expect(cmd.path).toEqual(["create", "package"]);
+  });
+
+  it("dry-run with all params returns output", async () => {
+    const cmd = buildPackageCommand();
+    const result = await cmd.execute(
+      {
+        name: "@canonical/test-pkg",
+        type: "tool-ts",
+        dryRun: true,
+        yes: true,
+      },
+      ctx,
+    );
+    expect(result.tag).toBe("output");
+  });
+
+  it("with missing required params returns interactive", async () => {
+    const cmd = buildPackageCommand();
+    const result = await cmd.execute({}, ctx);
+    expect(result.tag).toBe("interactive");
+  });
+});

package/src/domains/create/commands/package.ts

@@ -0,0 +1,21 @@
+import {
+  type CommandDefinition,
+  generatorToCommand,
+} from "@canonical/cli-core";
+import { generators as packageGenerators } from "@canonical/summon-package";
+
+/**
+ * Build the `pragma create package` command definition by bridging
+ * the package generator via `generatorToCommand`.
+ *
+ * @returns The command definition for `pragma create package`.
+ * @throws Error if the package generator is not found.
+ * @note Impure
+ */
+export default function buildPackageCommand(): CommandDefinition {
+  const gen = packageGenerators.package;
+  if (!gen) {
+    throw new Error("Package generator not found in @canonical/summon-package");
+  }
+  return generatorToCommand(["create", "package"], gen);
+}

package/src/domains/create/index.ts

@@ -0,0 +1,15 @@
+/** @module Create domain -- generator commands for `pragma create` (component and package). */
+
+import type { CommandDefinition } from "@canonical/cli-core";
+import { componentCommand, packageCommand } from "./commands/index.js";
+
+/**
+ * Return all create command definitions.
+ *
+ * @returns An array of CommandDefinitions for component and package generators.
+ */
+export function commands(): CommandDefinition[] {
+  return [componentCommand(), packageCommand()];
+}
+
+export { specs as mcpSpecs } from "./mcp/index.js";

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

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

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

@@ -0,0 +1,174 @@
+/**
+ * MCP tool specs for create domain — create_component, create_package.
+ */
+
+import { executeGenerator } from "@canonical/cli-core";
+import { generators as componentGenerators } from "@canonical/summon-component";
+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";
+
+const componentGeneratorMap: Record<string, AnyGenerator> = {
+  react: componentGenerators["component/react"],
+  svelte: componentGenerators["component/svelte"],
+  lit: componentGenerators["component/lit"],
+};
+
+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 = componentGeneratorMap[framework];
+      if (!gen) {
+        throw PragmaError.invalidInput("framework", framework, {
+          validOptions: Object.keys(componentGeneratorMap),
+        });
+      }
+
+      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));
+    },
+  },
+];
+
+export default specs;

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

@@ -0,0 +1,75 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { selectFormatterMock, runChecksMock } = vi.hoisted(() => ({
+  selectFormatterMock: vi.fn(
+    () => (data: { passed: number }) => `passed=${data.passed}`,
+  ),
+  runChecksMock: vi.fn(),
+}));
+
+vi.mock("../../shared/formatters.js", () => ({
+  selectFormatter: selectFormatterMock,
+}));
+
+vi.mock("../operations/index.js", () => ({
+  runChecks: runChecksMock,
+}));
+
+import doctorCommand from "./doctor.js";
+
+describe("doctorCommand", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+  });
+
+  it("has path ['doctor']", () => {
+    expect(doctorCommand.path).toEqual(["doctor"]);
+  });
+
+  it("has a description", () => {
+    expect(doctorCommand.description).toBeTruthy();
+  });
+
+  it("has no parameters", () => {
+    expect(doctorCommand.parameters).toEqual([]);
+  });
+
+  it("has an execute function", () => {
+    expect(typeof doctorCommand.execute).toBe("function");
+  });
+
+  it("returns formatted output without setting an error exit code when checks pass", async () => {
+    runChecksMock.mockResolvedValue({ checks: [], passed: 2, failed: 0 });
+
+    const result = await doctorCommand.execute(
+      {},
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: false, format: "text", verbose: false },
+      },
+    );
+
+    expect(runChecksMock).toHaveBeenCalledWith({ cwd: "/workspace" });
+    expect(result.tag).toBe("output");
+    if (result.tag === "output") {
+      expect(result.render.plain(result.value)).toBe("passed=2");
+    }
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it("sets exitCode when checks fail", async () => {
+    runChecksMock.mockResolvedValue({ checks: [], passed: 1, failed: 1 });
+
+    await doctorCommand.execute(
+      {},
+      {
+        cwd: "/workspace",
+        globalFlags: { llm: true, format: "json", verbose: false },
+      },
+    );
+
+    expect(selectFormatterMock).toHaveBeenCalled();
+    expect(process.exitCode).toBe(1);
+  });
+});