@canonical/pragma-cli 0.18.0

package/src/pipeline/collectCommands.ts

@@ -0,0 +1,47 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import { commands as blockCommands } from "../domains/block/index.js";
+import { commands as configCommands } from "../domains/config/index.js";
+import { commands as createCommands } from "../domains/create/index.js";
+import { doctorCommand } from "../domains/doctor/commands/index.js";
+import { commands as graphCommands } from "../domains/graph/index.js";
+import { infoCommand, upgradeCommand } from "../domains/info/index.js";
+import { buildLlmCommand } from "../domains/llm/index.js";
+import { commands as modifierCommands } from "../domains/modifier/index.js";
+import { commands as ontologyCommands } from "../domains/ontology/index.js";
+import { commands as setupCommands } from "../domains/setup/index.js";
+import type { PragmaContext } from "../domains/shared/context.js";
+import { commands as skillCommands } from "../domains/skill/index.js";
+import { commands as standardCommands } from "../domains/standard/index.js";
+import { commands as tierCommands } from "../domains/tier/index.js";
+import { commands as tokenCommands } from "../domains/token/index.js";
+
+/**
+ * Collect all CLI command definitions from domain modules.
+ *
+ * Extracted from runCli so the completions server can import
+ * the command list independently without running the full CLI pipeline.
+ *
+ * @param ctx - The pragma context providing store, config, and global flags.
+ * @returns The full array of command definitions for all domains.
+ */
+export default function collectCommands(
+  ctx: PragmaContext,
+): CommandDefinition[] {
+  return [
+    ...configCommands(ctx),
+    ...createCommands(),
+    ...setupCommands(),
+    ...standardCommands(ctx),
+    ...modifierCommands(ctx),
+    ...tierCommands(ctx),
+    ...tokenCommands(ctx),
+    ...blockCommands(ctx),
+    ...ontologyCommands(ctx),
+    ...graphCommands(ctx),
+    ...skillCommands(ctx),
+    doctorCommand,
+    infoCommand,
+    upgradeCommand,
+    buildLlmCommand(ctx),
+  ];
+}

package/src/pipeline/constants.ts

@@ -0,0 +1,14 @@
+import type { ErrorCode } from "../error/types.js";
+
+/** Map from error codes to numeric process exit codes. */
+const EXIT_CODES: Record<ErrorCode, number> = {
+  ENTITY_NOT_FOUND: 1,
+  EMPTY_RESULTS: 2,
+  INVALID_INPUT: 3,
+  AMBIGUOUS_INPUT: 3,
+  CONFIG_ERROR: 4,
+  STORE_ERROR: 5,
+  INTERNAL_ERROR: 127,
+};
+
+export { EXIT_CODES };

