@canonical/pragma-cli 0.31.0 → 0.32.0

package/src/pipeline/renderError.ts

@@ -1,129 +0,0 @@
-/**
- * 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.crossDomain) {
-    lines.push("");
-    lines.push(
-      `"${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}.`,
-    );
-    lines.push(`Run \`${error.crossDomain.cli}\``);
-  }
-
-  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.crossDomain) {
-    lines.push(
-      `Cross-domain: "${error.entity?.name ?? ""}" exists as a ${error.crossDomain.entityType}. \`${error.crossDomain.cli}\``,
-    );
-  }
-
-  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,
-    crossDomain: error.crossDomain,
-    filters: error.filters,
-    validOptions: error.validOptions,
-  });
-}
-
-export { renderErrorJson, renderErrorLlm, renderErrorPlain };

package/src/pipeline/resolveCommandKind.test.ts

@@ -1,80 +0,0 @@
-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("detects store-skip for create (pure scaffolding, no store)", () => {
-    const result = resolveCommandKind([
-      "node",
-      "pragma",
-      "create",
-      "component",
-      "react",
-      "Accordion2",
-    ]);
-    expect(result).toEqual({ kind: "store-skip", command: "create" });
-  });
-
-  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

@@ -1,82 +0,0 @@
-/**
- * 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",
-  "update-refs",
-  "capabilities",
-  "trace",
-  "graphql",
-  // `create` is pure scaffolding (summon generators) — it never queries the
-  // design-system graph, so booting the shared store just couples it to the
-  // installed packages and makes it fail when they are missing or malformed.
-  "create",
-]);
-
-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/rootHelp.test.ts

@@ -1,87 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import { describe, expect, it } from "vitest";
-import formatRootHelp from "./rootHelp.js";
-
-/** Minimal command stub — only the fields the help renderer reads. */
-function cmd(
-  path: string[],
-  extra: Partial<CommandDefinition> = {},
-): CommandDefinition {
-  return {
-    path,
-    description: `${path.join(" ")} description`,
-    parameters: [],
-    execute: async () => ({ tag: "output" }) as never,
-    ...extra,
-  };
-}
-
-const commands: CommandDefinition[] = [
-  cmd(["block", "list"]),
-  cmd(["token", "list"]),
-  cmd(["create", "component"], {
-    parameters: [
-      {
-        name: "framework",
-        description: "Component framework",
-        type: "select",
-        positional: true,
-        required: true,
-        choices: [
-          { label: "react", value: "react" },
-          { label: "svelte", value: "svelte" },
-          { label: "lit", value: "lit" },
-        ],
-      },
-    ],
-  }),
-  cmd(["create", "package"]),
-  cmd(["doctor"]),
-  cmd(["mystery", "verb"], { description: "an uncatalogued thing" }),
-];
-
-describe("formatRootHelp", () => {
-  const out = formatRootHelp("pragma", "Design system CLI", commands);
-
-  it("groups nouns under task-oriented headings instead of a flat list", () => {
-    expect(out).toContain("Explore the design system");
-    expect(out).toContain("Generate code");
-    expect(out).toContain("Set up & maintain");
-  });
-
-  it("gives real summaries, never the `<noun> commands` placeholder", () => {
-    expect(out).toContain("Look up design tokens and their values");
-    expect(out).not.toContain("block commands");
-    expect(out).not.toContain("token commands");
-  });
-
-  it("expands create with its subtypes and derived frameworks", () => {
-    expect(out).toContain("component");
-    expect(out).toContain("react · svelte · lit");
-    expect(out).toContain("package");
-  });
-
-  it("surfaces uncatalogued nouns under Other instead of dropping them", () => {
-    expect(out).toContain("Other");
-    expect(out).toContain("mystery");
-    expect(out).toContain("an uncatalogued thing");
-  });
-
-  it("always lists the mcp server command even without a definition", () => {
-    const withoutMcp = commands.filter((c) => c.path[0] !== "mcp");
-    const rendered = formatRootHelp("pragma", "d", withoutMcp);
-    expect(rendered).toContain("mcp");
-    expect(rendered).toContain("Start the MCP server over stdio");
-  });
-
-  it("hides nouns that are catalogued but not registered", () => {
-    // `standard` is catalogued but absent from this command set.
-    expect(out).not.toContain("Browse code standards");
-  });
-
-  it("lists the global flags and an orientation hint", () => {
-    expect(out).toContain("Global flags");
-    expect(out).toContain("--format json");
-    expect(out).toContain("pragma capabilities");
-  });
-});

