@canonical/pragma-cli 0.31.0 → 0.32.0

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,99 @@
+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 --llm", () => {
+    expect(parseGlobalFlags(["--llm"], TTY)).toMatchObject({
+      llm: true,
+      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", "--llm", "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", "--llm"])).toBe("");
+  });
+
+  it("returns undefined when --format is absent", () => {
+    expect(readRawFormat(["block", "list"])).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,149 @@
+/**
+ * Global-flag pre-parsing, ahead of Commander.
+ *
+ * `--llm`, `--format`, `--verbose`, and `--detail` may appear anywhere on the
+ * line, so they are scanned and stripped before Commander sees argv — otherwise
+ * `enablePositionalOptions()` scoping would reject a flag placed after a verb.
+ * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
+ * flag and the `--format text` value renamed to `plain` (the kernel's
+ * {@link OutputFormat}). Both the space (`--format json`) and equals
+ * (`--format=json`) forms are recognized.
+ */
+
+import { DETAIL_LEVELS, type DetailLevel } from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+
+/**
+ * Read a `--flag`'s value, accepting both `--flag value` and `--flag=value`.
+ *
+ * @param argv - Raw argv (already sliced to the user's arguments).
+ * @param flag - The flag including leading dashes (e.g. `--format`).
+ * @returns The 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 typed, for validation.
+ *
+ * Unlike {@link parseGlobalFlags} this does not normalize — the caller decides
+ * how to reject an unknown value. A bare `--format` with no following value is
+ * reported as `""` (not `undefined`) so it is rejected rather than silently
+ * falling through.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @returns The raw value, `""` for a valueless `--format`, or `undefined`.
+ */
+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];
+  return value !== undefined && !value.startsWith("-") ? value : "";
+}
+
+/**
+ * Environment probe for the auto-LLM default. Injectable so 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),
+  };
+}
+
+/** Narrow a raw `--detail` value to a recognized level, else `undefined`. */
+function readDetail(argv: readonly string[]): DetailLevel | undefined {
+  const raw = readFlagValue(argv, "--detail");
+  if (raw !== undefined && (DETAIL_LEVELS as readonly string[]).includes(raw)) {
+    return raw as DetailLevel;
+  }
+  return undefined;
+}
+
+/**
+ * Extract the global flags from raw argv (the user's arguments, argv[2:]).
+ *
+ * Auto-LLM: with no `--llm`/`--format` and a non-interactive stdout (piped or
+ * redirected — the shape an agent captures), `llm` defaults to true so agents
+ * get condensed Markdown without a flag. `--llm`, `--format`, and
+ * `PRAGMA_NO_AUTO_LLM` all override it.
+ *
+ * @param argv - The user's arguments (no `node`/script prefix).
+ * @param env - Output environment probe (defaults to the real process).
+ * @returns The parsed global flags.
+ * @note Impure by default — reads process.stdout/env unless `env` is injected.
+ */
+export function parseGlobalFlags(
+  argv: readonly string[],
+  env: OutputEnvironment = readOutputEnvironment(),
+): GlobalFlags {
+  const explicitLlm = argv.includes("--llm");
+  const rawFormat = readFlagValue(argv, "--format");
+  const format = rawFormat === "json" ? "json" : "plain";
+  const formatRequested = rawFormat !== undefined;
+  const autoLlm =
+    !explicitLlm && !formatRequested && !env.isTty && !env.noAutoLlm;
+  const detail = readDetail(argv);
+  return {
+    llm: explicitLlm || autoLlm,
+    autoLlm,
+    format,
+    verbose: argv.includes("--verbose"),
+    ...(detail !== undefined ? { detail } : {}),
+  };
+}
+
+/**
+ * Return a copy of argv with every global flag (and its value) removed.
+ *
+ * Since {@link parseGlobalFlags} pre-parses these, they are dropped so they do
+ * not collide with Commander's positional scoping, letting the user place them
+ * anywhere on the line.
+ *
+ * @param argv - The user's arguments.
+ * @returns A new array with global flags stripped.
+ */
+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;
+    if (
+      arg?.startsWith("--format=") ||
+      arg?.startsWith("--llm=") ||
+      arg?.startsWith("--verbose=") ||
+      arg?.startsWith("--detail=")
+    ) {
+      continue;
+    }
+    if (arg === "--format" || arg === "--detail") {
+      i += 1; // skip the space-form value too
+      continue;
+    }
+    result.push(arg as string);
+  }
+  return result;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Shared help-rendering primitives — the ONE visual system every help page
+ * composes from.
+ *
+ * Root help (`rootHelp.ts`), noun help, and verb help (`verbHelp.ts`) all build
+ * their pages out of these helpers so the front door and the leaf pages read as
+ * the same CLI: a dim `Usage:` label, bold section headers, a cyan-term /
+ * dim-description two-column body, and a dim footer that points at the next help
+ * level. chalk auto-disables color off a TTY, so goldens, piped output, and MCP
+ * transports all capture plain text — only an interactive terminal gets color.
+ */
+
+import chalk from "chalk";
+
+/** Two-space indent for every list body row. */
+const INDENT = "  ";
+/** Two-space gap between a term column and its description. */
+const GAP = "  ";
+
+/** A bold section header (`Flags`, `Verbs`, `Explore the design system`). */
+export function helpHeading(text: string): string {
+  return chalk.bold(text);
+}
+
+/** Dim secondary text — an example note, or the footer line. */
+export function helpDim(text: string): string {
+  return chalk.dim(text);
+}
+
+/** A cyan term — a command, verb, flag, or example, as shown in the body. */
+export function helpTerm(text: string): string {
+  return chalk.cyan(text);
+}
+
+/** The `Usage:` line: a dim label followed by the given command shape. */
+export function helpUsage(body: string): string {
+  return `${chalk.dim("Usage:")} ${body}`;
+}
+
+/**
+ * Render aligned two-column rows: a cyan term padded to a common width, then its
+ * dim description. Pass an explicit `width` to align across several lists (the
+ * root's grouped sections share one column); omit it to size to these rows
+ * alone.
+ *
+ * @param rows - `[term, description]` pairs.
+ * @param width - Optional shared column width; defaults to the widest term.
+ * @returns One formatted line per row.
+ */
+export function helpColumns(
+  rows: readonly (readonly [term: string, description: string])[],
+  width?: number,
+): string[] {
+  const column = width ?? Math.max(0, ...rows.map(([term]) => term.length));
+  return rows.map(([term, description]) =>
+    `${INDENT}${chalk.cyan(term.padEnd(column))}${GAP}${chalk.dim(description)}`.trimEnd(),
+  );
+}

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