package/src/pipeline/createProgram.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const runMcpServerMock = vi.fn(async () => undefined);
+
+vi.mock("../mcp/runMcpServer.js", () => ({
+  default: runMcpServerMock,
+}));
+
+describe("createProgram", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  it("uses plain root help when llm is disabled", async () => {
+    const { default: createProgram } = await import("./createProgram.js");
+
+    const program = createProgram([], {
+      cwd: "/tmp/work",
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      globalFlags: { llm: false, format: "text", verbose: false },
+    });
+    const write = vi.fn();
+    (
+      program as {
+        _events: {
+          beforeAllHelp: (ctx: {
+            command: unknown;
+            write: (value: string) => void;
+          }) => void;
+        };
+      }
+    )._events.beforeAllHelp({ command: program, write });
+
+    expect(write).toHaveBeenCalledWith(
+      expect.stringContaining("Usage: pragma <command> [options]"),
+    );
+  });
+
+  it("uses llm root help when llm is enabled", async () => {
+    const { default: createProgram } = await import("./createProgram.js");
+
+    const program = createProgram([], {
+      cwd: "/tmp/work",
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      globalFlags: { llm: true, format: "text", verbose: false },
+    });
+    const write = vi.fn();
+    (
+      program as {
+        _events: {
+          beforeAllHelp: (ctx: {
+            command: unknown;
+            write: (value: string) => void;
+          }) => void;
+        };
+      }
+    )._events.beforeAllHelp({ command: program, write });
+
+    expect(write).toHaveBeenCalledWith(
+      expect.stringContaining("# pragma commands"),
+    );
+  });
+
+  it("does not inject root help text into subcommand help", async () => {
+    const { default: createProgram } = await import("./createProgram.js");
+
+    const program = createProgram([], {
+      cwd: "/tmp/work",
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      globalFlags: { llm: false, format: "text", verbose: false },
+    });
+
+    const mcpCommand = program.commands.find(
+      (command) => command.name() === "mcp",
+    );
+    expect(mcpCommand).toBeDefined();
+    const write = vi.fn();
+    (
+      program as {
+        _events: {
+          beforeAllHelp: (ctx: {
+            command: unknown;
+            write: (value: string) => void;
+          }) => void;
+        };
+      }
+    )._events.beforeAllHelp({ command: mcpCommand, write });
+    expect(write).not.toHaveBeenCalled();
+  });
+
+  it("runs the mcp subcommand action", async () => {
+    const { default: createProgram } = await import("./createProgram.js");
+
+    const program = createProgram([], {
+      cwd: "/tmp/work",
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      globalFlags: { llm: false, format: "text", verbose: false },
+    });
+
+    await program.parseAsync(["node", "pragma", "mcp"]);
+
+    expect(runMcpServerMock).toHaveBeenCalledTimes(1);
+  });
+});

package/src/pipeline/createProgram.ts

@@ -0,0 +1,70 @@
+import {
+  type CommandDefinition,
+  formatHelp,
+  formatLlmHelp,
+  registerAll,
+} from "@canonical/cli-core";
+import { Command } from "commander";
+import { PROGRAM_DESCRIPTION, PROGRAM_NAME, VERSION } from "../constants.js";
+import type { PragmaContext } from "../domains/shared/context.js";
+
+/**
+ * Build and configure the top-level Commander program.
+ *
+ * Registers all domain commands, global flags, help formatting,
+ * and the `mcp` subcommand. Returns the configured Commander instance
+ * ready for `parseAsync`.
+ *
+ * @param commands - Domain command definitions to register.
+ * @param ctx - Shared pragma context (global flags, store, config).
+ * @returns Configured Commander program.
+ *
+ * @note Impure — attaches process.stdout/stderr handlers and lazy-imports the MCP server.
+ */
+export default function createProgram(
+  commands: readonly CommandDefinition[],
+  ctx: PragmaContext,
+): Command {
+  const program = new Command();
+  program.name(PROGRAM_NAME);
+  program.version(VERSION, "-V, --version");
+  program.description(PROGRAM_DESCRIPTION);
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: (str) => process.stdout.write(str),
+    writeErr: (str) => process.stderr.write(str),
+  });
+
+  program.option(
+    "--llm",
+    "Condensed Markdown output for LLM consumption",
+    false,
+  );
+  program.option("--format <type>", "Output format (text or json)", "text");
+  program.option("--verbose", "Diagnostic output to stderr", false);
+
+  program.addHelpText("beforeAll", (_ctx) => {
+    // Only show root-level help when the help is for the root program itself.
+    // Subcommand help is handled by registerAll via formatNounHelp/formatVerbHelp.
+    if (_ctx.command !== program) return "";
+    if (ctx.globalFlags.llm) {
+      return formatLlmHelp(PROGRAM_NAME, commands);
+    }
+    return formatHelp(PROGRAM_NAME, PROGRAM_DESCRIPTION, commands);
+  });
+
+  program.helpOption("-h, --help", "Show help");
+  program.configureHelp({ formatHelp: () => "" });
+
+  program
+    .command("mcp")
+    .description("Start the MCP server over stdio")
+    .action(async () => {
+      const { default: runMcpServer } = await import("../mcp/runMcpServer.js");
+      await runMcpServer();
+    });
+
+  registerAll(program, commands, ctx);
+
+  return program;
+}

