@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -105,6 +105,121 @@ describe("buildProgram — default-true boolean negation (B9)", () => {
   });
 });
 
+describe("buildProgram — one spelling per flag", () => {
+  it("registers no short option anywhere in the tree", () => {
+    const program = projectCli([fixtureModule]);
+    const walk = (cmd: import("commander").Command): void => {
+      expect(cmd.options.some((o) => o.short !== undefined)).toBe(false);
+      for (const child of cmd.commands) walk(child);
+    };
+    walk(program);
+  });
+
+  it("still answers --help while -v/-h reject as unknown options", async () => {
+    const spyErr = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    const spyOut = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "--help"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.helpDisplayed" });
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "list", "-h"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.unknownOption" });
+    await expect(
+      projectCli([fixtureModule]).parseAsync(["widget", "list", "-v"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.unknownOption" });
+    spyErr.mockRestore();
+    spyOut.mockRestore();
+  });
+});
+
+describe("buildProgram — repeatable filter flags", () => {
+  /** A verb with a repeatable enum filter and a repeatable string filter. */
+  const filterVerb: VerbSpec = {
+    path: ["thing", "list"],
+    summary: "thing list summary",
+    params: [
+      {
+        kind: "enum",
+        name: "category",
+        doc: "Filter by category.",
+        values: ["css", "git"],
+        repeatable: true,
+      },
+      { kind: "string", name: "tag", doc: "Filter by tag.", repeatable: true },
+    ],
+    output: {
+      formatters: {
+        plain: (d) => JSON.stringify(d),
+        llm: (d) => JSON.stringify(d),
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async (params) => params,
+  };
+
+  /** Parse argv and capture the option bag the action receives. */
+  async function optsFor(argv: string[]): Promise<Record<string, unknown>> {
+    let seen: Record<string, unknown> = {};
+    const program = projectCli([
+      {
+        name: "thing",
+        verbs: [
+          {
+            ...filterVerb,
+            run: async (params) => {
+              seen = params;
+              return null;
+            },
+          },
+        ],
+      },
+    ]);
+    await program.parseAsync(["thing", "list", ...argv], { from: "user" });
+    return seen;
+  }
+
+  it("accumulates a repeated filter into the union, never last-wins", async () => {
+    const params = await optsFor([
+      "--category",
+      "css",
+      "--category",
+      "git",
+      "--tag",
+      "a",
+      "--tag",
+      "b",
+    ]);
+    expect(params.category).toEqual(["css", "git"]);
+    expect(params.tag).toEqual(["a", "b"]);
+  });
+
+  it("keeps a single occurrence a one-element array and validates enum values", async () => {
+    const params = await optsFor(["--category", "css"]);
+    expect(params.category).toEqual(["css"]);
+    const program = projectCli([{ name: "thing", verbs: [filterVerb] }]);
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await expect(
+      program.parseAsync(["thing", "list", "--category", "bogus"], {
+        from: "user",
+      }),
+    ).rejects.toMatchObject({ code: "commander.invalidArgument" });
+    spy.mockRestore();
+  });
+});
+
 describe("buildProgram — early exits", () => {
   it("throws commander.version for --version, writing the version", async () => {
     const program = projectCli([fixtureModule]);
@@ -372,11 +487,17 @@ describe("buildProgram — sub-verb-only noun invoked bare (U2)", () => {
 });
 
 describe("formatRootHelp — grouping", () => {
-  const help = formatRootHelp("pragma", "pragma test", [
-    makeVerb(["info"]),
-    makeVerb(["config", "show"]),
-    makeVerb(["block", "list"]),
-  ]);
+  const help = formatRootHelp(
+    "pragma",
+    "pragma test",
+    [
+      makeVerb(["info"]),
+      makeVerb(["config", "show"]),
+      makeVerb(["block", "list"]),
+    ],
+    "1.2.3",
+    "https://example.test/issues",
+  );
 
   it("leads with the uncurated nouns, untitled, under the usage line", () => {
     // `block` is not in the kernel's curated table, so it leads the page with
@@ -389,11 +510,13 @@ describe("formatRootHelp — grouping", () => {
     expect(help.match(/pragma test/g)).toHaveLength(1);
   });
 
-  it("lists the live nouns and always-available mcp", () => {
+  it("lists the live nouns, and only those", () => {
     expect(help).toContain("block");
     expect(help).toContain("config");
     expect(help).toContain("info");
-    expect(help).toContain("mcp");
+    // `mcp` is curated for PLACEMENT, not conjured into existence: a registry
+    // without an mcp verb has no mcp row.
+    expect(help).not.toContain("mcp");
   });
 
   it("drops nouns that are not present", () => {
@@ -410,7 +533,20 @@ describe("formatRootHelp — grouping", () => {
 
   it("renders the unified root page (restyle golden)", () => {
     expect(help).toMatchInlineSnapshot(`
-      "pragma — pragma test
+      "              _
+                  /' \`\\
+                /'     )
+              /' (___,/'____     ____     ____     ,__________     ____
+            /'        )'    )--/'    )  /'    )   /'    )     )  /'    )
+          /'        /'       /'    /' /'    /'  /'    /'    /' /'    /'
+      (,/'        /'        (___,/(__(___,/(__/'    /'    /(__(___,/(__
+                                        /'
+                                /     /'
+                               (___,/'
+
+      pragma v1.2.3 — pragma test
+
+      This is a preview version. Issues and suggestions: https://example.test/issues
 
       Usage: pragma <command> [subcommand] [flags]
 
@@ -420,13 +556,12 @@ describe("formatRootHelp — grouping", () => {
         config  Read and write pragma configuration
         info    Show version, config, and update status
 
-      For AI agents
-        mcp     Start the MCP server over stdio
-
       Global flags
         --format <plain|llm|json>  Select output format (llm = condensed Markdown for agents)
         --detail <level>           Progressive-disclosure level (summary, standard, detailed)
-        --verbose                  Diagnostic output on stderr
+        --no-headers               Hide the table header row in plain output
+        --quiet                    Suppress success and progress output (errors still print)
+        --verbose                  Diagnostic output on stderr (sources update)
         --help                     Show help (works on any command)
         --version                  Show the CLI version
 

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

@@ -11,11 +11,17 @@
  * 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 { Command, InvalidArgumentError, Option } from "commander";
+import {
+  BIN_NAME,
+  ISSUES_URL,
+  PROGRAM_DESCRIPTION,
+  VERSION,
+} from "../../../constants.js";
+import type { GlobalFlags } from "../../runtime/index.js";
+import { kebabCase } from "../../spec/index.js";
+import type { CliProjection, ParamSpec, VerbSpec } from "../../spec/types.js";
+import { MUTATION_FLAG_DOCS, negationFlagDoc } from "./constants.js";
 import { dispatch } from "./dispatch.js";
 import { formatRootHelp } from "./rootHelp.js";
 import { formatNounHelp, formatVerbHelp } from "./verbHelp.js";
@@ -30,6 +36,15 @@ export interface BuildProgramOptions {
   readonly description?: string;
   /** Version string for `--version`. */
   readonly version?: string;
+  /** Where root help's preview notice sends feedback. */
+  readonly issuesUrl?: string;
+  /**
+   * Module-owned noun mounts (see `CapabilityModule.cliProjection`), keyed by
+   * noun. A mounted noun's parent command is created here exactly once and
+   * handed to the module's `mount` — the module owns everything beneath it;
+   * its verbs stay the binding-level grammar for help/surface/completion.
+   */
+  readonly mounts?: ReadonlyMap<string, CliProjection>;
 }
 
 /** The positional usage token for a param (`<name>` / `[name]`, variadic `...`). */
@@ -61,7 +76,30 @@ 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") {
+    if (
+      (param.kind === "enum" || param.kind === "string") &&
+      param.repeatable === true
+    ) {
+      // A repeatable flag ACCUMULATES — Commander's default keeps only the
+      // last occurrence, which silently drops data. The collector validates
+      // an enum's values itself, since a custom parser replaces the parser
+      // `.choices()` would install.
+      command.addOption(
+        new Option(spec, param.doc).argParser(
+          (value: string, previous: string[] | undefined) => {
+            if (
+              param.kind === "enum" &&
+              !(param.values as readonly string[]).includes(value)
+            ) {
+              throw new InvalidArgumentError(
+                `Allowed choices are ${param.values.join(", ")}.`,
+              );
+            }
+            return [...(previous ?? []), value];
+          },
+        ),
+      );
+    } else 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);
@@ -70,23 +108,28 @@ function registerParams(command: Command, verb: VerbSpec): void {
     } 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:
+    // B9: a default-`true` boolean is otherwise undisableable — the grammar
+    // has no negation form, so a kernel-registered default-true boolean could
+    // never be turned off. Register a paired `--no-<flag>` so it 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.
+    // (verified: an unset default-false boolean is left alone). For verbs
+    // registered HERE this is a CLI PARSE convenience, never a ParamSpec —
+    // `emitSurface`/MCP/the covenant keep the positive kebab token and
+    // negation stays additive. A MOUNTED noun (`create`) never reaches this
+    // loop: its leaves register through the projection's `buildOptionInfo`,
+    // where a default-true confirm registers ONLY the `--no-` form — so its
+    // covenant/reference tokens come from the module's registered-syntax
+    // seam, not this convention (L-CIS-2).
     if (param.kind === "boolean" && param.default === true) {
       const flag = kebabCase(param.name);
-      command.option(`--no-${flag}`, `Disable --${flag} (on by default).`);
+      command.option(`--no-${flag}`, negationFlagDoc(flag));
     }
   }
 
   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");
+    for (const { flag, doc } of MUTATION_FLAG_DOCS) {
+      command.option(flag, doc);
+    }
   }
 }
 
@@ -241,15 +284,21 @@ export function buildProgram(
   const programName = options.programName ?? BIN_NAME;
   const description = options.description ?? PROGRAM_DESCRIPTION;
   const version = options.version ?? VERSION;
+  const issuesUrl = options.issuesUrl ?? ISSUES_URL;
   const live = verbs.filter((verb) => !verb.hidden);
 
   const program = new Command();
   program.name(programName).description(description);
-  program.version(version, "-v, --version");
+  // One spelling per flag: no shorts. `--version` drops `-v` (which reads as
+  // *verbose* everywhere else), and the help option is `--help` alone —
+  // subcommands created from here on inherit it (Commander copies the help
+  // option into children at creation), including a mounted subtree's.
+  program.version(version, "--version");
+  program.helpOption("--help", "Show help (works on any command)");
   program.enablePositionalOptions();
   program.exitOverride();
   useDesignedHelp(program, () =>
-    formatRootHelp(programName, description, live),
+    formatRootHelp(programName, description, live, version, issuesUrl),
   );
 
   const groups = new Map<string, VerbSpec[]>();
@@ -264,6 +313,16 @@ export function buildProgram(
     const selfVerbs = bucket.filter((v) => v.path.length === 1);
     const subVerbs = bucket.filter((v) => v.path.length > 1);
 
+    // A module-owned mount replaces the generic per-verb attachment for its
+    // noun: create the parent once, hand it over, move on.
+    const mounted = options.mounts?.get(noun);
+    if (mounted) {
+      const parent = program.command(noun);
+      parent.enablePositionalOptions();
+      mounted.mount(parent, { globalFlags: options.globalFlags, programName });
+      continue;
+    }
+
     // Pure self-verb noun(s) — attach each leaf directly to the root, as before.
     if (subVerbs.length === 0) {
       for (const verb of selfVerbs) {

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

@@ -0,0 +1,34 @@
+/**
+ * CLI projector constants — the flag/doc pairs that must read identically
+ * wherever they surface.
+ *
+ * The mutation flags are auto-injected onto every mutating verb by
+ * `registerParams` (and by the mounted create subtree's own registration),
+ * and `formatVerbHelp` renders them in the Flags block; a default-true
+ * boolean's `--no-` negation is likewise both registered and rendered. Help
+ * and registration deriving from the SAME rows here is what keeps a page
+ * from denying a flag that parses — the defect this file exists to prevent.
+ */
+
+/** One auto-injected flag: the token and the doc both surfaces print. */
+export interface FlagDoc {
+  readonly flag: string;
+  readonly doc: string;
+}
+
+/** The three mutation flags every mutating verb accepts, in display order. */
+export const MUTATION_FLAG_DOCS: readonly FlagDoc[] = [
+  { flag: "--dry-run", doc: "Preview effects without applying them" },
+  { flag: "--undo", doc: "Reverse a previous run of this command" },
+  { flag: "--yes", doc: "Apply without an interactive confirmation" },
+];
+
+/**
+ * The doc for the `--no-<flag>` negation a default-true boolean registers.
+ *
+ * @param kebab - The positive flag's kebab token (no dashes).
+ * @returns The doc string registration and help share.
+ */
+export function negationFlagDoc(kebab: string): string {
+  return `Disable --${kebab} (on by default).`;
+}

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

@@ -1,14 +1,14 @@
 import { existsSync, mkdtempSync, readdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { fail, succeed } from "@canonical/task";
+import { $, fail, gen, log, mkdir, succeed, writeFile } from "@canonical/task";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { fixturePreviewModule } from "../../../testing/fixtures/fixtureCapability.js";
 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";
+import { cliIsTTY, dispatch, executeVerb, extractParams } from "./dispatch.js";
 
 /** The read-then-write mutation the honest-preview guards drive. */
 const graft = fixturePreviewModule.verbs[0] as VerbSpec;
@@ -150,6 +150,46 @@ describe("executeVerb — mutations", () => {
     expect(outcome.stdout).toContain("Dry run");
   });
 
+  it("a verb with NO formatPlan renders the effect dump, byte for byte", async () => {
+    // The `formatPlan` seam is opt-in, and opting out is the majority case.
+    // These are the exact bytes the kernel produced before any verb had a
+    // renderer of its own — the whole literal, not a substring — so a verb
+    // that declares nothing can never be re-rendered by accident.
+    const dumped: VerbSpec = {
+      ...make,
+      run: () =>
+        gen(function* () {
+          yield* $(log("info", "starting"));
+          yield* $(mkdir("out"));
+          yield* $(writeFile("out/thing.txt", "hello"));
+          return { dumped: true };
+        }),
+    };
+    const outcome = await executeVerb(
+      dumped,
+      {},
+      { dryRun: true, undo: false, yes: false },
+      bootRuntime(PLAIN, mkdtempSync(join(tmpdir(), "pragma-dump-"))),
+    );
+    expect(outcome.stdout).toBe(
+      "Dry run — planned effects:\n" +
+        "  - Log [info]: starting\n" +
+        "  - Created out/\n" +
+        "  - Write file: out/thing.txt (5 bytes)\n",
+    );
+    expect(outcome.exitCode).toBe(0);
+  });
+
+  it("an empty plan renders the no-effects line, byte for byte", async () => {
+    const outcome = await executeVerb(
+      make,
+      {},
+      { dryRun: true, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(outcome.stdout).toBe("Dry run — no effects.\n");
+  });
+
   it("reports undo count under --undo", async () => {
     const outcome = await executeVerb(
       make,
@@ -161,6 +201,104 @@ describe("executeVerb — mutations", () => {
   });
 });
 
+describe("--quiet — success is silent, failure is not", () => {
+  // The rule the flag has to keep: everything muted is success-path narration
+  // (the calm zero-record notice, a mutation's stage lines). Error rendering
+  // does not route through either seam, so no failure can hide behind it.
+  const QUIET: GlobalFlags = { ...PLAIN, quiet: true };
+  const savedExit = process.exitCode;
+  afterEach(() => {
+    process.exitCode = savedExit;
+  });
+
+  const emptyList: VerbSpec = {
+    ...echo,
+    params: [],
+    output: {
+      formatters: {
+        ...passthroughFormatters,
+        plain: () => "",
+        emptyNotice: () => "No results.",
+      },
+    },
+    run: async () => [],
+  };
+
+  it("mutes the empty-state notice but keeps stdout and the exit code", async () => {
+    const loud = await executeVerb(
+      emptyList,
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(PLAIN),
+    );
+    expect(loud.stderr).toBe("No results.\n");
+
+    const quiet = await executeVerb(
+      emptyList,
+      {},
+      { dryRun: false, undo: false, yes: false },
+      bootRuntime(QUIET),
+    );
+    expect(quiet.stderr).toBeUndefined();
+    expect(quiet.stdout).toBe(loud.stdout);
+    expect(quiet.exitCode).toBe(0);
+  });
+
+  it("mutes a mutation's progress lines", async () => {
+    const reporting: VerbSpec = {
+      ...make,
+      run: (_params, runtime) => {
+        runtime.report?.("Resolving the pack…");
+        return succeed({ made: true });
+      },
+    };
+    const errs: string[] = [];
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        errs.push(String(chunk));
+        return true;
+      });
+    await executeVerb(
+      reporting,
+      {},
+      { dryRun: false, undo: false, yes: true },
+      bootRuntime(PLAIN),
+    );
+    const loud = errs.join("");
+    errs.length = 0;
+    await executeVerb(
+      reporting,
+      {},
+      { dryRun: false, undo: false, yes: true },
+      bootRuntime(QUIET),
+    );
+    spy.mockRestore();
+    expect(loud).toContain("Resolving the pack…");
+    expect(errs.join("")).toBe("");
+  });
+
+  it("still renders the error, with its 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"], {}, QUIET);
+    spy.mockRestore();
+    expect(errs.join("")).toContain('thing "Nope" not found.');
+    expect(process.exitCode).toBe(1);
+  });
+});
+
 describe("dispatch — errors", () => {
   const savedExit = process.exitCode;
   afterEach(() => {
@@ -190,7 +328,7 @@ describe("dispatch — errors", () => {
   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.
+    // the scary INTERNAL_ERROR "report this issue" / exit 1.
     const cancelling: VerbSpec = {
       ...make,
       run: () => fail({ code: "GENERATOR_CANCELLED", message: "Cancelled." }),
@@ -352,4 +490,23 @@ describe("executeVerb — interactivity gate (H3)", () => {
     );
     expect(sink.isTTY).toBe(true);
   });
+
+  it("cliIsTTY IS the stdin+stderr conjunction — the one gate both callers read", () => {
+    // The mount's create decision reads the same exported function this
+    // describe drives through executeVerb, so pinning the truth table here
+    // pins BOTH callers (nothing is left to keep two copies in step).
+    const cases: Array<[boolean, boolean, boolean, boolean]> = [
+      [true, true, false, true], // stdout is irrelevant…
+      [true, true, true, true],
+      [false, true, true, false], // …stdin is required…
+      [true, false, true, false], // …and so is stderr.
+      [false, false, false, false],
+    ];
+    for (const [stdin, stderr, stdout, expected] of cases) {
+      setTTY(process.stdin, stdin);
+      setTTY(process.stderr, stderr);
+      setTTY(process.stdout, stdout);
+      expect(cliIsTTY(), `stdin=${stdin} stderr=${stderr}`).toBe(expected);
+    }
+  });
 });