@canonical/pragma-cli 0.31.0 → 0.33.0

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

@@ -0,0 +1,291 @@
+/**
+ * Build the Commander program from the grammar.
+ *
+ * Reads only the declarative fields of each {@link VerbSpec} — path, params,
+ * summary, capability — never a run body, so constructing the tree stays on the
+ * fast path and imports no verb implementations (the actions dynamic-dispatch
+ * lazily). Verbs are grouped by noun: a self-verb (`["info"]`) attaches to the
+ * root, sub-verbs (`["config","show"]`) hang under a noun parent. Positionals
+ * become usage tokens, other params become kebab flags, and a mutating verb
+ * gains the auto-injected `--dry-run` / `--undo` / `--yes` flags. Ported from
+ * the v1 cli-core `registerAll`, retargeted at the grammar.
+ */
+
+import { Command, Option } from "commander";
+import { BIN_NAME, PROGRAM_DESCRIPTION, VERSION } from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+import { kebabCase } from "../../spec/emitSurface.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { dispatch } from "./dispatch.js";
+import { formatRootHelp } from "./rootHelp.js";
+import { formatNounHelp, formatVerbHelp } from "./verbHelp.js";
+
+/** Options controlling the built program. */
+export interface BuildProgramOptions {
+  /** Global flags for this invocation, closed over by every verb action. */
+  readonly globalFlags: GlobalFlags;
+  /** Binary name (defaults to `pragma`). */
+  readonly programName?: string;
+  /** Program description shown in root help. */
+  readonly description?: string;
+  /** Version string for `--version`. */
+  readonly version?: string;
+}
+
+/** The positional usage token for a param (`<name>` / `[name]`, variadic `...`). */
+function positionalToken(param: ParamSpec): string {
+  const variadic = param.kind === "string[]" ? "..." : "";
+  return param.required
+    ? `<${param.name}${variadic}>`
+    : `[${param.name}${variadic}]`;
+}
+
+/** The Commander flag spec for a non-positional param. */
+function flagSpec(param: ParamSpec): string {
+  const flag = `--${kebabCase(param.name)}`;
+  if (param.kind === "boolean") return flag;
+  if (param.kind === "string[]") return `${flag} <values...>`;
+  return `${flag} <value>`;
+}
+
+/** Install designed help for a command, suppressing Commander's auto-help. */
+function useDesignedHelp(command: Command, text: () => string): void {
+  command.configureHelp({ formatHelp: () => "" });
+  command.addHelpText("beforeAll", (ctx) =>
+    ctx.command === command ? `${text()}\n` : "",
+  );
+}
+
+/** Register a verb's flags (plus mutation flags) onto its Commander command. */
+function registerParams(command: Command, verb: VerbSpec): void {
+  for (const param of verb.params) {
+    if (param.positional) continue;
+    const spec = flagSpec(param);
+    if (param.kind === "enum") {
+      const option = new Option(spec, param.doc).choices([...param.values]);
+      if (param.default !== undefined) option.default(param.default);
+      command.addOption(option);
+    } else if ("default" in param && param.default !== undefined) {
+      command.option(spec, param.doc, param.default as string | boolean);
+    } else {
+      command.option(spec, param.doc);
+    }
+    // B9: a default-`true` boolean is otherwise undisableable — the grammar has
+    // no negation form, so `create`'s sibling booleans (--ssr/--with-styles/…)
+    // could never be turned off. Register a paired `--no-<flag>` so they can:
+    // Commander keeps the `true` default and lets `--no-<flag>` set it false
+    // (verified: an unset default-false boolean is left alone). This is a CLI
+    // PARSE convenience, never a ParamSpec — `emitSurface`/MCP/the covenant are
+    // untouched — so the frozen flag list stands and negation stays additive.
+    if (param.kind === "boolean" && param.default === true) {
+      const flag = kebabCase(param.name);
+      command.option(`--no-${flag}`, `Disable --${flag} (on by default).`);
+    }
+  }
+
+  if (verb.capability.mutates) {
+    command.option("--dry-run", "Preview effects without applying them");
+    command.option("--undo", "Reverse a previous run of this command");
+    command.option("--yes", "Apply without an interactive confirmation");
+  }
+}
+
+/** Split Commander's variadic action args into positionals and options. */
+function splitActionArgs(actionArgs: readonly unknown[]): {
+  positionals: string[];
+  opts: Record<string, unknown>;
+} {
+  const positionals: string[] = [];
+  let opts: Record<string, unknown> = {};
+  for (const arg of actionArgs) {
+    if (typeof arg === "string") {
+      positionals.push(arg);
+    } else if (Array.isArray(arg)) {
+      positionals.push(
+        ...arg.filter((value): value is string => typeof value === "string"),
+      );
+    } else if (arg instanceof Command) {
+      // The trailing Command instance — skip.
+    } else if (typeof arg === "object" && arg !== null) {
+      opts = arg as Record<string, unknown>;
+    }
+  }
+  return { positionals, opts };
+}
+
+/** Attach one verb as a leaf command under `parent`. */
+function attachVerb(
+  parent: Command,
+  verb: VerbSpec,
+  name: string,
+  programName: string,
+  globalFlags: GlobalFlags,
+): void {
+  const positionals = verb.params.filter((p) => p.positional);
+  const suffix = positionals.map(positionalToken).join(" ");
+  const fullName = suffix ? `${name} ${suffix}` : name;
+
+  const command = parent.command(fullName).description(verb.summary);
+  command.enablePositionalOptions();
+  useDesignedHelp(command, () => formatVerbHelp(programName, verb));
+  registerParams(command, verb);
+
+  command.action(async (...actionArgs: unknown[]) => {
+    const { positionals: positionalArgs, opts } = splitActionArgs(actionArgs);
+    await dispatch(verb, positionalArgs, opts, globalFlags);
+  });
+}
+
+/**
+ * Attach a noun that has sub-verbs, creating its parent command exactly once.
+ *
+ * When the noun also has a SELF-verb (`["setup"]`), the parent command doubles
+ * as that verb — it carries the self-verb's own params/mutation flags and
+ * `.action()` AND hosts the sub-commands, so `pragma setup` runs the self-verb
+ * while `pragma setup mcp` routes to the sub. Commander resolves a registered
+ * sub-command name before the parent's action, so the two never collide — but
+ * only because the one covenant noun shaped this way (`setup`) has NO positional
+ * on its self-verb, so `<noun> <sub>` can never be read as a positional value.
+ * A noun with only sub-verbs keeps a plain, action-less group parent.
+ *
+ * @param program - The root program.
+ * @param noun - The noun to attach.
+ * @param selfVerb - The self-verb (`path.length === 1`), if the noun has one.
+ * @param subVerbs - The noun's sub-verbs (`path.length > 1`).
+ * @param programName - The binary name shown in help.
+ * @param globalFlags - Global flags closed over by every action.
+ * @param live - All non-hidden verbs, for noun-level help.
+ */
+function attachNounGroup(
+  program: Command,
+  noun: string,
+  selfVerb: VerbSpec | undefined,
+  subVerbs: readonly VerbSpec[],
+  programName: string,
+  globalFlags: GlobalFlags,
+  live: readonly VerbSpec[],
+): void {
+  const parent = program.command(noun);
+  parent.enablePositionalOptions();
+  useDesignedHelp(parent, () => formatNounHelp(programName, noun, live));
+
+  if (selfVerb) {
+    // A mixed noun (self-verb + sub-verbs) MUST have no positional on its
+    // self-verb: Commander resolves a registered sub-command name before the
+    // parent action, so a positional would be shadowed by `<noun> <sub>` and
+    // silently dropped from the parent's model. Enforce the invariant the
+    // JSDoc above documents, turning a latent footgun into a build-time error.
+    const positional = selfVerb.params.find((param) => param.positional);
+    if (positional) {
+      throw new Error(
+        `buildProgram: mixed noun "${noun}" self-verb declares positional ` +
+          `"${positional.name}"; a mixed noun's self-verb must have no ` +
+          "positional (it collides with sub-verb routing).",
+      );
+    }
+    parent.description(selfVerb.summary);
+    registerParams(parent, selfVerb);
+    parent.action(async (...actionArgs: unknown[]) => {
+      const { positionals: positionalArgs, opts } = splitActionArgs(actionArgs);
+      await dispatch(selfVerb, positionalArgs, opts, globalFlags);
+    });
+  } else {
+    parent.description(`${noun} commands`);
+    // A sub-verb-only noun invoked bare (`pragma block`) prints its own help
+    // and exits 0 — byte-for-byte the `pragma block --help` page, because it
+    // runs the SAME Commander help machinery `--help` runs (`outputHelp`),
+    // minus the `helpDisplayed` throw, so it returns 0. Commander resolves a
+    // registered sub-command name BEFORE the parent action (the invariant the
+    // mixed-noun path above relies on), so `pragma block list` still routes to
+    // the sub-verb; only the bare noun reaches this action.
+    //
+    // An UNRECOGNIZED sub-verb (`pragma block bogus`) must keep its "Did you
+    // mean?" suggestion. Adding an action turns Commander's default
+    // unknown-command error into a generic "too many arguments" (the action
+    // declares no positional), so we opt into excess args and re-raise the
+    // SAME `unknownCommand` error the bin's suggester already routes on — the
+    // bin re-derives the offending token from argv, so its message is cosmetic.
+    parent.allowExcessArguments(true);
+    parent.action(async () => {
+      // The unrecognized sub-verb lands in `parent.args` (excess operands), not
+      // as a declared action parameter, since the parent declares none.
+      const excess = parent.args[0];
+      if (excess !== undefined) {
+        const { CommanderError } = await import("commander");
+        throw new CommanderError(
+          2,
+          "commander.unknownCommand",
+          `error: unknown command '${excess}'`,
+        );
+      }
+      parent.outputHelp();
+    });
+  }
+
+  for (const verb of subVerbs) {
+    attachVerb(parent, verb, verb.path[1] as string, programName, globalFlags);
+  }
+}
+
+/**
+ * Build the Commander program for a set of verbs.
+ *
+ * @param verbs - The verbs to project (hidden verbs are excluded).
+ * @param options - Global flags and program metadata.
+ * @returns The configured program, ready for `parseAsync`.
+ */
+export function buildProgram(
+  verbs: readonly VerbSpec[],
+  options: BuildProgramOptions,
+): Command {
+  const programName = options.programName ?? BIN_NAME;
+  const description = options.description ?? PROGRAM_DESCRIPTION;
+  const version = options.version ?? VERSION;
+  const live = verbs.filter((verb) => !verb.hidden);
+
+  const program = new Command();
+  program.name(programName).description(description);
+  program.version(version, "-v, --version");
+  program.enablePositionalOptions();
+  program.exitOverride();
+  useDesignedHelp(program, () =>
+    formatRootHelp(programName, description, live),
+  );
+
+  const groups = new Map<string, VerbSpec[]>();
+  for (const verb of live) {
+    const noun = verb.path[0];
+    const bucket = groups.get(noun) ?? [];
+    bucket.push(verb);
+    groups.set(noun, bucket);
+  }
+
+  for (const [noun, bucket] of groups) {
+    const selfVerbs = bucket.filter((v) => v.path.length === 1);
+    const subVerbs = bucket.filter((v) => v.path.length > 1);
+
+    // Pure self-verb noun(s) — attach each leaf directly to the root, as before.
+    if (subVerbs.length === 0) {
+      for (const verb of selfVerbs) {
+        attachVerb(program, verb, noun, programName, options.globalFlags);
+      }
+      continue;
+    }
+
+    // Has sub-verbs (and, for the mixed noun `setup`, also a self-verb): the
+    // noun parent is created ONCE. A pre-fold buildProgram registered
+    // `program.command(noun)` twice for such a noun (self leaf + sub parent) —
+    // Commander then saw a duplicate `setup` command.
+    attachNounGroup(
+      program,
+      noun,
+      selfVerbs[0],
+      subVerbs,
+      programName,
+      options.globalFlags,
+      live,
+    );
+  }
+
+  return program;
+}

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

