@canonical/pragma-cli 0.31.0 → 0.33.0

package/src/kernel/project/cli/dispatch.ts

@@ -0,0 +1,334 @@
+/**
+ * The CLI dispatcher: from parsed argv to rendered output.
+ *
+ * Coerces raw string args into typed params by {@link ParamSpec.kind} (no zod
+ * on this path), boots the runtime, runs the verb across the effect seam, and
+ * renders. The seam is the discriminator `capability.mutates`: a read is a
+ * plain `Promise` rendered directly; a mutation is a `Task` interpreted under
+ * the node interpreter (`--yes`), the dry-run interpreter (`--dry-run`), or the
+ * undo interpreter (`--undo`). `--format json` wraps output in the full
+ * `{ ok, data, meta }` envelope (D3); errors render to stderr with a mapped
+ * exit code.
+ */
+
+import { describeEffect, dryRun, type Task } from "@canonical/task";
+import { runTask, runUndo } from "@canonical/task/node";
+import {
+  asPragmaError,
+  CANCELLED_MESSAGE,
+  isCancellation,
+  isInterruption,
+} from "../../error/fromTaskError.js";
+import { PragmaError } from "../../error/PragmaError.js";
+import {
+  renderErrorJson,
+  renderErrorLlm,
+  renderErrorPlain,
+} from "../../error/renderError.js";
+import { successEnvelope } from "../../render/envelope.js";
+import { selectFormatter } from "../../render/formatters.js";
+import { writeStdout } from "../../render/writeStdout.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type {
+  GlobalFlags,
+  InteractionRuntime,
+  PragmaRuntime,
+} from "../../runtime/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { EXIT, mapExitCode } from "./exitCodes.js";
+
+/** The CLI-only mutation flags auto-injected onto every mutating verb. */
+export interface MutationFlags {
+  readonly dryRun: boolean;
+  readonly undo: boolean;
+  readonly yes: boolean;
+}
+
+/**
+ * Route a Task's log effects to stderr. The interpreter otherwise falls back to
+ * `console.log` (stdout), which would corrupt the `--format json` / MCP stdio
+ * data stream; diagnostics belong on stderr.
+ */
+const logToStderr = (_level: string, message: string): void => {
+  process.stderr.write(`${message}\n`);
+};
+
+/** The result of running a verb: what to write where, and the exit code. */
+export interface DispatchOutcome {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  readonly exitCode: number;
+}
+
+/** Coerce one raw arg into the type its {@link ParamSpec} declares. */
+function coerceParam(param: ParamSpec, raw: unknown): unknown {
+  switch (param.kind) {
+    case "number": {
+      const value = typeof raw === "number" ? raw : Number(raw);
+      if (Number.isNaN(value)) {
+        throw PragmaError.invalidInput(param.name, String(raw));
+      }
+      return value;
+    }
+    case "boolean":
+      return typeof raw === "boolean" ? raw : raw === "true";
+    case "enum": {
+      const value = String(raw);
+      if (!param.values.includes(value)) {
+        throw PragmaError.invalidInput(param.name, value, {
+          validOptions: [...param.values],
+        });
+      }
+      return value;
+    }
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Build the typed param bag from Commander's positional args and options.
+ *
+ * Flag options arrive keyed by their camelCase param name (Commander derives
+ * `withHistory` from `--with-history`); positionals map in declared order, with
+ * a trailing `string[]` param absorbing the remainder.
+ *
+ * @param params - The verb's parameter specs.
+ * @param positionals - Positional args in order.
+ * @param opts - Commander's parsed option values.
+ * @returns The coerced param bag passed to `run`.
+ */
+export function extractParams(
+  params: readonly ParamSpec[],
+  positionals: readonly string[],
+  opts: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const param of params) {
+    if (param.positional) continue;
+    const raw = opts[param.name];
+    if (raw !== undefined) {
+      result[param.name] = coerceParam(param, raw);
+    } else if ("default" in param && param.default !== undefined) {
+      result[param.name] = param.default;
+    }
+  }
+
+  const positional = params.filter((p) => p.positional);
+  for (let i = 0; i < positional.length && i < positionals.length; i++) {
+    const param = positional[i] as ParamSpec;
+    if (param.kind === "string[]" && i === positional.length - 1) {
+      result[param.name] = positionals.slice(i);
+      break;
+    }
+    result[param.name] = coerceParam(param, positionals[i]);
+  }
+
+  return result;
+}
+
+/** Render a read/execute result through the verb's formatters. */
+function renderData(
+  verb: VerbSpec,
+  flags: GlobalFlags,
+  data: unknown,
+  meta: Record<string, unknown>,
+): DispatchOutcome {
+  if (flags.format === "json") {
+    const projection = JSON.parse(verb.output.formatters.json(data));
+    return {
+      stdout: `${JSON.stringify(successEnvelope(projection, meta))}\n`,
+      exitCode: 0,
+    };
+  }
+  const text = selectFormatter(flags, verb.output.formatters)(data);
+  return { stdout: text ? `${text}\n` : "", exitCode: 0 };
+}
+
+/** Render a dry-run plan (the effects a mutation would perform). */
+function renderPlan(
+  flags: GlobalFlags,
+  plan: readonly string[],
+): DispatchOutcome {
+  if (flags.format === "json") {
+    return {
+      stdout: `${JSON.stringify(successEnvelope({ plan }, { dryRun: true }))}\n`,
+      exitCode: 0,
+    };
+  }
+  const body =
+    plan.length > 0
+      ? `Dry run — planned effects:\n${plan.map((p) => `  - ${p}`).join("\n")}`
+      : "Dry run — no effects.";
+  return { stdout: `${body}\n`, exitCode: 0 };
+}
+
+/** Render the outcome of an undo. */
+function renderUndo(flags: GlobalFlags, undone: number): DispatchOutcome {
+  if (flags.format === "json") {
+    return {
+      stdout: `${JSON.stringify(successEnvelope({ undone }, { undo: true }))}\n`,
+      exitCode: 0,
+    };
+  }
+  return { stdout: `Undid ${undone} step(s).\n`, exitCode: 0 };
+}
+
+/** Render a caught error to stderr with a mapped exit code. */
+function renderError(error: PragmaError, flags: GlobalFlags): DispatchOutcome {
+  const rendered =
+    flags.format === "json"
+      ? renderErrorJson(error)
+      : flags.llm
+        ? renderErrorLlm(error)
+        : renderErrorPlain(error);
+  return { stderr: `${rendered}\n`, exitCode: mapExitCode(error.code) };
+}
+
+/**
+ * Run a verb across the effect seam and produce its output.
+ *
+ * The testable core of {@link dispatch}: pure of process I/O, it returns what
+ * to write rather than writing it, so tests (and the envelope-parity check)
+ * can assert on the outcome directly.
+ *
+ * @param verb - The verb to run.
+ * @param params - The coerced param bag.
+ * @param mutation - The mutation flags (ignored for reads).
+ * @param runtime - The booted runtime.
+ * @returns The dispatch outcome.
+ * @note Impure — a mutation's node/undo interpreter touches the filesystem.
+ */
+export async function executeVerb(
+  verb: VerbSpec,
+  params: Record<string, unknown>,
+  mutation: MutationFlags,
+  runtime: PragmaRuntime,
+): Promise<DispatchOutcome> {
+  const flags = runtime.globalFlags;
+
+  // The lazy-store seam: boot the store (once, memoized) only for verbs that
+  // declare they need it. A storeless verb never reaches the store factory, so
+  // the storeless guarantee holds by construction (no STORE_SKIP triage).
+  if (verb.capability.needsStore) {
+    await runtime.store.get();
+  }
+
+  if (verb.capability.mutates) {
+    // Tell the verb whether this is a plan-only preview (`--dry-run`) or a real
+    // execution, so a network-touching mutation can stay offline for the plan.
+    // Also hand it the interaction context so an interactive verb can pick its
+    // prompt strategy. The verb's `run` sets `mutationRuntime.exec` (the runner
+    // options) as its last act; the projector reads it back on the real-run
+    // branch only — the dry-run/undo branches stay handler-free (they mock
+    // prompts), so `--dry-run`/`--undo` are unchanged by this seam.
+    const controller = new AbortController();
+    const interaction: InteractionRuntime = {
+      // Gate on STDERR (H3): the Ink wizard renders to stderr and reads stdin,
+      // so `<verb> 2>/dev/null` must be non-interactive — gating on stdout would
+      // mount an invisible render that blocks on stdin.
+      isTTY: process.stdin.isTTY === true && process.stderr.isTTY === true,
+      transport: "cli",
+      yes: mutation.yes,
+      signal: controller.signal,
+      // Let an interactive verb's wizard abort the run on an in-Ink Ctrl-C (H2):
+      // raw mode swallows SIGINT, so the keypress can't reach the SIGINT handler
+      // below — the wizard drives this instead. `abort()` is idempotent.
+      abort: () => controller.abort(),
+    };
+    const mutationRuntime: PragmaRuntime = {
+      ...runtime,
+      mutation: { preview: mutation.dryRun },
+      interaction,
+      // Progress seam (U7): a long mutation's eager resolve/build runs before its
+      // Task is returned, so `onLog` can't reach it — stream stage lines straight
+      // to stderr instead, keeping stdout (the JSON/data stream) clean.
+      report: (message: string) => process.stderr.write(`${message}\n`),
+    };
+    const task = await Promise.resolve(
+      verb.run(params, mutationRuntime) as
+        | Task<unknown>
+        | Promise<Task<unknown>>,
+    );
+    if (mutation.dryRun) {
+      // A plan is the effects a mutation WOULD apply — a `Prompt` is not one, so
+      // the interactive confirm gate / answer prompts never clutter the preview.
+      return renderPlan(
+        flags,
+        dryRun(task)
+          .effects.filter((effect) => effect._tag !== "Prompt")
+          .map(describeEffect),
+      );
+    }
+    if (mutation.undo) {
+      const { undoCount } = await runUndo(task, { onLog: logToStderr });
+      return renderUndo(flags, undoCount);
+    }
+    // Real execution: spread the verb's runner options into the node
+    // interpreter (prompt handler, stamping/progress callbacks, log routing,
+    // signal). Teardown (e.g. unmount an Ink render) runs in `finally`.
+    const exec = mutationRuntime.exec ?? {};
+    const onSigint = (): void => controller.abort();
+    process.once("SIGINT", onSigint);
+    try {
+      const value = await runTask(task, { onLog: logToStderr, ...exec });
+      return renderData(verb, flags, value, {});
+    } finally {
+      process.removeListener("SIGINT", onSigint);
+      await exec.dispose?.();
+    }
+  }
+
+  const data = await Promise.resolve(
+    verb.run(params, runtime) as Promise<unknown>,
+  );
+  return renderData(verb, flags, data, {});
+}
+
+/**
+ * Dispatch a matched verb: coerce, run, and perform the output I/O.
+ *
+ * @param verb - The matched verb spec.
+ * @param positionals - Positional args from Commander.
+ * @param opts - Commander's parsed option values (incl. mutation flags).
+ * @param globalFlags - The parsed global flags.
+ * @note Impure — writes stdout/stderr and sets `process.exitCode`.
+ */
+export async function dispatch(
+  verb: VerbSpec,
+  positionals: readonly string[],
+  opts: Record<string, unknown>,
+  globalFlags: GlobalFlags,
+): Promise<void> {
+  const runtime = bootRuntime(globalFlags);
+  let outcome: DispatchOutcome;
+  try {
+    const params = extractParams(verb.params, positionals, opts);
+    const mutation: MutationFlags = {
+      dryRun: opts.dryRun === true,
+      undo: opts.undo === true,
+      yes: opts.yes === true,
+    };
+    outcome = await executeVerb(verb, params, mutation, runtime);
+  } catch (error) {
+    // Two clean, non-bug outcomes print the same "Cancelled." line but exit
+    // differently — both set DIRECTLY here, out-of-band from `mapExitCode`'s
+    // frozen {0,1,2,3} (see exitCodes.ts):
+    //   - a DECLINE (confirm gate / at-prompt Ctrl-C) is a deliberate user
+    //     choice, not a failure → success exit 0; and
+    //   - an INTERRUPT (SIGINT on --yes/CI, or an in-wizard Ctrl-C mid-run) is
+    //     an abort of work already underway → UNIX 128+SIGINT exit 130.
+    // Everything else maps through the shared task-error bridge (which turns a
+    // bad/absent non-interactive answer into a usage error, not an internal bug).
+    outcome = isCancellation(error)
+      ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.OK }
+      : isInterruption(error)
+        ? { stderr: `${CANCELLED_MESSAGE}\n`, exitCode: EXIT.INTERRUPTED }
+        : renderError(asPragmaError(error), globalFlags);
+  }
+
+  if (outcome.stdout) writeStdout(outcome.stdout);
+  if (outcome.stderr) process.stderr.write(outcome.stderr);
+  if (outcome.exitCode !== 0) process.exitCode = outcome.exitCode;
+}

