@canonical/pragma-cli 0.18.0

package/src/pipeline/runCli.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { VERSION } from "../constants.js";
+import createProgram from "./createProgram.js";
+import parseGlobalFlags from "./parseGlobalFlags.js";
+
+describe("parseGlobalFlags", () => {
+  it("parses defaults", () => {
+    const flags = parseGlobalFlags(["node", "pragma"]);
+    expect(flags).toEqual({ llm: false, format: "text", verbose: false });
+  });
+
+  it("parses --llm", () => {
+    const flags = parseGlobalFlags(["node", "pragma", "--llm"]);
+    expect(flags.llm).toBe(true);
+  });
+
+  it("parses --format json", () => {
+    const flags = parseGlobalFlags(["node", "pragma", "--format", "json"]);
+    expect(flags.format).toBe("json");
+  });
+
+  it("parses --verbose", () => {
+    const flags = parseGlobalFlags(["node", "pragma", "--verbose"]);
+    expect(flags.verbose).toBe(true);
+  });
+
+  it("parses all flags together", () => {
+    const flags = parseGlobalFlags([
+      "node",
+      "pragma",
+      "--llm",
+      "--format",
+      "json",
+      "--verbose",
+    ]);
+    expect(flags).toEqual({ llm: true, format: "json", verbose: true });
+  });
+});
+
+describe("createProgram", () => {
+  it("creates a Commander program named pragma", () => {
+    const ctx = {
+      cwd: "/tmp",
+      globalFlags: { llm: false, format: "text" as const, verbose: false },
+    };
+    const program = createProgram([], ctx);
+    expect(program.name()).toBe("pragma");
+  });
+
+  it("has version set", () => {
+    const ctx = {
+      cwd: "/tmp",
+      globalFlags: { llm: false, format: "text" as const, verbose: false },
+    };
+    const program = createProgram([], ctx);
+    expect(program.version()).toBe(VERSION);
+  });
+
+  it("has global flags registered", () => {
+    const ctx = {
+      cwd: "/tmp",
+      globalFlags: { llm: false, format: "text" as const, verbose: false },
+    };
+    const program = createProgram([], ctx);
+    const optionNames = program.options.map((o) => o.long);
+    expect(optionNames).toContain("--llm");
+    expect(optionNames).toContain("--format");
+    expect(optionNames).toContain("--verbose");
+  });
+});

package/src/pipeline/runCli.ts

