@canonical/pragma-cli 0.31.0 → 0.33.0

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,193 +0,0 @@
-import { describe, expect, it } from "vitest";
-import parseGlobalFlags, {
-  readRawFormat,
-  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("accepts the --format=json equals form", () => {
-    const flags = parseGlobalFlags(["node", "pragma", "info", "--format=json"]);
-    expect(flags.format).toBe("json");
-  });
-
-  it("treats an unknown --format value as text", () => {
-    expect(
-      parseGlobalFlags(["node", "pragma", "info", "--format", "xml"]).format,
-    ).toBe("text");
-    expect(
-      parseGlobalFlags(["node", "pragma", "info", "--format=xml"]).format,
-    ).toBe("text");
-  });
-
-  it("extracts --verbose", () => {
-    const flags = parseGlobalFlags([
-      "node",
-      "pragma",
-      "--verbose",
-      "block",
-      "list",
-    ]);
-    expect(flags.verbose).toBe(true);
-  });
-
-  describe("auto-LLM detection", () => {
-    const tty = { isTty: true, noAutoLlm: false };
-    const piped = { isTty: false, noAutoLlm: false };
-
-    it("stays plain on an interactive terminal", () => {
-      expect(parseGlobalFlags(["node", "pragma", "info"], tty).llm).toBe(false);
-    });
-
-    it("defaults to llm when stdout is not a TTY, flagged as auto", () => {
-      const flags = parseGlobalFlags(["node", "pragma", "info"], piped);
-      expect(flags.llm).toBe(true);
-      expect(flags.autoLlm).toBe(true);
-    });
-
-    it("marks explicit --llm as not auto", () => {
-      const flags = parseGlobalFlags(
-        ["node", "pragma", "--llm", "info"],
-        piped,
-      );
-      expect(flags.llm).toBe(true);
-      expect(flags.autoLlm).toBe(false);
-    });
-
-    it("does not auto-enable llm when --format json is requested", () => {
-      expect(
-        parseGlobalFlags(["node", "pragma", "info", "--format", "json"], piped)
-          .llm,
-      ).toBe(false);
-    });
-
-    it("respects an explicit --llm even on a TTY", () => {
-      expect(
-        parseGlobalFlags(["node", "pragma", "--llm", "info"], tty).llm,
-      ).toBe(true);
-    });
-
-    it("honours PRAGMA_NO_AUTO_LLM to stay plain when piped", () => {
-      expect(
-        parseGlobalFlags(["node", "pragma", "info"], {
-          isTty: false,
-          noAutoLlm: true,
-        }).llm,
-      ).toBe(false);
-    });
-  });
-});
-
-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",
-    ]);
-  });
-
-  it("removes the equals form of every global flag", () => {
-    expect(
-      stripGlobalFlags([
-        "node",
-        "pragma",
-        "--llm=",
-        "--verbose=",
-        "--format=json",
-        "block",
-        "list",
-      ]),
-    ).toEqual(["node", "pragma", "block", "list"]);
-  });
-});
-
-describe("readRawFormat", () => {
-  it("reads the space form", () => {
-    expect(readRawFormat(["node", "pragma", "--format", "json"])).toBe("json");
-  });
-
-  it("reads the equals form", () => {
-    expect(readRawFormat(["node", "pragma", "--format=text"])).toBe("text");
-  });
-
-  it("returns undefined when --format is absent", () => {
-    expect(readRawFormat(["node", "pragma", "info"])).toBeUndefined();
-  });
-
-  it("returns an empty string for a bare --format at end of argv", () => {
-    // Not undefined — the caller must reject it rather than fall through to
-    // root help with exit code 0.
-    expect(readRawFormat(["node", "pragma", "--format"])).toBe("");
-  });
-
-  it("returns an empty string when --format is followed by another flag", () => {
-    expect(readRawFormat(["node", "pragma", "--format", "--llm"])).toBe("");
-  });
-});

package/src/pipeline/parseGlobalFlags.ts