package/src/pipeline/formatTerminal.test.ts

@@ -0,0 +1,43 @@
+import chalk from "chalk";
+import { describe, expect, it } from "vitest";
+import {
+  formatField,
+  formatHeading,
+  formatList,
+  formatSection,
+} from "./formatTerminal.js";
+
+describe("formatHeading", () => {
+  it("applies bold and underline", () => {
+    expect(formatHeading("Title")).toBe(chalk.bold.underline("Title"));
+  });
+});
+
+describe("formatField", () => {
+  it("renders dim label with value", () => {
+    expect(formatField("Name:", "Button")).toBe(`${chalk.dim("Name:")} Button`);
+  });
+});
+
+describe("formatList", () => {
+  it("renders items with default bullet", () => {
+    const result = formatList(["one", "two", "three"]);
+    expect(result).toBe("  - one\n  - two\n  - three");
+  });
+
+  it("uses custom bullet", () => {
+    const result = formatList(["a", "b"], "*");
+    expect(result).toBe("  * a\n  * b");
+  });
+
+  it("returns empty string for empty array", () => {
+    expect(formatList([])).toBe("");
+  });
+});
+
+describe("formatSection", () => {
+  it("combines heading and body", () => {
+    const result = formatSection("Details", "some content");
+    expect(result).toBe(`${chalk.bold.underline("Details")}\nsome content`);
+  });
+});

package/src/pipeline/formatTerminal.ts

@@ -0,0 +1,53 @@
+/**
+ * Terminal formatting helpers for CLI output.
+ *
+ * Pure string transformers that apply chalk styling
+ * for headings, fields, lists, and sections.
+ */
+
+import chalk from "chalk";
+
+/**
+ * Format text as a bold underlined heading.
+ *
+ * @param text - Heading content.
+ * @returns Styled string.
+ */
+function formatHeading(text: string): string {
+  return chalk.bold.underline(text);
+}
+
+/**
+ * Format a label–value pair with a dimmed label.
+ *
+ * @param label - Field label (rendered dim).
+ * @param value - Field value.
+ * @returns Styled `"label value"` string.
+ */
+function formatField(label: string, value: string): string {
+  return `${chalk.dim(label)} ${value}`;
+}
+
+/**
+ * Format an array of items as a bulleted list.
+ *
+ * @param items - Lines to render.
+ * @param bullet - Bullet character (default `"-"`).
+ * @returns Multi-line bulleted string.
+ */
+function formatList(items: string[], bullet = "-"): string {
+  return items.map((item) => `  ${bullet} ${item}`).join("\n");
+}
+
+/**
+ * Combine a heading and a body block into a section.
+ *
+ * @param heading - Section heading text.
+ * @param body - Pre-formatted body content.
+ * @returns Heading followed by body, separated by a newline.
+ */
+function formatSection(heading: string, body: string): string {
+  return `${formatHeading(heading)}\n${body}`;
+}
+
+export { formatField, formatHeading, formatList, formatSection };

package/src/pipeline/index.ts