package/src/pipeline/rootHelp.ts

@@ -1,265 +0,0 @@
-/**
- * Curated root `--help` for `pragma`.
- *
- * cli-core's generic `formatHelp` derives a description per top-level noun from
- * its commands, but noun groups that only have verbs (e.g. `block list`) have
- * no command to carry one — so it emits placeholder text like "block commands".
- * The root help is also the CLI's front door, so its content and grouping are
- * worth hand-curating here rather than auto-generating.
- *
- * This renderer:
- * - groups nouns into task-oriented sections with real one-line summaries,
- * - derives each section's live nouns from the registered commands (so a noun
- *   that disappears is dropped, and a new, uncatalogued one still shows up
- *   under "Other" instead of vanishing),
- * - expands `create` to show its scaffolding subtypes, including the component
- *   frameworks pulled straight from the command's parameter choices.
- */
-
-import type { CommandDefinition } from "@canonical/cli-core";
-import chalk from "chalk";
-
-interface NounSummary {
-  readonly noun: string;
-  readonly summary: string;
-}
-
-interface HelpGroup {
-  readonly title: string;
-  readonly nouns: readonly NounSummary[];
-}
-
-/**
- * Task-oriented grouping with curated summaries. Order is intentional: the
- * things people reach for most (exploring the system, generating code) come
- * first; agent/integration tooling comes last.
- */
-const HELP_GROUPS: readonly HelpGroup[] = [
-  {
-    title: "Explore the design system",
-    nouns: [
-      {
-        noun: "block",
-        summary: "Inspect components & patterns and their anatomy",
-      },
-      { noun: "token", summary: "Look up design tokens and their values" },
-      { noun: "modifier", summary: "Inspect modifiers and modifier families" },
-      { noun: "standard", summary: "Browse code standards and categories" },
-      {
-        noun: "ontology",
-        summary: "Explore the loaded ontologies (classes, properties)",
-      },
-      { noun: "tier", summary: "List the design-system tiers" },
-    ],
-  },
-  {
-    title: "Generate code",
-    nouns: [
-      { noun: "create", summary: "Scaffold components, packages, and apps" },
-    ],
-  },
-  {
-    title: "Query & serve the graph",
-    nouns: [
-      {
-        noun: "graph",
-        summary: "Run SPARQL queries or inspect a URI directly",
-      },
-      {
-        noun: "graphql",
-        summary: "Compile and serve a GraphQL API over the ontologies",
-      },
-    ],
-  },
-  {
-    title: "Set up & maintain",
-    nouns: [
-      { noun: "doctor", summary: "Check environment health" },
-      {
-        noun: "setup",
-        summary: "Configure MCP, skills, completions, and the LSP",
-      },
-      { noun: "config", summary: "Read and write pragma.config.json" },
-      { noun: "tokens", summary: "Generate a Terrazzo tokens config" },
-      {
-        noun: "info",
-        summary: "Show version, config, update status, and store summary",
-      },
-      {
-        noun: "upgrade",
-        summary: "Upgrade the pragma CLI to the latest version",
-      },
-    ],
-  },
-  {
-    title: "For AI agents",
-    nouns: [
-      {
-        noun: "capabilities",
-        summary: "Discover conventions, tools, and the discovery sequence",
-      },
-      {
-        noun: "llm",
-        summary: "LLM orientation: context, decision trees, command reference",
-      },
-      { noun: "mcp", summary: "Start the MCP server over stdio" },
-      {
-        noun: "skill",
-        summary: "Browse agent skills from design-system packages",
-      },
-    ],
-  },
-];
-
-/** All distinct top-level nouns present in the registered commands. */
-function nounsFrom(commands: readonly CommandDefinition[]): Set<string> {
-  const nouns = new Set<string>();
-  for (const cmd of commands) {
-    const noun = cmd.path[0];
-    if (noun) nouns.add(noun);
-  }
-  return nouns;
-}
-
-/** The verbs (second path segment) registered under a noun, in order. */
-function verbsOf(
-  noun: string,
-  commands: readonly CommandDefinition[],
-): CommandDefinition[] {
-  return commands.filter((c) => c.path[0] === noun && c.path.length > 1);
-}
-
-/**
- * The framework values offered by `create component`, e.g. `react · svelte ·
- * lit`, read from the command's `framework` parameter choices so the help
- * can never drift from what the generator actually accepts.
- */
-function componentFrameworks(
-  commands: readonly CommandDefinition[],
-): string | undefined {
-  const component = commands.find(
-    (c) => c.path[0] === "create" && c.path[1] === "component",
-  );
-  const choices = component?.parameters.find(
-    (p) => p.name === "framework",
-  )?.choices;
-  if (!choices || choices.length === 0) return undefined;
-  return choices.map((c) => c.label).join(" · ");
-}
-
-/** Render the `create` subtypes as indented sub-lines. */
-function createSubtypes(
-  commands: readonly CommandDefinition[],
-  subWidth: number,
-): string[] {
-  const lines: string[] = [];
-  const frameworks = componentFrameworks(commands);
-  for (const verb of verbsOf("create", commands)) {
-    const name = verb.path[1] as string;
-    const note =
-      name === "component" && frameworks
-        ? frameworks
-        : name === "package"
-          ? "a new package for the monorepo"
-          : verb.description;
-    lines.push(
-      `      ${chalk.dim("·")} ${chalk.cyan(name.padEnd(subWidth))}  ${chalk.dim(note)}`,
-    );
-  }
-  return lines;
-}
-
-/**
- * Build the curated root help string.
- *
- * @param programName - The CLI binary name (`pragma`).
- * @param description - The program description shown in the header.
- * @param commands - All registered command definitions.
- * @returns The formatted, colorized help text.
- */
-export default function formatRootHelp(
-  programName: string,
-  description: string,
-  commands: readonly CommandDefinition[],
-): string {
-  const present = nounsFrom(commands);
-  // `mcp` is attached to Commander directly (not via the command list), but is
-  // always available — surface it so the front door is complete.
-  present.add("mcp");
-  const catalogued = new Set(
-    HELP_GROUPS.flatMap((g) => g.nouns.map((n) => n.noun)),
-  );
-
-  // Any live noun we didn't curate is surfaced so nothing silently disappears.
-  const uncatalogued = [...present].filter((n) => !catalogued.has(n)).sort();
-  const groups: HelpGroup[] = [
-    ...HELP_GROUPS.map((g) => ({
-      ...g,
-      nouns: g.nouns.filter((n) => present.has(n.noun)),
-    })),
-    ...(uncatalogued.length > 0
-      ? [
-          {
-            title: "Other",
-            nouns: uncatalogued.map((noun) => ({
-              noun,
-              summary:
-                verbsOf(noun, commands)[0]?.description ?? `${noun} commands`,
-            })),
-          },
-        ]
-      : []),
-  ].filter((g) => g.nouns.length > 0);
-
-  // One shared column width so summaries line up across every group.
-  const nounWidth = Math.max(
-    ...groups.flatMap((g) => g.nouns.map((n) => n.noun.length)),
-    0,
-  );
-  const subWidth = Math.max(
-    ...verbsOf("create", commands).map((v) => (v.path[1] as string).length),
-    0,
-  );
-
-  const lines: string[] = [
-    `${chalk.bold(programName)} — ${description}`,
-    "",
-    `${chalk.dim("Usage:")} ${programName} ${chalk.cyan("<command>")} ${chalk.dim("[subcommand] [flags]")}`,
-    "",
-  ];
-
-  for (const group of groups) {
-    lines.push(chalk.bold(group.title));
-    for (const { noun, summary } of group.nouns) {
-      lines.push(
-        `  ${chalk.cyan(noun.padEnd(nounWidth))}  ${chalk.dim(summary)}`,
-      );
-      if (noun === "create") {
-        lines.push(...createSubtypes(commands, subWidth));
-      }
-    }
-    lines.push("");
-  }
-
-  lines.push(chalk.bold("Global flags"));
-  const flags: [string, string][] = [
-    ["--llm", "Condensed Markdown output for agents"],
-    ["--format json", "Machine-readable JSON output"],
-    ["--verbose", "Diagnostic output on stderr"],
-    ["--help", "Show help (works on any command)"],
-    ["--version", "Show the CLI version"],
-  ];
-  const flagWidth = Math.max(...flags.map(([f]) => f.length));
-  for (const [flag, desc] of flags) {
-    lines.push(`  ${chalk.cyan(flag.padEnd(flagWidth))}  ${chalk.dim(desc)}`);
-  }
-  lines.push("");
-
-  lines.push(
-    chalk.dim(
-      `Run \`${programName} <command> --help\` for details, or \`${programName} capabilities\` to get oriented.`,
-    ),
-  );
-
-  return lines.join("\n");
-}