@@ -1,135 +0,0 @@
-import type { GlobalFlags } from "@canonical/cli-core";
-
-/**
- * Read the value of a `--flag` that accepts both the space form
- * (`--flag value`) and the equals form (`--flag=value`).
- *
- * @param argv - Raw process.argv array.
- * @param flag - The flag name including leading dashes (e.g. `--format`).
- * @returns The flag's value, or undefined when the flag is absent.
- */
-function readFlagValue(
-  argv: readonly string[],
-  flag: string,
-): string | undefined {
-  const equalsPrefix = `${flag}=`;
-  const equalsArg = argv.find((arg) => arg.startsWith(equalsPrefix));
-  if (equalsArg !== undefined) {
-    return equalsArg.slice(equalsPrefix.length);
-  }
-  const spaceIndex = argv.indexOf(flag);
-  return spaceIndex === -1 ? undefined : argv[spaceIndex + 1];
-}
-
-/**
- * Read the raw `--format` value exactly as the user typed it (both space and
- * equals forms), for validation. Unlike {@link parseGlobalFlags}, this does not
- * coerce unknown values to `text` — the caller decides how to reject them.
- *
- * A bare `--format` with no following value (either at the end of argv or
- * immediately followed by another flag) is reported as an empty string rather
- * than `undefined`, so the caller rejects it as invalid input instead of
- * silently falling through to the root-help path with exit code 0.
- *
- * @param argv - Raw process.argv array.
- * @returns The raw format value, an empty string when `--format` is present
- *   without a value, or undefined when `--format` is absent.
- */
-export function readRawFormat(argv: readonly string[]): string | undefined {
-  const equalsArg = argv.find((arg) => arg.startsWith("--format="));
-  if (equalsArg !== undefined) return equalsArg.slice("--format=".length);
-
-  const spaceIndex = argv.indexOf("--format");
-  if (spaceIndex === -1) return undefined;
-
-  const value = argv[spaceIndex + 1];
-  // A missing value or another flag means the user gave no format at all.
-  return value !== undefined && !value.startsWith("-") ? value : "";
-}
-
-/**
- * Environment probe used to decide the auto-LLM default. Injectable so the
- * detection can be unit-tested without touching the real process.
- */
-export interface OutputEnvironment {
-  /** Whether stdout is attached to an interactive terminal. */
-  readonly isTty: boolean;
-  /** Whether the auto-LLM default is explicitly disabled. */
-  readonly noAutoLlm: boolean;
-}
-
-/** Read the real stdout/env output environment. @note Impure — reads process. */
-function readOutputEnvironment(): OutputEnvironment {
-  return {
-    isTty: process.stdout.isTTY === true,
-    noAutoLlm: Boolean(process.env.PRAGMA_NO_AUTO_LLM),
-  };
-}
-
-/**
- * Extract global flags (--llm, --format, --verbose) from raw argv.
- *
- * Performs simple scanning rather than full argument parsing so it can run
- * before Commander processes the command tree. Recognises both the space form
- * (`--format json`) and the equals form (`--format=json`).
- *
- * Auto-LLM: when no `--llm`/`--format` is given and stdout is not an
- * interactive terminal (piped or redirected — the shape an agent captures),
- * `llm` defaults to true so agents get condensed Markdown without passing a
- * flag. Interactive terminals stay in rich mode. `--llm`, `--format json`, and
- * `PRAGMA_NO_AUTO_LLM` all override this.
- *
- * @param argv - Raw process.argv array.
- * @param env - Output environment probe (defaults to the real process).
- * @returns Parsed global flags.
- * @note Impure by default — reads process.stdout/env unless `env` is injected.
- */
-export default function parseGlobalFlags(
-  argv: readonly string[],
-  env: OutputEnvironment = readOutputEnvironment(),
-): GlobalFlags {
-  const explicitLlm = argv.includes("--llm");
-  const format = readFlagValue(argv, "--format") === "json" ? "json" : "text";
-  const formatRequested = readFlagValue(argv, "--format") !== undefined;
-  const autoLlm =
-    !explicitLlm && !formatRequested && !env.isTty && !env.noAutoLlm;
-  return {
-    llm: explicitLlm || autoLlm,
-    autoLlm,
-    format,
-    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;
-    // Equals form (`--format=json`, `--llm=…`) is a single token — drop it.
-    if (
-      arg?.startsWith("--format=") ||
-      arg?.startsWith("--llm=") ||
-      arg?.startsWith("--verbose=")
-    ) {
-      continue;
-    }
-    if (arg === "--format") {
-      i += 1; // skip the space-form value too
-      continue;
-    }
-    result.push(arg as string);
-  }
-  return result;
-}

package/src/pipeline/renderError.test.ts

@@ -1,151 +0,0 @@
-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();
-  });
-});