@@ -0,0 +1,288 @@
+import { fail, succeed } from "@canonical/task";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { PragmaError } from "../../error/PragmaError.js";
+import { bootRuntime } from "../../runtime/boot.js";
+import type { GlobalFlags } from "../../runtime/types.js";
+import type { ParamSpec, VerbSpec } from "../../spec/types.js";
+import { dispatch, executeVerb, extractParams } from "./dispatch.js";
+
+const PLAIN: GlobalFlags = {
+  llm: false,
+  autoLlm: false,
+  format: "plain",
+  verbose: false,
+};
+const JSON_FLAGS: GlobalFlags = { ...PLAIN, format: "json" };
+
+const passthroughFormatters = {
+  plain: (d: unknown) => String(d),
+  llm: (d: unknown) => String(d),
+  json: (d: unknown) => JSON.stringify(d),
+};
+
+const echo: VerbSpec = {
+  path: ["probe", "echo"],
+  summary: "Echo the message.",
+  params: [
+    {
+      kind: "string",
+      name: "message",
+      doc: "The message.",
+      positional: true,
+      required: true,
+    },
+  ],
+  output: { formatters: passthroughFormatters },
+  capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+  run: async (p) => ({ echoed: (p as { message: string }).message }),
+};
+
+const make: VerbSpec = {
+  path: ["probe", "make"],
+  summary: "Make a thing.",
+  params: [],
+  output: { formatters: passthroughFormatters },
+  capability: { needsStore: false, mutates: true, mcp: { expose: true } },
+  run: () => succeed({ made: true }),
+};
+
+describe("extractParams", () => {
+  it("maps positionals and flags into the param bag", () => {
+    const params: ParamSpec[] = [
+      {
+        kind: "string",
+        name: "name",
+        doc: "",
+        positional: true,
+        required: true,
+      },
+      { kind: "boolean", name: "withHistory", doc: "" },
+    ];
+    expect(extractParams(params, ["Gadget"], { withHistory: true })).toEqual({
+      name: "Gadget",
+      withHistory: true,
+    });
+  });
+
+  it("coerces a number and rejects a non-number", () => {
+    const params: ParamSpec[] = [
+      { kind: "number", name: "count", doc: "", positional: true },
+    ];
+    expect(extractParams(params, ["42"], {})).toEqual({ count: 42 });
+    expect(() => extractParams(params, ["nan"], {})).toThrow(PragmaError);
+  });
+
+  it("rejects an out-of-set enum value", () => {
+    const params: ParamSpec[] = [
+      { kind: "enum", name: "mode", doc: "", values: ["a", "b"] },
+    ];
+    expect(() => extractParams(params, [], { mode: "c" })).toThrow(
+      /Invalid mode/,
+    );
+  });
+
+  it("absorbs the remainder into a trailing string[] positional", () => {
+    const params: ParamSpec[] = [
+      { kind: "string[]", name: "names", doc: "", positional: true },
+    ];
+    expect(extractParams(params, ["a", "b", "c"], {})).toEqual({
+      names: ["a", "b", "c"],
+    });
+  });
+});
+
+describe("executeVerb — reads", () => {
+  it("renders plain text", async () => {
+    const outcome = await executeVerb(
+      echo,
+      { message: "hi" },
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toBe("[object Object]\n");
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("wraps json output in the {ok,data,meta} envelope", async () => {
+    const outcome = await executeVerb(
+      echo,
+      { message: "hi" },
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(JSON_FLAGS),
+    );
+    expect(JSON.parse(outcome.stdout as string)).toEqual({
+      ok: true,
+      data: { echoed: "hi" },
+      meta: {},
+    });
+  });
+});
+
+describe("executeVerb — mutations", () => {
+  it("executes a Task and envelopes the result", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(JSON_FLAGS),
+    );
+    expect(JSON.parse(outcome.stdout as string)).toEqual({
+      ok: true,
+      data: { made: true },
+      meta: {},
+    });
+  });
+
+  it("previews under --dry-run without executing", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: true, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toContain("Dry run");
+  });
+
+  it("reports undo count under --undo", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: false, undo: true, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toBe("Undid 0 step(s).\n");
+  });
+});
+
+describe("dispatch — errors", () => {
+  const savedExit = process.exitCode;
+  afterEach(() => {
+    process.exitCode = savedExit;
+  });
+
+  it("renders a PragmaError to stderr with a mapped exit code", async () => {
+    const failing: VerbSpec = {
+      ...echo,
+      run: async () => {
+        throw PragmaError.notFound("thing", "Nope");
+      },
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    await dispatch(failing, ["x"], {}, PLAIN);
+    spy.mockRestore();
+    expect(errs.join("")).toContain('thing "Nope" not found.');
+    expect(process.exitCode).toBe(1);
+  });
+
+  it("renders a declined confirm gate as a clean cancellation, not a bug report", async () => {
+    // A TTY user declining execute()'s "Proceed?" gate fails the task with
+    // GENERATOR_CANCELLED; the boundary must treat it as a clean cancel, never
+    // the scary INTERNAL_ERROR "please report this issue" / exit 1.
+    const cancelling: VerbSpec = {
+      ...make,
+      run: () => fail({ code: "GENERATOR_CANCELLED", message: "Cancelled." }),
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    await dispatch(cancelling, [], { yes: true }, PLAIN);
+    spy.mockRestore();
+    const out = errs.join("");
+    expect(out).toContain("Cancelled.");
+    expect(out).not.toContain("INTERNAL_ERROR");
+    expect(out).not.toMatch(/report this issue/i);
+    // A deliberate cancel is a success exit under the frozen exit-code covenant.
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("renders an interrupt (SIGINT / mid-run Ctrl-C) as a clean cancel, exit 130 (M1)", async () => {
+    // A --yes/CI run aborted by SIGINT fails the task with TASK_INTERRUPTED.
+    // The boundary must render it as a clean cancel (not a bug), but exit with
+    // the UNIX 128+SIGINT code 130 — out-of-band from the frozen {0,1,2,3}.
+    const interrupting: VerbSpec = {
+      ...make,
+      run: () =>
+        fail({ code: "TASK_INTERRUPTED", message: "Task interrupted" }),
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    process.exitCode = 0;
+    await dispatch(interrupting, [], { yes: true }, PLAIN);
+    spy.mockRestore();
+    const out = errs.join("");
+    expect(out).toContain("Cancelled.");
+    expect(out).not.toContain("INTERNAL_ERROR");
+    expect(out).not.toMatch(/report this issue/i);
+    expect(process.exitCode).toBe(130);
+  });
+});
+
+describe("executeVerb — interactivity gate (H3)", () => {
+  const setTTY = (
+    stream: NodeJS.ReadStream | NodeJS.WriteStream,
+    value: boolean | undefined,
+  ): void => {
+    (stream as { isTTY?: boolean }).isTTY = value;
+  };
+  const savedIn = process.stdin.isTTY;
+  const savedOut = process.stdout.isTTY;
+  const savedErr = process.stderr.isTTY;
+  afterEach(() => {
+    setTTY(process.stdin, savedIn);
+    setTTY(process.stdout, savedOut);
+    setTTY(process.stderr, savedErr);
+  });
+
+  /** A mutating verb that records the interaction context it was handed. */
+  const captureTTY = (sink: { isTTY?: boolean }): VerbSpec => ({
+    ...make,
+    run: (_p, rt) => {
+      sink.isTTY = rt.interaction?.isTTY;
+      return succeed({ made: true });
+    },
+  });
+
+  it("is NON-interactive when stderr is redirected, even with a stdout TTY (2>/dev/null)", async () => {
+    setTTY(process.stdin, true);
+    setTTY(process.stdout, true);
+    setTTY(process.stderr, false); // the Ink UI's stream is gone
+    const sink: { isTTY?: boolean } = {};
+    await executeVerb(
+      captureTTY(sink),
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(sink.isTTY).toBe(false);
+  });
+
+  it("is interactive on a stdin+stderr TTY, even when stdout is piped (gate is stderr, not stdout)", async () => {
+    setTTY(process.stdin, true);
+    setTTY(process.stdout, false); // piped stdout must NOT force non-interactive
+    setTTY(process.stderr, true);
+    const sink: { isTTY?: boolean } = {};
+    await executeVerb(
+      captureTTY(sink),
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(sink.isTTY).toBe(true);
+  });
+});