@@ -0,0 +1,21 @@
+/**
+ * CLI projector barrel — the Commander program, dispatcher, help, and
+ * exit-code model. The bin composes these; tests build programs from arbitrary
+ * modules via the `projectCli` helper.
+ */
+
+export type { BuildProgramOptions } from "./buildProgram.js";
+export { buildProgram } from "./buildProgram.js";
+export type { DispatchOutcome, MutationFlags } from "./dispatch.js";
+export { dispatch, executeVerb, extractParams } from "./dispatch.js";
+export { EXIT, mapExitCode } from "./exitCodes.js";
+export type { OutputEnvironment } from "./globalFlags.js";
+export {
+  parseGlobalFlags,
+  readRawFormat,
+  stripGlobalFlags,
+} from "./globalFlags.js";
+export { formatRootHelp } from "./rootHelp.js";
+export { nounVerbMap, resolveUnknownCommand } from "./suggest.js";
+export { suggestNames } from "./suggestNames.js";
+export { formatNounHelp, formatVerbHelp } from "./verbHelp.js";

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

@@ -0,0 +1,99 @@
+/**
+ * The §0 spine: a mutating verb reads `runtime.interaction` and sets
+ * `runtime.exec`, and the dispatcher spreads `exec` into the node interpreter
+ * on the REAL-run branch only — so an interactive Prompt effect is resolved by
+ * the injected handler (not the bare `NO_PROMPT_HANDLER` throw), while
+ * `--dry-run` stays handler-free and mocks the prompt.
+ */
+
+import { $, gen, prompt } from "@canonical/task";
+import { describe, expect, it, vi } from "vitest";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags, VerbSpec } from "../../spec/types.js";
+import { executeVerb, type MutationFlags } from "./dispatch.js";
+
+const FLAGS: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const noMutation: MutationFlags = { dryRun: false, undo: false, yes: false };
+
+const json = (d: unknown) => JSON.stringify(d);
+
+/** A mutating verb whose task prompts once and whose `run` wires `exec`. */
+function seamVerb(onExec?: () => void): VerbSpec {
+  return {
+    path: ["fixture", "seam"],
+    summary: "A prompting mutation.",
+    params: [],
+    output: { formatters: { plain: json, llm: json, json } },
+    capability: {
+      needsStore: false,
+      mutates: true,
+      interactive: true,
+      mcp: { expose: false, reason: "test fixture" },
+    },
+    run: (_params, rt) => {
+      // The verb picks its strategy from the interaction context and records it
+      // as the injected prompt handler + optional teardown.
+      const answer = rt.interaction?.yes ? "confirmed" : "attended";
+      rt.exec = {
+        promptHandler: () => Promise.resolve(answer),
+        dispose: onExec,
+      };
+      return gen(function* () {
+        const value = yield* $(
+          prompt({ type: "text", name: "which", message: "Which?" }),
+        );
+        return { value };
+      });
+    },
+  };
+}
+
+describe("interaction/exec seam (PROTECTED)", () => {
+  it("resolves an interactive Prompt through the verb's injected handler", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(
+      seamVerb(),
+      {},
+      { ...noMutation, yes: true },
+      runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    expect(outcome.stdout).toContain("confirmed");
+  });
+
+  it("passes the interaction context (yes flag) to the verb", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(seamVerb(), {}, noMutation, runtime);
+    expect(outcome.stdout).toContain("attended");
+  });
+
+  it("runs the verb's exec.dispose teardown after a real run", async () => {
+    const dispose = vi.fn();
+    const runtime = bootRuntime(FLAGS);
+    await executeVerb(
+      seamVerb(dispose),
+      {},
+      { ...noMutation, yes: true },
+      runtime,
+    );
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it("dry-run stays handler-free, mocks the prompt, and omits it from the plan", async () => {
+    const runtime = bootRuntime(FLAGS);
+    const outcome = await executeVerb(
+      seamVerb(),
+      {},
+      { ...noMutation, dryRun: true },
+      runtime,
+    );
+    expect(outcome.exitCode).toBe(0);
+    // The only effect is the Prompt (mocked) — filtered from the plan.
+    expect(outcome.stdout).toContain("no effects");
+  });
+});