package/src/kernel/project/cli/exitCodes.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { ERROR_CODES } from "../../error/constants.js";
+import type { ErrorCode } from "../../error/types.js";
+import { EXIT, mapExitCode } from "./exitCodes.js";
+
+/**
+ * Protected: the exit-code table is a frozen covenant (D2). Every error code
+ * maps (via {@link mapExitCode}) to exactly one of the four blessed
+ * ERROR-CLASSIFICATION codes, and the table below is the enumerated contract —
+ * changing a mapping must change this test.
+ *
+ * `INTERRUPTED` (130, UNIX 128+SIGINT) is an INTENTIONAL out-of-band addition:
+ * it is set DIRECTLY at the dispatch catch (like the existing exit-0 cancel),
+ * NEVER produced by `mapExitCode`, so the frozen four-code classification range
+ * is untouched. The tests below assert exactly that split.
+ */
+describe("exit codes (PROTECTED)", () => {
+  it("blesses exactly four error-classification codes (mapExitCode's frozen range)", () => {
+    // The four codes mapExitCode is allowed to produce. 130 is deliberately NOT
+    // among them — it bypasses the map (asserted by the exhaustive table below).
+    expect({
+      OK: EXIT.OK,
+      RUNTIME: EXIT.RUNTIME,
+      USAGE: EXIT.USAGE,
+      STORE_UNAVAILABLE: EXIT.STORE_UNAVAILABLE,
+    }).toEqual({ OK: 0, RUNTIME: 1, USAGE: 2, STORE_UNAVAILABLE: 3 });
+  });
+
+  it("adds INTERRUPTED=130 as an out-of-band code never produced by mapExitCode", () => {
+    // A deliberate SIGINT/interrupt exit (UNIX 128+SIGINT), set directly at the
+    // dispatch catch. It must never leak into mapExitCode's classification range.
+    expect(EXIT.INTERRUPTED).toBe(130);
+    const produced = new Set(ERROR_CODES.map(mapExitCode));
+    expect(produced.has(130)).toBe(false);
+    expect([...produced].every((c) => c === 1 || c === 2 || c === 3)).toBe(
+      true,
+    );
+  });
+
+  const table: Record<ErrorCode, number> = {
+    ENTITY_NOT_FOUND: 1,
+    EMPTY_RESULTS: 1,
+    CONFIG_ERROR: 1,
+    INTERNAL_ERROR: 1,
+    UNSUPPORTED: 1,
+    INVALID_INPUT: 2,
+    AMBIGUOUS_INPUT: 2,
+    UNKNOWN_VERB: 2,
+    STORE_UNAVAILABLE: 3,
+  };
+
+  it.each(ERROR_CODES)("maps %s to its exit code", (code) => {
+    expect(mapExitCode(code)).toBe(table[code]);
+  });
+
+  it("covers every error code in the table", () => {
+    expect(Object.keys(table).sort()).toEqual([...ERROR_CODES].sort());
+  });
+});