@@ -0,0 +1,215 @@
+import type { GlobalFlags } from "@canonical/cli-core";
+import { CommanderError } from "commander";
+import { commands as setupCommands } from "../domains/setup/index.js";
+import type { PragmaContext } from "../domains/shared/context.js";
+import type { PragmaRuntime } from "../domains/shared/runtime.js";
+import { bootPragma } from "../domains/shared/runtime.js";
+import { PragmaError } from "../error/index.js";
+import collectCommands from "./collectCommands.js";
+import createProgram from "./createProgram.js";
+import mapExitCode from "./mapExitCode.js";
+import parseGlobalFlags from "./parseGlobalFlags.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "./renderError.js";
+import resolveCommandKind from "./resolveCommandKind.js";
+
+function hasCommandArg(argv: readonly string[]): boolean {
+  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 true;
+  }
+
+  return false;
+}
+
+// — Helpers ———————————————————————————————————————————————————————————————————
+
+function renderError(error: PragmaError, flags: GlobalFlags): string {
+  if (flags.format === "json") return renderErrorJson(error);
+  if (flags.llm) return renderErrorLlm(error);
+  return renderErrorPlain(error);
+}
+
+// — Stage 3: Handle early-exit command kinds ——————————————————————————————————
+
+async function handleCompletionsClient(partial: string): Promise<void> {
+  const { default: queryCompletions } = await import(
+    "../completions/queryCompletions.js"
+  );
+  await queryCompletions(partial);
+}
+
+async function handleCompletionsServer(): Promise<void> {
+  const { default: startCompletionsServer } = await import(
+    "../completions/startCompletionsServer.js"
+  );
+  await startCompletionsServer();
+}
+
+async function handleDoctor(globalFlags: GlobalFlags): Promise<void> {
+  const { doctorCommand } = await import("../domains/doctor/commands/index.js");
+  const ctx = { cwd: process.cwd(), globalFlags };
+  const result = await doctorCommand.execute({}, ctx);
+  if (result.tag === "output") {
+    process.stdout.write(`${result.render.plain(result.value)}\n`);
+  }
+}
+
+async function handleRootHelp(globalFlags: GlobalFlags): Promise<void> {
+  const stubCtx: PragmaContext = {
+    store: {} as PragmaRuntime["store"],
+    config: { tier: undefined, channel: "normal" },
+    cwd: process.cwd(),
+    dispose: () => {},
+    globalFlags,
+  };
+  const commands = collectCommands(stubCtx);
+  const program = createProgram(commands, stubCtx);
+
+  try {
+    await program.parseAsync(["node", "pragma", "--help"]);
+  } catch (err) {
+    handleProgramError(err, globalFlags);
+  }
+}
+
+// — Stage 4+5: Boot, build program, execute ——————————————————————————————————
+
+async function bootAndRun(
+  argv: readonly string[],
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  let runtime: PragmaRuntime | undefined;
+  try {
+    runtime = await bootPragma();
+  } catch (err) {
+    const pragmaErr =
+      err instanceof PragmaError
+        ? err
+        : PragmaError.storeError(
+            err instanceof Error ? err.message : String(err),
+          );
+    process.stderr.write(`${renderError(pragmaErr, globalFlags)}\n`);
+    process.exitCode = mapExitCode(pragmaErr.code);
+    return;
+  }
+
+  try {
+    const ctx: PragmaContext = { ...runtime, globalFlags };
+    const commands = collectCommands(ctx);
+    const program = createProgram(commands, ctx);
+    await program.parseAsync(argv);
+  } catch (err) {
+    handleProgramError(err, globalFlags);
+  } finally {
+    runtime.dispose();
+  }
+}
+
+async function runStoreSkip(
+  argv: readonly string[],
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  const stubCtx: PragmaContext = {
+    store: {} as PragmaRuntime["store"],
+    config: { tier: undefined, channel: "normal" },
+    cwd: process.cwd(),
+    dispose: () => {},
+    globalFlags,
+  };
+  const commands = [...setupCommands()];
+  const program = createProgram(commands, stubCtx);
+
+  try {
+    await program.parseAsync(argv);
+  } catch (err) {
+    handleProgramError(err, globalFlags);
+  }
+}
+
+function handleProgramError(err: unknown, globalFlags: GlobalFlags): void {
+  if (err instanceof CommanderError) {
+    if (
+      err.code === "commander.helpDisplayed" ||
+      err.code === "commander.version"
+    ) {
+      process.exitCode = 0;
+      return;
+    }
+    process.exitCode = err.exitCode;
+    return;
+  }
+
+  if (err instanceof PragmaError) {
+    process.stderr.write(`${renderError(err, globalFlags)}\n`);
+    process.exitCode = mapExitCode(err.code);
+    return;
+  }
+
+  const wrapped = PragmaError.internalError(
+    err instanceof Error ? err.message : String(err),
+  );
+  process.stderr.write(`${renderError(wrapped, globalFlags)}\n`);
+  process.exitCode = 127;
+}
+
+// — Main orchestrator —————————————————————————————————————————————————————————
+
+/**
+ * Main CLI orchestrator.
+ *
+ * Pipeline stages:
+ * 1. `parseGlobalFlags(argv)`
+ * 2. `resolveCommandKind(argv)`
+ * 3. Pattern match on kind -- early exit or `bootPragma()`
+ * 4. `collectCommands(ctx)` + `createProgram(commands, ctx)`
+ * 5. `program.parseAsync(argv)` with error handling + dispose
+ *
+ * @param argv - The raw process.argv array.
+ *
+ * @note Impure
+ */
+export default async function runCli(argv: readonly string[]): Promise<void> {
+  const globalFlags = parseGlobalFlags(argv);
+  const explicitHelpOrVersion = argv
+    .slice(2)
+    .some(
+      (arg) =>
+        arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V",
+    );
+
+  if (!hasCommandArg(argv) && !explicitHelpOrVersion) {
+    return handleRootHelp(globalFlags);
+  }
+
+  const commandKind = resolveCommandKind(argv);
+
+  switch (commandKind.kind) {
+    case "completions-client":
+      return handleCompletionsClient(commandKind.partial);
+    case "completions-server":
+      return handleCompletionsServer();
+    case "doctor":
+      return handleDoctor(globalFlags);
+    case "store-skip":
+      return runStoreSkip(argv, globalFlags);
+    case "store-required":
+      return bootAndRun(argv, globalFlags);
+  }
+}