@@ -0,0 +1,19 @@
+/** @module CLI pipeline — program construction, flag parsing, error rendering, and command routing. */
+export { default as collectCommands } from "./collectCommands.js";
+export { default as createProgram } from "./createProgram.js";
+export {
+  formatField,
+  formatHeading,
+  formatList,
+  formatSection,
+} from "./formatTerminal.js";
+export { default as mapExitCode } from "./mapExitCode.js";
+export { default as parseGlobalFlags } from "./parseGlobalFlags.js";
+export {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "./renderError.js";
+export { default as resolveCommandKind } from "./resolveCommandKind.js";
+export { default as runCli } from "./runCli.js";
+export type { CommandKind } from "./types.js";

package/src/pipeline/mapExitCode.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { ERROR_CODES } from "../error/index.js";
+import { EXIT_CODES } from "./constants.js";
+import mapExitCode from "./mapExitCode.js";
+
+describe("mapExitCode", () => {
+  it("maps ENTITY_NOT_FOUND to 1", () => {
+    expect(mapExitCode("ENTITY_NOT_FOUND")).toBe(1);
+  });
+
+  it("maps EMPTY_RESULTS to 2", () => {
+    expect(mapExitCode("EMPTY_RESULTS")).toBe(2);
+  });
+
+  it("maps INVALID_INPUT to 3", () => {
+    expect(mapExitCode("INVALID_INPUT")).toBe(3);
+  });
+
+  it("maps AMBIGUOUS_INPUT to 3", () => {
+    expect(mapExitCode("AMBIGUOUS_INPUT")).toBe(3);
+  });
+
+  it("maps CONFIG_ERROR to 4", () => {
+    expect(mapExitCode("CONFIG_ERROR")).toBe(4);
+  });
+
+  it("maps STORE_ERROR to 5", () => {
+    expect(mapExitCode("STORE_ERROR")).toBe(5);
+  });
+
+  it("maps INTERNAL_ERROR to 127", () => {
+    expect(mapExitCode("INTERNAL_ERROR")).toBe(127);
+  });
+
+  it("covers every ErrorCode", () => {
+    for (const code of ERROR_CODES) {
+      expect(typeof mapExitCode(code)).toBe("number");
+    }
+    expect(Object.keys(EXIT_CODES)).toHaveLength(ERROR_CODES.length);
+  });
+});

package/src/pipeline/mapExitCode.ts

@@ -0,0 +1,12 @@
+import type { ErrorCode } from "../error/types.js";
+import { EXIT_CODES } from "./constants.js";
+
+/**
+ * Map a PragmaError error code to a numeric process exit code.
+ *
+ * @param code - Machine-readable error code.
+ * @returns Corresponding exit code from the EXIT_CODES table.
+ */
+export default function mapExitCode(code: ErrorCode): number {
+  return EXIT_CODES[code];
+}

package/src/pipeline/parseGlobalFlags.ts

@@ -0,0 +1,21 @@
+import type { GlobalFlags } from "@canonical/cli-core";
+
+/**
+ * Extract global flags (--llm, --format, --verbose) from raw argv.
+ *
+ * Performs simple indexOf scanning rather than full argument parsing
+ * so it can run before Commander processes the command tree.
+ *
+ * @param argv - Raw process.argv array.
+ * @returns Parsed global flags.
+ */
+export default function parseGlobalFlags(argv: readonly string[]): GlobalFlags {
+  return {
+    llm: argv.includes("--llm"),
+    format:
+      argv.includes("--format") && argv[argv.indexOf("--format") + 1] === "json"
+        ? "json"
+        : "text",
+    verbose: argv.includes("--verbose"),
+  };
+}

package/src/pipeline/renderError.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it } from "vitest";
+import { PragmaError } from "../error/index.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "./renderError.js";
+
+describe("renderErrorPlain", () => {
+  it("renders a basic error", () => {
+    const err = PragmaError.internalError("something broke");
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Error: Internal error: something broke");
+    expect(out).toContain("Please report this issue.");
+  });
+
+  it("renders suggestions", () => {
+    const err = PragmaError.notFound("component", "Buton", {
+      suggestions: ["Button", "ButtonGroup"],
+    });
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Did you mean?");
+    expect(out).toContain("  - Button");
+    expect(out).toContain("  - ButtonGroup");
+  });
+
+  it("renders filters", () => {
+    const err = PragmaError.emptyResults("component", {
+      filters: { tier: "apps/lxd", channel: "normal" },
+    });
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Active filters:");
+    expect(out).toContain("  tier: apps/lxd");
+    expect(out).toContain("  channel: normal");
+  });
+
+  it("renders validOptions", () => {
+    const err = PragmaError.invalidInput("channel", "aggressive", {
+      validOptions: ["normal", "experimental", "prerelease"],
+    });
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Valid options: normal, experimental, prerelease");
+  });
+
+  it("renders recovery with cli command", () => {
+    const err = PragmaError.notFound("component", "Foo", {
+      recovery: {
+        message: "List available components.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    });
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Run `pragma block list`");
+  });
+
+  it("renders recovery with message only (no cli)", () => {
+    const err = PragmaError.emptyResults("component", {
+      recovery: {
+        message: "Ensure design system packages are installed.",
+      },
+    });
+    const out = renderErrorPlain(err);
+    expect(out).toContain("Ensure design system packages are installed.");
+  });
+});
+
+describe("renderErrorLlm", () => {
+  it("renders structured markdown", () => {
+    const err = PragmaError.notFound("component", "Buton", {
+      suggestions: ["Button", "ButtonGroup"],
+      recovery: {
+        message: "List available components.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    });
+    const out = renderErrorLlm(err);
+    expect(out).toContain("## Error: ENTITY_NOT_FOUND");
+    expect(out).toContain('component "Buton" not found.');
+    expect(out).toContain("Suggestions: Button, ButtonGroup");
+    expect(out).toContain("Recovery: `pragma block list`");
+  });
+
+  it("renders filters", () => {
+    const err = PragmaError.emptyResults("component", {
+      filters: { tier: "apps/lxd" },
+    });
+    const out = renderErrorLlm(err);
+    expect(out).toContain("Filters: tier=apps/lxd");
+  });
+
+  it("renders validOptions", () => {
+    const err = PragmaError.invalidInput("channel", "bad", {
+      validOptions: ["normal", "experimental"],
+    });
+    const out = renderErrorLlm(err);
+    expect(out).toContain("Valid options: normal, experimental");
+  });
+
+  it("renders recovery message when no cli", () => {
+    const err = PragmaError.emptyResults("component", {
+      recovery: {
+        message: "Install packages first.",
+      },
+    });
+    const out = renderErrorLlm(err);
+    expect(out).toContain("Recovery: Install packages first.");
+  });
+});
+
+describe("renderErrorJson", () => {
+  it("produces valid JSON with all fields", () => {
+    const err = PragmaError.notFound("component", "Buton", {
+      suggestions: ["Button"],
+      recovery: {
+        message: "List available components.",
+        cli: "pragma block list",
+        mcp: { tool: "block_list" },
+      },
+    });
+    const parsed = JSON.parse(renderErrorJson(err));
+    expect(parsed.code).toBe("ENTITY_NOT_FOUND");
+    expect(parsed.message).toBe('component "Buton" not found.');
+    expect(parsed.entity).toEqual({ type: "component", name: "Buton" });
+    expect(parsed.suggestions).toEqual(["Button"]);
+    expect(parsed.recovery).toEqual({
+      message: "List available components.",
+      cli: "pragma block list",
+      mcp: { tool: "block_list" },
+    });
+  });
+
+  it("includes filters and validOptions", () => {
+    const err = PragmaError.emptyResults("component", {
+      filters: { tier: "global" },
+    });
+    const parsed = JSON.parse(renderErrorJson(err));
+    expect(parsed.code).toBe("EMPTY_RESULTS");
+    expect(parsed.filters).toEqual({ tier: "global" });
+  });
+
+  it("includes undefined fields as undefined/null", () => {
+    const err = PragmaError.storeError("disk full");
+    const parsed = JSON.parse(renderErrorJson(err));
+    expect(parsed.code).toBe("STORE_ERROR");
+    expect(parsed.entity).toBeUndefined();
+    expect(parsed.filters).toBeUndefined();
+    expect(parsed.validOptions).toBeUndefined();
+  });
+});