@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/pipeline/collectCommands.test.ts

@@ -1,187 +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 {
-  deriveReservedVerbs,
-  isReserved,
-  nounVerbFromPath,
-  nounVerbFromToolName,
-} from "../domains/shared/stories/pack/index.js";
-import { TOKEN_READ_SURFACE_ENABLED } from "../domains/token/featureFlag.js";
-import { allSpecs } from "../mcp/tools/index.js";
-import createTestRuntime from "../testing/helpers/createTestRuntime.js";
-import collectCommands, { builtInCommands } 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");
-  });
-
-  // Golden surface: the full built-in command set, in emission order. The
-  // per-(noun, verb) reserved-guard flip must not add, drop, rename, or REORDER
-  // a single built-in command — order drives help output and registration.
-  // `tier list` and the whole `standard` noun are no longer here: the
-  // hand-written domains were deleted and are served by bundled story packs
-  // (asserted below).
-  it("has a stable built-in command surface", () => {
-    const paths = builtInCommands(makeCtx()).map((command) =>
-      command.path.join(" "),
-    );
-
-    expect(paths).toEqual([
-      "config tier",
-      "config channel",
-      "config trace",
-      "config framework",
-      "config show",
-      "create component",
-      "create package",
-      "create application",
-      "create domain",
-      "create route",
-      "create wrapper",
-      "setup",
-      "setup lsp",
-      "setup mcp",
-      "setup completions",
-      "setup skills",
-      "modifier list",
-      "modifier lookup",
-      "modifier sample",
-      ...(TOKEN_READ_SURFACE_ENABLED ? ["token list", "token lookup"] : []),
-      "tokens add-config",
-      ...(TOKEN_READ_SURFACE_ENABLED ? ["token sample"] : []),
-      "block list",
-      "block lookup",
-      "block sample",
-      "ontology list",
-      "ontology show",
-      "graph query",
-      "graph inspect",
-      "graphql build",
-      "graphql check",
-      "graphql serve",
-      "skill list",
-      "skill lookup",
-      "doctor",
-      "info",
-      "upgrade",
-      "llm",
-      "capabilities",
-    ]);
-  });
-
-  it("serves `tier list` from the bundled pack, not a built-in", () => {
-    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
-      c.path.join(" "),
-    );
-    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
-
-    expect(builtInPaths).not.toContain("tier list");
-    expect(allPaths).toContain("tier list");
-  });
-
-  it("serves the whole `standard` noun from the bundled pack", () => {
-    const builtInPaths = builtInCommands(makeCtx()).map((c) =>
-      c.path.join(" "),
-    );
-    const allPaths = collectCommands(makeCtx()).map((c) => c.path.join(" "));
-
-    const standardVerbs = [
-      "standard list",
-      "standard lookup",
-      "standard categories",
-      "standard sample",
-    ];
-    for (const path of standardVerbs) {
-      expect(builtInPaths).not.toContain(path);
-      expect(allPaths).toContain(path);
-    }
-  });
-});
-
-// Cross-surface skew invariant (FIX 2 / R4-F1): the CLI and MCP surfaces both
-// derive their reserved map through the single shared deriveReservedVerbs, so
-// they MUST agree on every leaf read (noun, verb) reservation. If they drifted,
-// a pack migrating a `list`/`lookup` verb could be admitted on one surface and
-// blocked on the other. Operational nouns legitimately differ (graphql/setup/
-// upgrade are CLI-only), so the invariant is scoped to the read verbs that
-// packs actually emit.
-describe("cross-surface reserved-verb parity", () => {
-  const READ_VERBS = ["list", "lookup"] as const;
-
-  it("CLI and MCP reserve the same list/lookup verbs for every leaf read noun", () => {
-    // Both surfaces derive reservations from BUILT-INS only (production reserves
-    // from built-ins, before appending packs), so a bundled/config/package pack
-    // never inflates the reserved map. Using collectCommands here would fold the
-    // bundled tier pack into the CLI side and break the symmetry.
-    const cliPairs = builtInCommands(makeCtx()).map((command) =>
-      nounVerbFromPath(command.path),
-    );
-    const mcpPairs = allSpecs.map((spec) => nounVerbFromToolName(spec.name));
-
-    const cliReserved = deriveReservedVerbs(cliPairs);
-    const mcpReserved = deriveReservedVerbs(mcpPairs);
-
-    // FIX 1 on the real CLI surface: operational nouns own no list/lookup, so
-    // they are reserved wholesale — a pack emitting `list` stays blocked.
-    for (const noun of ["config", "graph", "graphql", "setup", "create"]) {
-      expect(isReserved(cliReserved, noun, "list")).toBe(true);
-    }
-
-    // Leaf read nouns: those that own a `list`/`lookup` verb on either surface.
-    const readNouns = new Set(
-      [...cliPairs, ...mcpPairs]
-        .filter(([, verb]) => verb === "list" || verb === "lookup")
-        .map(([noun]) => noun),
-    );
-
-    // Sanity: the real leaf-migration targets are present, so this asserts
-    // something (a silently empty set would make the test vacuous). `tier`
-    // and `standard` are no longer here — both were cut over to bundled
-    // packs, so they are correctly absent from the built-in reserved
-    // surface on both sides. The token noun only owns read verbs while its
-    // feature flag is on.
-    const expectedReadNouns = ["block", "modifier"];
-    if (TOKEN_READ_SURFACE_ENABLED) expectedReadNouns.push("token");
-    for (const noun of expectedReadNouns) {
-      expect(readNouns.has(noun)).toBe(true);
-    }
-    expect(readNouns.has("standard")).toBe(false);
-
-    for (const noun of readNouns) {
-      for (const verb of READ_VERBS) {
-        expect(
-          isReserved(cliReserved, noun, verb),
-          `CLI/MCP disagree on ${noun} ${verb}`,
-        ).toBe(isReserved(mcpReserved, noun, verb));
-      }
-    }
-  });
-});