package/src/pipeline/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Discriminated union classifying the CLI invocation for pipeline routing.
+ *
+ * - `"completions-client"` — shell completion request with a partial input string.
+ * - `"completions-server"` — background completions daemon.
+ * - `"doctor"` — environment validation (runs before store boot).
+ * - `"store-skip"` — commands that do not need the ke store (e.g., `setup`, `mcp`).
+ * - `"store-required"` — standard domain commands requiring a booted store.
+ */
+type CommandKind =
+  | { kind: "completions-client"; partial: string }
+  | { kind: "completions-server" }
+  | { kind: "doctor" }
+  | { kind: "store-skip"; command: string }
+  | { kind: "store-required" };
+
+export type { CommandKind };

package/src/testing/cli.ts

@@ -0,0 +1,43 @@
+/**
+ * CLI test helpers — runCommand, CommandResult.
+ *
+ * Provides a synchronous subprocess runner for testing the pragma CLI
+ * binary in integration tests.
+ */
+
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+/** Captured output from a CLI subprocess invocation. */
+interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Spawn the pragma CLI binary synchronously and capture its output.
+ *
+ * @param args - CLI arguments to pass after the binary path.
+ * @param cwd - Optional working directory for the subprocess.
+ * @returns Captured stdout, stderr, and exit code.
+ *
+ * @note Impure
+ */
+function runCommand(args: string[], cwd?: string): CommandResult {
+  const binPath = resolve(import.meta.dirname, "../bin.ts");
+  const result = spawnSync("bun", ["run", binPath, ...args], {
+    cwd,
+    encoding: "utf-8",
+    timeout: 10_000,
+  });
+
+  return {
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    exitCode: result.status ?? 1,
+  };
+}
+
+export { runCommand };
+export type { CommandResult };

package/src/testing/createTestMcpClient.ts

@@ -0,0 +1,64 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import type { PragmaConfig } from "../config/index.js";
+import type { PragmaRuntime } from "../domains/shared/runtime.js";
+import { createMcpServerFromRuntime } from "../mcp/createMcpServer.js";
+import { DS_ALL_TTL } from "./dsFixtures.js";
+import { createTestStore } from "./store.js";
+import type { TestMcpClientResult } from "./types.js";
+
+/**
+ * Create an in-process MCP client connected to a server with
+ * all tools and resources registered against a test store.
+ *
+ * Uses InMemoryTransport — no network, no stdio. The returned
+ * `cleanup` disposes the client, server, and backing store.
+ *
+ * @param options - Optional TTL data and config overrides.
+ * @returns The connected client and a cleanup function.
+ *
+ * @note Impure
+ */
+export default async function createTestMcpClient(options?: {
+  ttl?: string;
+  config?: PragmaConfig;
+  cwd?: string;
+}): Promise<TestMcpClientResult> {
+  const ttl = options?.ttl ?? DS_ALL_TTL;
+  const config: PragmaConfig = options?.config ?? {
+    tier: undefined,
+    channel: "normal",
+  };
+  const cwd = options?.cwd ?? process.cwd();
+
+  const { store, cleanup: cleanupStore } = await createTestStore({ ttl });
+
+  const runtime: PragmaRuntime = {
+    store,
+    config,
+    cwd,
+    dispose: () => cleanupStore(),
+  };
+
+  const { server } = createMcpServerFromRuntime(runtime);
+
+  const [serverTransport, clientTransport] =
+    InMemoryTransport.createLinkedPair();
+
+  const client = new Client({ name: "pragma-test-client", version: "0.0.0" });
+
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  return {
+    client,
+    cleanup: async () => {
+      try {
+        await client.close();
+        await server.close();
+      } finally {
+        runtime.dispose();
+      }
+    },
+  };
+}