package/src/kernel/project/cli/exitCodes.ts

@@ -0,0 +1,68 @@
+/**
+ * Process exit codes for the CLI projector (D2).
+ *
+ * The covenant freezes exactly four ERROR-CLASSIFICATION codes: success, a
+ * generic runtime failure, a usage failure, and an unavailable store.
+ * {@link mapExitCode} routes every {@link ErrorCode} into one of them — usage
+ * errors the shell can fix, a store that is not reachable, and everything else
+ * as a runtime failure.
+ *
+ * COVENANT NOTE — out-of-band codes bypass {@link mapExitCode} by design. The
+ * dispatch catch sets two codes DIRECTLY, never through the map, so the frozen
+ * `{0,1,2,3}` classification set is untouched:
+ *   - a deliberate cancel (declining the confirm gate / an at-prompt Ctrl-C)
+ *     exits {@link EXIT.OK} (0) — a user choice, not a failure; and
+ *   - an interrupt ({@link EXIT.INTERRUPTED}, 130) — a run aborted by SIGINT or
+ *     an in-wizard Ctrl-C mid-execution, following the UNIX 128+SIGINT
+ *     convention. It is intentionally out-of-band from the four error codes and
+ *     is NOT produced by `mapExitCode`.
+ */
+
+import type { ErrorCode } from "../../error/types.js";
+
+/**
+ * The process exit codes. The first four are the covenant's frozen
+ * error-classification set (produced by {@link mapExitCode}); `INTERRUPTED` is
+ * the out-of-band UNIX interrupt code set directly at the dispatch catch (see
+ * the module doc), never routed through the map.
+ */
+export const EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Generic runtime failure (entity-not-found, empty, config, internal). */
+  RUNTIME: 1,
+  /** Usage failure (invalid/ambiguous input, unknown verb). */
+  USAGE: 2,
+  /** The knowledge-engine store could not be reached. */
+  STORE_UNAVAILABLE: 3,
+  /**
+   * Interrupted by SIGINT / an in-wizard Ctrl-C during execution (UNIX
+   * 128+SIGINT). Out-of-band from the four classification codes above: set
+   * directly at the dispatch catch, NOT via {@link mapExitCode}.
+   */
+  INTERRUPTED: 130,
+} as const;
+
+/** Error codes that signal a usage mistake the caller can correct. */
+const USAGE_CODES = new Set<ErrorCode>([
+  "INVALID_INPUT",
+  "AMBIGUOUS_INPUT",
+  "UNKNOWN_VERB",
+]);
+
+/**
+ * Map a {@link PragmaError} code to its numeric process exit code.
+ *
+ * Usage codes map to {@link EXIT.USAGE}, an unavailable store to
+ * {@link EXIT.STORE_UNAVAILABLE}, and every other code — entity-not-found,
+ * empty results, config error, internal error — to the generic
+ * {@link EXIT.RUNTIME}.
+ *
+ * @param code - The error code to map.
+ * @returns The corresponding process exit code.
+ */
+export function mapExitCode(code: ErrorCode): number {
+  if (code === "STORE_UNAVAILABLE") return EXIT.STORE_UNAVAILABLE;
+  if (USAGE_CODES.has(code)) return EXIT.USAGE;
+  return EXIT.RUNTIME;
+}