package/src/pipeline/collectCommands.ts

@@ -1,75 +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,
-  deriveReservedVerbs,
-  nounVerbFromPath,
-} from "../domains/shared/stories/pack/index.js";
-import { commands as skillCommands } from "../domains/skill/index.js";
-import { commands as tokenCommands } from "../domains/token/index.js";
-
-/**
- * The built-in (hand-written domain) command surface, in emission order.
- *
- * Excludes story-pack commands (bundled, config, or package). Exported so the
- * reserved-verb derivation and its tests share the exact input production uses
- * — the reserved map is built from built-ins only, never from packs.
- */
-export function builtInCommands(ctx: PragmaContext): CommandDefinition[] {
-  return [
-    ...configCommands(ctx),
-    ...createCommands(),
-    ...setupCommands(),
-    ...modifierCommands(ctx),
-    ...tokenCommands(ctx),
-    ...blockCommands(ctx),
-    ...ontologyCommands(ctx),
-    ...graphCommands(ctx),
-    ...graphqlCommands(),
-    ...skillCommands(ctx),
-    doctorCommand,
-    infoCommand,
-    upgradeCommand,
-    buildLlmCommand(ctx),
-    buildCapabilitiesCommand(),
-  ];
-}
-
-/**
- * Collect all CLI command definitions: built-in domains plus story packs.
- *
- * Extracted from runCli so the completions server can import the command list
- * independently without running the full CLI pipeline.
- *
- * Story packs (bundled transitional packs, plus config- and package-declared
- * stories) project onto the same surface. Leaf read nouns reserve only the
- * (noun, verb) pairs they own, so a pack can add a verb no built-in owns and,
- * once a built-in leaf is deleted, its bundled pack takes over the freed noun;
- * operational nouns (config, graph, setup, …) stay reserved wholesale.
- *
- * @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 = builtInCommands(ctx);
-  const reserved = deriveReservedVerbs(
-    builtIn.map((command) => nounVerbFromPath(command.path)),
-  );
-  return [...builtIn, ...compilePackCommands(ctx, reserved)];
-}

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,116 +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 });
-
-    // Assert on single-chalk-span strings so the check is robust whether or
-    // not color is enabled (CI renders with color; ANSI resets would otherwise
-    // split a multi-word phrase like "Usage: pragma").
-    expect(write).toHaveBeenCalledWith(
-      expect.stringContaining("For AI agents"),
-    );
-    expect(write).toHaveBeenCalledWith(expect.stringContaining("Global flags"));
-  });
-
-  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,
-  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";
-import formatRootHelp from "./rootHelp.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 formatRootHelp(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/firstRun.test.ts

@@ -1,80 +0,0 @@
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import ensureFirstRun from "./firstRun.js";
-
-let xdg: string;
-let savedXdg: string | undefined;
-let lines: string[];
-
-const write = (line: string) => {
-  lines.push(line);
-};
-
-beforeEach(() => {
-  savedXdg = process.env.XDG_CONFIG_HOME;
-  xdg = mkdtempSync(join(tmpdir(), "pragma-firstrun-"));
-  process.env.XDG_CONFIG_HOME = xdg;
-  lines = [];
-});
-
-afterEach(() => {
-  process.env.XDG_CONFIG_HOME = savedXdg;
-  rmSync(xdg, { recursive: true, force: true });
-});
-
-const configPath = () => join(xdg, "pragma", "config.json");
-
-describe("ensureFirstRun", () => {
-  it("creates the global config with defaults and greets on first run", async () => {
-    await ensureFirstRun(write);
-
-    expect(existsSync(configPath())).toBe(true);
-    expect(JSON.parse(readFileSync(configPath(), "utf-8"))).toEqual({});
-
-    const text = lines.join("\n");
-    expect(text).toContain("pre-release pragma CLI");
-    expect(text).toContain("github.com/canonical/pragma");
-    expect(text).toContain(configPath());
-    expect(text).toContain("pragma.config.json");
-  });
-
-  it("is silent and leaves the config untouched on subsequent runs", async () => {
-    await ensureFirstRun(write);
-    lines = [];
-
-    await ensureFirstRun(write);
-
-    expect(lines).toEqual([]);
-    expect(readFileSync(configPath(), "utf-8")).toBe("{}\n");
-  });
-
-  it("never overwrites an existing config", async () => {
-    await ensureFirstRun(write);
-    const custom = '{ "channel": "experimental" }\n';
-    const { writeFileSync } = await import("node:fs");
-    writeFileSync(configPath(), custom);
-    lines = [];
-
-    await ensureFirstRun(write);
-
-    expect(readFileSync(configPath(), "utf-8")).toBe(custom);
-    expect(lines).toEqual([]);
-  });
-
-  it("degrades to a warning instead of throwing when the config cannot be created", async () => {
-    // Point XDG at a path whose parent is a FILE, so mkdir must fail.
-    const blocker = join(xdg, "blocker");
-    const { writeFileSync } = await import("node:fs");
-    writeFileSync(blocker, "not a directory");
-    process.env.XDG_CONFIG_HOME = join(blocker, "nested");
-
-    await expect(ensureFirstRun(write)).resolves.toBeUndefined();
-    // Exactly one warning line and no welcome banner: creation is attempted
-    // before the greeting, so a failure degrades to a single stderr warning.
-    expect(lines).toHaveLength(1);
-    expect(lines[0]).toContain("could not create the global pragma config");
-    expect(lines.join("\n")).not.toContain("pre-release pragma CLI");
-  });
-});

package/src/pipeline/firstRun.ts

@@ -1,99 +0,0 @@
-/**
- * First-run onboarding — welcome note + global config creation.
- *
- * On the first invocation of pragma (detected by the absence of the global
- * config file), print a short welcome to stderr and create
- * `$XDG_CONFIG_HOME/pragma/config.json` with defaults. Modeled as a
- * {@link Task} so the effects (exists/mkdir/write/log) stay declarative and
- * testable, mirroring the config domain's write tasks.
- *
- * The banner goes to STDERR: stdout belongs to command output (`--format
- * json` consumers, MCP stdio), and the note must never corrupt it.
- */
-
-import { dirname } from "node:path";
-import {
-  $,
-  exists,
-  gen,
-  info,
-  mkdir,
-  type Task,
-  writeFile,
-} from "@canonical/task";
-import { runTask } from "@canonical/task/node";
-import { resolveGlobalConfigPath } from "../config/index.js";
-
-/**
- * Seed content for a fresh global config: an empty object, so every field
- * keeps its built-in default and `config show` reports honest provenance
- * (nothing is pinned that the user did not choose).
- */
-const SEED_CONFIG = "{}\n";
-
-/** Build the welcome note. The resolved path is shown so it is copyable. */
-function welcomeLines(path: string): string[] {
-  return [
-    "Hello! Thanks for taking the time to try the pre-release pragma CLI.",
-    "Please file issues, suggestions, and feedback at https://github.com/canonical/pragma/issues.",
-    `Pragma stores its configuration in ${path} (just created with defaults).`,
-    "A `pragma.config.json` in the current directory or any directory above it overrides it per project.",
-    "",
-  ];
-}
-
-/**
- * The first-run task: create the global config, announcing it on first run.
- *
- * @returns Task yielding whether the config was created and its path.
- * @note Impure — checks/creates the global config file, emits log effects.
- */
-export function firstRunTask(): Task<{ created: boolean; path: string }> {
-  return gen(function* () {
-    const path = resolveGlobalConfigPath();
-
-    if (yield* $(exists(path))) {
-      return { created: false, path };
-    }
-
-    // Create the config first, then greet: if creation fails the effects throw
-    // before any line is emitted, so onboarding degrades to the single stderr
-    // warning ensureFirstRun writes — never a "just created" banner alongside a
-    // failure. `mkdir` is recursive (its default), so a missing XDG parent is
-    // created rather than being treated as an error.
-    yield* $(mkdir(dirname(path), true));
-    yield* $(writeFile(path, SEED_CONFIG));
-
-    for (const line of welcomeLines(path)) {
-      yield* $(info(line));
-    }
-
-    return { created: true, path };
-  });
-}
-
-/**
- * Run the first-run task, tolerating every failure.
- *
- * Onboarding must never break the CLI: a read-only home, a weird XDG path,
- * or a race with a concurrent first run degrade to a single stderr warning
- * and the invocation proceeds normally (the config layers treat a missing
- * global file as defaults anyway).
- *
- * @param write - Stderr sink, injectable for tests.
- * @note Impure — filesystem effects + stderr.
- */
-export default async function ensureFirstRun(
-  write: (line: string) => void = (line) => process.stderr.write(`${line}\n`),
-): Promise<void> {
-  try {
-    await runTask(firstRunTask(), {
-      // Route log effects to stderr without the interpreter's [INFO] prefix —
-      // this is a greeting, not diagnostics.
-      onLog: (_level, message) => write(message),
-    });
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    write(`Warning: could not create the global pragma config — ${reason}`);
-  }
-}