@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/pipeline/collectCommands.test.ts

@@ -1,37 +0,0 @@
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import type { PragmaContext } from "../domains/shared/context.js";
-import type { PragmaRuntime } from "../domains/shared/runtime.js";
-import createTestRuntime from "../testing/helpers/createTestRuntime.js";
-import collectCommands from "./collectCommands.js";
-
-let runtime: PragmaRuntime;
-
-beforeAll(async () => {
-  runtime = await createTestRuntime();
-});
-
-afterAll(() => {
-  runtime.dispose();
-});
-
-function makeCtx(overrides: Partial<PragmaContext> = {}): PragmaContext {
-  return {
-    ...runtime,
-    globalFlags: { llm: false, format: "text" as const, verbose: false },
-    ...overrides,
-  };
-}
-
-describe("collectCommands", () => {
-  it("includes block, ontology, and graph command paths", () => {
-    const commands = collectCommands(makeCtx());
-    const paths = commands.map((command) => command.path.join(" "));
-
-    expect(paths).toContain("block list");
-    expect(paths).toContain("block lookup");
-    expect(paths).toContain("ontology list");
-    expect(paths).toContain("ontology show");
-    expect(paths).toContain("graph query");
-    expect(paths).toContain("graph inspect");
-  });
-});

package/src/pipeline/collectCommands.ts

@@ -1,60 +0,0 @@
-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 { commands as graphqlCommands } from "../domains/graphql/index.js";
-import { infoCommand, upgradeCommand } from "../domains/info/index.js";
-import {
-  buildCapabilitiesCommand,
-  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 { compilePackCommands } from "../domains/shared/stories/pack/index.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[] {
-  const builtIn: CommandDefinition[] = [
-    ...configCommands(ctx),
-    ...createCommands(),
-    ...setupCommands(),
-    ...standardCommands(ctx),
-    ...modifierCommands(ctx),
-    ...tierCommands(ctx),
-    ...tokenCommands(ctx),
-    ...blockCommands(ctx),
-    ...ontologyCommands(ctx),
-    ...graphCommands(ctx),
-    ...graphqlCommands(),
-    ...skillCommands(ctx),
-    doctorCommand,
-    infoCommand,
-    upgradeCommand,
-    buildLlmCommand(ctx),
-    buildCapabilitiesCommand(),
-  ];
-
-  // Story packs project onto the same surface; built-in nouns are reserved.
-  const reservedNouns = new Set(
-    builtIn.map((command) => command.path.at(0) ?? ""),
-  );
-  return [...builtIn, ...compilePackCommands(ctx, reservedNouns)];
-}

package/src/pipeline/constants.ts

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

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

@@ -1,89 +0,0 @@
-import {
-  type CommandDefinition,
-  detectRenderMode,
-  formatHelp,
-  formatLlmHelp,
-  type HandleResultOptions,
-  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),
-  });
-
-  // Global flags (--llm, --format, --verbose) are pre-parsed by
-  // parseGlobalFlags() and stripped from argv before Commander sees it.
-  // Declaring them here keeps them visible in --help output.
-  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);
-  // Commander will never see these flags in argv (they're stripped),
-  // so enablePositionalOptions() scoping can't reject them.
-
-  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();
-    });
-
-  const mode = detectRenderMode(ctx.globalFlags);
-  const resultOptions: HandleResultOptions = {
-    mode,
-    renderInk:
-      mode === "ink"
-        ? async (element: unknown) => {
-            const { renderInk } = await import("#tui");
-            await renderInk(element as import("react").ReactElement);
-          }
-        : undefined,
-  };
-
-  registerAll(program, commands, ctx, resultOptions);
-
-  return program;
-}

package/src/pipeline/formatTerminal.test.ts

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

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

@@ -1,22 +0,0 @@
-/** @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,
-  stripGlobalFlags,
-} 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

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

@@ -1,12 +0,0 @@
-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.test.ts

@@ -1,92 +0,0 @@
-import { describe, expect, it } from "vitest";
-import parseGlobalFlags, { stripGlobalFlags } from "./parseGlobalFlags.js";
-
-describe("parseGlobalFlags", () => {
-  it("extracts --llm", () => {
-    const flags = parseGlobalFlags([
-      "node",
-      "pragma",
-      "block",
-      "list",
-      "--llm",
-    ]);
-    expect(flags.llm).toBe(true);
-  });
-
-  it("extracts --format json", () => {
-    const flags = parseGlobalFlags([
-      "node",
-      "pragma",
-      "--format",
-      "json",
-      "info",
-    ]);
-    expect(flags.format).toBe("json");
-  });
-
-  it("defaults to text when --format is absent", () => {
-    const flags = parseGlobalFlags(["node", "pragma", "info"]);
-    expect(flags.format).toBe("text");
-  });
-
-  it("extracts --verbose", () => {
-    const flags = parseGlobalFlags([
-      "node",
-      "pragma",
-      "--verbose",
-      "block",
-      "list",
-    ]);
-    expect(flags.verbose).toBe(true);
-  });
-});
-
-describe("stripGlobalFlags", () => {
-  it("removes --llm from any position", () => {
-    expect(
-      stripGlobalFlags(["node", "pragma", "--llm", "tier", "list"]),
-    ).toEqual(["node", "pragma", "tier", "list"]);
-    expect(
-      stripGlobalFlags(["node", "pragma", "tier", "list", "--llm"]),
-    ).toEqual(["node", "pragma", "tier", "list"]);
-  });
-
-  it("removes --format and its value", () => {
-    expect(
-      stripGlobalFlags(["node", "pragma", "--format", "json", "info"]),
-    ).toEqual(["node", "pragma", "info"]);
-    expect(
-      stripGlobalFlags(["node", "pragma", "info", "--format", "json"]),
-    ).toEqual(["node", "pragma", "info"]);
-  });
-
-  it("removes --verbose from any position", () => {
-    expect(
-      stripGlobalFlags(["node", "pragma", "block", "list", "--verbose"]),
-    ).toEqual(["node", "pragma", "block", "list"]);
-  });
-
-  it("removes all global flags at once", () => {
-    expect(
-      stripGlobalFlags([
-        "node",
-        "pragma",
-        "--llm",
-        "--verbose",
-        "--format",
-        "json",
-        "block",
-        "list",
-      ]),
-    ).toEqual(["node", "pragma", "block", "list"]);
-  });
-
-  it("preserves argv when no global flags present", () => {
-    expect(stripGlobalFlags(["node", "pragma", "block", "list"])).toEqual([
-      "node",
-      "pragma",
-      "block",
-      "list",
-    ]);
-  });
-});

package/src/pipeline/parseGlobalFlags.ts

@@ -1,46 +0,0 @@
-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"),
-  };
-}
-
-/**
- * Return a copy of argv with global flags stripped out.
- *
- * Since {@link parseGlobalFlags} pre-parses these flags before Commander
- * runs, we remove them so they don't collide with Commander's
- * `enablePositionalOptions()` scoping. This lets users place `--llm`,
- * `--format`, and `--verbose` anywhere in the command line.
- *
- * @param argv - Raw process.argv array.
- * @returns New array with global flags removed.
- */
-export function stripGlobalFlags(argv: readonly string[]): string[] {
-  const result: string[] = [];
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "--llm" || arg === "--verbose") continue;
-    if (arg === "--format") {
-      i += 1; // skip the value too
-      continue;
-    }
-    result.push(arg as string);
-  }
-  return result;
-}