package/src/kernel/project/cli/globalFlags.test.ts

@@ -0,0 +1,107 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseGlobalFlags,
+  readRawFormat,
+  stripGlobalFlags,
+} from "./globalFlags.js";
+
+const TTY = { isTty: true, noAutoLlm: false };
+const PIPE = { isTty: false, noAutoLlm: false };
+
+describe("parseGlobalFlags", () => {
+  it("honours an explicit --format llm (condensed even on a TTY)", () => {
+    expect(parseGlobalFlags(["--format", "llm"], TTY)).toMatchObject({
+      llm: true,
+      autoLlm: false,
+      format: "llm",
+    });
+  });
+
+  it("forces human output with --format plain down a pipe", () => {
+    expect(parseGlobalFlags(["--format", "plain"], PIPE)).toMatchObject({
+      llm: false,
+      autoLlm: false,
+      format: "plain",
+    });
+  });
+
+  it("selects json format (space and equals forms)", () => {
+    expect(parseGlobalFlags(["--format", "json"], TTY).format).toBe("json");
+    expect(parseGlobalFlags(["--format=json"], TTY).format).toBe("json");
+  });
+
+  it("renames --format text to plain", () => {
+    expect(parseGlobalFlags(["--format", "text"], PIPE).format).toBe("plain");
+  });
+
+  it("auto-enables llm on a non-interactive stdout", () => {
+    expect(parseGlobalFlags([], PIPE)).toMatchObject({
+      llm: true,
+      autoLlm: true,
+    });
+  });
+
+  it("stays rich on an interactive terminal", () => {
+    expect(parseGlobalFlags([], TTY)).toMatchObject({
+      llm: false,
+      autoLlm: false,
+    });
+  });
+
+  it("respects PRAGMA_NO_AUTO_LLM", () => {
+    expect(
+      parseGlobalFlags([], { isTty: false, noAutoLlm: true }),
+    ).toMatchObject({ llm: false, autoLlm: false });
+  });
+
+  it("does not auto-enable llm when a format is requested", () => {
+    expect(parseGlobalFlags(["--format", "json"], PIPE).llm).toBe(false);
+  });
+
+  it("reads a valid --detail level and drops an invalid one", () => {
+    expect(parseGlobalFlags(["--detail", "detailed"], TTY).detail).toBe(
+      "detailed",
+    );
+    expect(parseGlobalFlags(["--detail", "bogus"], TTY).detail).toBeUndefined();
+  });
+
+  it("reads --verbose", () => {
+    expect(parseGlobalFlags(["--verbose"], TTY).verbose).toBe(true);
+  });
+});
+
+describe("stripGlobalFlags", () => {
+  it("removes global flags and their values, keeping the command", () => {
+    expect(stripGlobalFlags(["--format", "json", "block", "list"])).toEqual([
+      "block",
+      "list",
+    ]);
+    expect(
+      stripGlobalFlags(["block", "--verbose", "list", "--detail", "detailed"]),
+    ).toEqual(["block", "list"]);
+    expect(stripGlobalFlags(["--format=json", "config", "show"])).toEqual([
+      "config",
+      "show",
+    ]);
+    expect(stripGlobalFlags(["config", "show", "--verbose"])).toEqual([
+      "config",
+      "show",
+    ]);
+  });
+});
+
+describe("readRawFormat", () => {
+  it("returns the raw value for validation", () => {
+    expect(readRawFormat(["--format", "yaml"])).toBe("yaml");
+    expect(readRawFormat(["--format=json"])).toBe("json");
+  });
+
+  it("reports a valueless --format as empty string", () => {
+    expect(readRawFormat(["--format"])).toBe("");
+    expect(readRawFormat(["--format", "--verbose"])).toBe("");
+  });
+
+  it("returns undefined when --format is absent", () => {
+    expect(readRawFormat(["block", "list"])).toBeUndefined();
+  });
+});