@canonical/pragma-cli 0.18.0

package/src/pipeline/renderError.ts

@@ -0,0 +1,114 @@
+/**
+ * Error rendering functions for different output surfaces.
+ *
+ * Each renderer takes a PragmaError and produces a formatted string
+ * suitable for its target: human-readable plain text, LLM-oriented
+ * Markdown, or machine-readable JSON.
+ */
+
+import type { PragmaError } from "../error/index.js";
+
+/**
+ * Render a PragmaError as human-readable plain text for terminal output.
+ *
+ * Includes suggestions, active filters, valid options, and recovery hints
+ * when present.
+ *
+ * @param error - The structured error to render.
+ * @returns Multi-line plain text string.
+ */
+function renderErrorPlain(error: PragmaError): string {
+  const lines: string[] = [];
+
+  lines.push(`Error: ${error.message}`);
+
+  if (error.suggestions.length > 0) {
+    lines.push("");
+    lines.push("Did you mean?");
+    for (const s of error.suggestions) {
+      lines.push(`  - ${s}`);
+    }
+  }
+
+  if (error.filters) {
+    lines.push("");
+    lines.push("Active filters:");
+    for (const [key, value] of Object.entries(error.filters)) {
+      lines.push(`  ${key}: ${value}`);
+    }
+  }
+
+  if (error.validOptions && error.validOptions.length > 0) {
+    lines.push("");
+    lines.push(`Valid options: ${error.validOptions.join(", ")}`);
+  }
+
+  if (error.recovery) {
+    lines.push("");
+    if (error.recovery.cli) {
+      lines.push(`Run \`${error.recovery.cli}\``);
+    } else {
+      lines.push(error.recovery.message);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Render a PragmaError as condensed Markdown for LLM consumption.
+ *
+ * @param error - The structured error to render.
+ * @returns Markdown-formatted string.
+ */
+function renderErrorLlm(error: PragmaError): string {
+  const lines: string[] = [];
+
+  lines.push(`## Error: ${error.code}`);
+  lines.push(error.message);
+
+  if (error.suggestions.length > 0) {
+    lines.push(`Suggestions: ${error.suggestions.join(", ")}`);
+  }
+
+  if (error.filters) {
+    const filterParts = Object.entries(error.filters)
+      .map(([k, v]) => `${k}=${v}`)
+      .join(", ");
+    lines.push(`Filters: ${filterParts}`);
+  }
+
+  if (error.validOptions && error.validOptions.length > 0) {
+    lines.push(`Valid options: ${error.validOptions.join(", ")}`);
+  }
+
+  if (error.recovery) {
+    if (error.recovery.cli) {
+      lines.push(`Recovery: \`${error.recovery.cli}\``);
+    } else {
+      lines.push(`Recovery: ${error.recovery.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Render a PragmaError as a JSON string for machine consumption.
+ *
+ * @param error - The structured error to render.
+ * @returns JSON-serialized string of the error payload.
+ */
+function renderErrorJson(error: PragmaError): string {
+  return JSON.stringify({
+    code: error.code,
+    message: error.message,
+    entity: error.entity,
+    suggestions: error.suggestions,
+    recovery: error.recovery,
+    filters: error.filters,
+    validOptions: error.validOptions,
+  });
+}
+
+export { renderErrorJson, renderErrorLlm, renderErrorPlain };

package/src/pipeline/resolveCommandKind.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import resolveCommandKind from "./resolveCommandKind.js";
+
+describe("resolveCommandKind", () => {
+  it("detects completions-client from --completions flag", () => {
+    const result = resolveCommandKind([
+      "node",
+      "pragma",
+      "--completions",
+      "component",
+      "li",
+    ]);
+    expect(result).toEqual({
+      kind: "completions-client",
+      partial: "component li",
+    });
+  });
+
+  it("detects completions-server from _completions-server command", () => {
+    const result = resolveCommandKind([
+      "node",
+      "pragma",
+      "_completions-server",
+    ]);
+    expect(result).toEqual({ kind: "completions-server" });
+  });
+
+  it("detects doctor command", () => {
+    const result = resolveCommandKind(["node", "pragma", "doctor"]);
+    expect(result).toEqual({ kind: "doctor" });
+  });
+
+  it("detects store-skip for setup", () => {
+    const result = resolveCommandKind(["node", "pragma", "setup"]);
+    expect(result).toEqual({ kind: "store-skip", command: "setup" });
+  });
+
+  it("detects store-skip for mcp", () => {
+    const result = resolveCommandKind(["node", "pragma", "mcp"]);
+    expect(result).toEqual({ kind: "store-skip", command: "mcp" });
+  });
+
+  it("defaults to store-required for regular commands", () => {
+    const result = resolveCommandKind(["node", "pragma", "component", "list"]);
+    expect(result).toEqual({ kind: "store-required" });
+  });
+
+  it("defaults to store-required when no command given", () => {
+    const result = resolveCommandKind(["node", "pragma"]);
+    expect(result).toEqual({ kind: "store-required" });
+  });
+
+  it("skips flags when finding command argument", () => {
+    const result = resolveCommandKind(["node", "pragma", "--llm", "doctor"]);
+    expect(result).toEqual({ kind: "doctor" });
+  });
+
+  it("skips the --format value when finding the command argument", () => {
+    const result = resolveCommandKind([
+      "node",
+      "pragma",
+      "--format",
+      "json",
+      "doctor",
+    ]);
+    expect(result).toEqual({ kind: "doctor" });
+  });
+});

package/src/pipeline/resolveCommandKind.ts

@@ -0,0 +1,71 @@
+/**
+ * Classify the CLI invocation into a command kind.
+ *
+ * Determines which pipeline path to take before any store boot occurs.
+ * Store-skip commands are listed declaratively in STORE_SKIP_COMMANDS.
+ */
+
+import type { CommandKind } from "./types.js";
+
+/** Commands that do not require the ke store to be booted. */
+const STORE_SKIP_COMMANDS = new Set(["setup", "mcp"]);
+
+function findCommandArg(argv: readonly string[]): string | undefined {
+  const args = argv.slice(2);
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg) continue;
+
+    if (arg === "--format") {
+      i += 1;
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      continue;
+    }
+
+    return arg;
+  }
+
+  return undefined;
+}
+
+/**
+ * Classify the CLI invocation into a {@link CommandKind} discriminated union.
+ *
+ * Runs before any store boot to decide the pipeline path.
+ *
+ * @param argv - Raw process.argv array.
+ * @returns Discriminated union indicating the command category.
+ */
+export default function resolveCommandKind(
+  argv: readonly string[],
+): CommandKind {
+  // Completions client — intercept before anything else.
+  const completionsIdx = argv.indexOf("--completions");
+  if (completionsIdx !== -1) {
+    const partial = argv.slice(completionsIdx + 1).join(" ");
+    return { kind: "completions-client", partial };
+  }
+
+  const commandArg = findCommandArg(argv);
+
+  // Completions server — boots its own store with cache.
+  if (commandArg === "_completions-server") {
+    return { kind: "completions-server" };
+  }
+
+  // Doctor runs before store boot — it validates the environment itself.
+  if (commandArg === "doctor") {
+    return { kind: "doctor" };
+  }
+
+  // Store-skip commands (setup, mcp) don't need the ke store.
+  if (commandArg && STORE_SKIP_COMMANDS.has(commandArg)) {
+    return { kind: "store-skip", command: commandArg };
+  }
+
+  return { kind: "store-required" };
+}

package/src/pipeline/runCli.orchestration.test.ts

@@ -0,0 +1,418 @@
+import type { CommandDefinition } from "@canonical/cli-core";
+import { CommanderError } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PragmaError } from "../error/index.js";
+
+const bootPragmaMock = vi.fn();
+const collectCommandsMock = vi.fn();
+const createProgramMock = vi.fn();
+const mapExitCodeMock = vi.fn();
+const parseGlobalFlagsMock = vi.fn();
+const resolveCommandKindMock = vi.fn();
+const setupCommandsMock = vi.fn();
+const queryCompletionsMock = vi.fn();
+const startCompletionsServerMock = vi.fn();
+const doctorExecuteMock = vi.fn();
+
+vi.mock("../domains/shared/runtime.js", () => ({
+  bootPragma: bootPragmaMock,
+}));
+
+vi.mock("./collectCommands.js", () => ({
+  default: collectCommandsMock,
+}));
+
+vi.mock("./createProgram.js", () => ({
+  default: createProgramMock,
+}));
+
+vi.mock("./mapExitCode.js", () => ({
+  default: mapExitCodeMock,
+}));
+
+vi.mock("./parseGlobalFlags.js", () => ({
+  default: parseGlobalFlagsMock,
+}));
+
+vi.mock("./resolveCommandKind.js", () => ({
+  default: resolveCommandKindMock,
+}));
+
+vi.mock("../domains/setup/index.js", () => ({
+  commands: setupCommandsMock,
+}));
+
+vi.mock("../completions/queryCompletions.js", () => ({
+  default: queryCompletionsMock,
+}));
+
+vi.mock("../completions/startCompletionsServer.js", () => ({
+  default: startCompletionsServerMock,
+}));
+
+vi.mock("../domains/doctor/commands/index.js", () => ({
+  doctorCommand: {
+    execute: doctorExecuteMock,
+  },
+}));
+
+describe("runCli orchestration", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    process.exitCode = undefined;
+    parseGlobalFlagsMock.mockReturnValue({
+      llm: false,
+      format: "text",
+      verbose: false,
+    });
+    mapExitCodeMock.mockReturnValue(17);
+  });
+
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  it("boots, parses, and disposes for store-required commands", async () => {
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => undefined);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "list"]);
+
+    expect(bootPragmaMock).toHaveBeenCalledTimes(1);
+    expect(collectCommandsMock).toHaveBeenCalledTimes(1);
+    expect(createProgramMock).toHaveBeenCalledTimes(1);
+    expect(parseAsync).toHaveBeenCalledWith([
+      "node",
+      "pragma",
+      "block",
+      "list",
+    ]);
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows root help when no command is given", async () => {
+    const parseAsync = vi.fn(async () => undefined);
+
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "--verbose"]);
+
+    expect(resolveCommandKindMock).not.toHaveBeenCalled();
+    expect(bootPragmaMock).not.toHaveBeenCalled();
+    expect(parseAsync).toHaveBeenCalledWith(["node", "pragma", "--help"]);
+  });
+
+  it("renders boot errors and maps exit code", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    bootPragmaMock.mockRejectedValue(PragmaError.storeError("boom"));
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "list"]);
+
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(17);
+
+    stderrSpy.mockRestore();
+  });
+
+  it("handles completions client early-exit", async () => {
+    resolveCommandKindMock.mockReturnValue({
+      kind: "completions-client",
+      partial: "blo",
+    });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "_complete", "blo"]);
+
+    expect(queryCompletionsMock).toHaveBeenCalledWith("blo");
+    expect(bootPragmaMock).not.toHaveBeenCalled();
+  });
+
+  it("handles completions server early-exit", async () => {
+    resolveCommandKindMock.mockReturnValue({ kind: "completions-server" });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "_completions-server"]);
+
+    expect(startCompletionsServerMock).toHaveBeenCalledTimes(1);
+    expect(bootPragmaMock).not.toHaveBeenCalled();
+  });
+
+  it("handles doctor early-exit", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "doctor" });
+    doctorExecuteMock.mockResolvedValue({
+      tag: "output",
+      value: { checks: [] },
+      render: { plain: () => "doctor ok" },
+    });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "doctor"]);
+
+    expect(doctorExecuteMock).toHaveBeenCalledTimes(1);
+    expect(stdoutSpy).toHaveBeenCalledWith("doctor ok\n");
+
+    stdoutSpy.mockRestore();
+  });
+
+  it("skips stdout when doctor returns a non-output result", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "doctor" });
+    doctorExecuteMock.mockResolvedValue({ tag: "exit", code: 0 });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "doctor"]);
+
+    expect(stdoutSpy).not.toHaveBeenCalled();
+
+    stdoutSpy.mockRestore();
+  });
+
+  it("runs store-skip commands without booting the store", async () => {
+    const parseAsync = vi.fn(async () => undefined);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-skip" });
+    setupCommandsMock.mockReturnValue([{ path: ["setup", "skills"] }]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "setup", "skills"]);
+
+    expect(bootPragmaMock).not.toHaveBeenCalled();
+    expect(setupCommandsMock).toHaveBeenCalledTimes(1);
+    expect(parseAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it("maps Commander errors from the program", async () => {
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => {
+      throw new CommanderError(3, "commander.unknownCommand", "bad command");
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "bad"]);
+
+    expect(process.exitCode).toBe(3);
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats help-displayed commander errors as success", async () => {
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => {
+      throw new CommanderError(0, "commander.helpDisplayed", "help");
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "--help"]);
+
+    expect(process.exitCode).toBe(0);
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("treats version commander errors as success", async () => {
+    const parseAsync = vi.fn(async () => {
+      throw new CommanderError(0, "commander.version", "version");
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-skip" });
+    setupCommandsMock.mockReturnValue([{ path: ["setup", "skills"] }]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "--version"]);
+
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("renders pragma errors from the program using mapped exit codes", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => {
+      throw PragmaError.invalidInput("tier", "bad value");
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    parseGlobalFlagsMock.mockReturnValue({
+      llm: true,
+      format: "text",
+      verbose: false,
+    });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "get"]);
+
+    expect(mapExitCodeMock).toHaveBeenCalledWith("INVALID_INPUT");
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(17);
+
+    stderrSpy.mockRestore();
+  });
+
+  it("wraps unknown program errors and exits 127", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => {
+      throw new Error("kaboom");
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    parseGlobalFlagsMock.mockReturnValue({
+      llm: false,
+      format: "json",
+      verbose: false,
+    });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "get"]);
+
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(127);
+    expect(dispose).toHaveBeenCalledTimes(1);
+
+    stderrSpy.mockRestore();
+  });
+
+  it("renders boot errors in json mode", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    parseGlobalFlagsMock.mockReturnValue({
+      llm: false,
+      format: "json",
+      verbose: false,
+    });
+    bootPragmaMock.mockRejectedValue(PragmaError.storeError("boom"));
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "list"]);
+
+    expect(stderrSpy).toHaveBeenCalledWith(expect.stringContaining('"code"'));
+    expect(process.exitCode).toBe(17);
+
+    stderrSpy.mockRestore();
+  });
+
+  it("wraps non-pragma boot failures in a store error", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    parseGlobalFlagsMock.mockReturnValue({
+      llm: false,
+      format: "text",
+      verbose: false,
+    });
+    bootPragmaMock.mockRejectedValue("boot exploded");
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "list"]);
+
+    expect(mapExitCodeMock).toHaveBeenCalledWith("STORE_ERROR");
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(17);
+
+    stderrSpy.mockRestore();
+  });
+
+  it("wraps non-error thrown values from the program and exits 127", async () => {
+    const stderrSpy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const dispose = vi.fn();
+    const runtime = {
+      store: {},
+      config: { tier: undefined, channel: "normal" },
+      cwd: "/tmp",
+      dispose,
+    };
+    const parseAsync = vi.fn(async () => {
+      throw "kaboom";
+    });
+
+    resolveCommandKindMock.mockReturnValue({ kind: "store-required" });
+    bootPragmaMock.mockResolvedValue(runtime);
+    collectCommandsMock.mockReturnValue([] as CommandDefinition[]);
+    createProgramMock.mockReturnValue({ parseAsync });
+
+    const { default: runCli } = await import("./runCli.js");
+    await runCli(["node", "pragma", "block", "get"]);
+
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exitCode).toBe(127);
+    expect(dispose).toHaveBeenCalledTimes(1);
+
+    stderrSpy.mockRestore();
+  });
+});