@canonical/pragma-cli 0.30.0 → 0.32.0

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

@@ -0,0 +1,387 @@
+import chalk from "chalk";
+import { afterAll, describe, expect, it, vi } from "vitest";
+import { VERSION } from "../../../constants.js";
+import { fixtureModule } from "../../../testing/fixtures/fixtureCapability.js";
+import { projectCli } from "../../../testing/helpers/projectCli.js";
+import type { CapabilityModule, VerbSpec } from "../../spec/types.js";
+import { formatRootHelp } from "./rootHelp.js";
+
+// Root/noun/verb help styling (helpFormat.ts) routes through chalk, whose
+// `supports-color` enables color when GITHUB_ACTIONS is set — even off a TTY —
+// so CI would paint ANSI into these plain goldens and the bare-noun `--help`
+// comparison. Pin the level to 0 for deterministic, color-free renders (the same
+// guard colophon.render.test.ts / verbHelp.test.ts use). Module scope so the
+// collection-time formatRootHelp() call below renders plain too.
+const prevChalkLevel = chalk.level;
+chalk.level = 0;
+afterAll(() => {
+  chalk.level = prevChalkLevel;
+});
+
+/** A minimal verb under an arbitrary path, for help-grouping tests. */
+function makeVerb(path: [string, string?]): VerbSpec {
+  return {
+    path,
+    summary: `${path.filter(Boolean).join(" ")} summary`,
+    params: [],
+    output: {
+      formatters: {
+        plain: (d) => String(d),
+        llm: (d) => String(d),
+        json: (d) => JSON.stringify(d),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async () => null,
+  };
+}
+
+describe("buildProgram — flags", () => {
+  const program = projectCli([fixtureModule]);
+  const widget = program.commands.find((c) => c.name() === "widget");
+  const make = widget?.commands.find((c) => c.name() === "make");
+  const list = widget?.commands.find((c) => c.name() === "list");
+
+  it("registers a camelCase flag in kebab form", () => {
+    expect(make?.options.map((o) => o.long)).toContain("--with-history");
+  });
+
+  it("auto-injects --dry-run/--undo/--yes onto a mutating verb", () => {
+    expect(make?.options.map((o) => o.long)).toEqual(
+      expect.arrayContaining(["--dry-run", "--undo", "--yes"]),
+    );
+  });
+
+  it("does not inject mutation flags onto a read verb", () => {
+    expect(list?.options.map((o) => o.long)).not.toContain("--dry-run");
+  });
+
+  it("carries the positional into the command usage", () => {
+    expect(make?.usage()).toContain("<name>");
+  });
+});
+
+describe("buildProgram — early exits", () => {
+  it("throws commander.version for --version, writing the version", async () => {
+    const program = projectCli([fixtureModule]);
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        writes.push(String(chunk));
+        return true;
+      });
+    await expect(
+      program.parseAsync(["--version"], { from: "user" }),
+    ).rejects.toMatchObject({ code: "commander.version" });
+    spy.mockRestore();
+    expect(writes.join("")).toContain(VERSION);
+  });
+
+  it("throws commander.helpDisplayed for --help", async () => {
+    const program = projectCli([fixtureModule]);
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    await expect(
+      program.parseAsync(["--help"], { from: "user" }),
+    ).rejects.toMatchObject({ code: "commander.helpDisplayed" });
+    spy.mockRestore();
+  });
+
+  it("throws commander.unknownCommand for an unknown noun", async () => {
+    const program = projectCli([fixtureModule]);
+    const spy = vi
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+    await expect(
+      program.parseAsync(["widgt"], { from: "user" }),
+    ).rejects.toMatchObject({ code: "commander.unknownCommand" });
+    spy.mockRestore();
+  });
+});
+
+describe("buildProgram — lazy dispatch", () => {
+  it("does not evaluate a verb's run body while building the tree", () => {
+    const boom: CapabilityModule = {
+      name: "boom",
+      verbs: [
+        {
+          path: ["boom", "go"],
+          summary: "Explodes if its run body is invoked at build time.",
+          params: [],
+          output: {
+            formatters: {
+              plain: (d) => String(d),
+              llm: (d) => String(d),
+              json: (d) => JSON.stringify(d),
+            },
+          },
+          capability: {
+            needsStore: false,
+            mutates: false,
+            mcp: { expose: false, reason: "test" },
+          },
+          run: () => {
+            throw new Error("run body evaluated during build");
+          },
+        },
+      ],
+    };
+    expect(() => projectCli([boom])).not.toThrow();
+  });
+});
+
+/** A read verb whose run body renders a distinguishable marker, for routing. */
+function recordingVerb(path: [string, string?], marker: string): VerbSpec {
+  return {
+    path,
+    summary: `${path.filter(Boolean).join(" ")} summary`,
+    params: [],
+    output: {
+      formatters: {
+        plain: () => marker,
+        llm: () => marker,
+        json: () => JSON.stringify({ marker }),
+      },
+    },
+    capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+    run: async () => marker,
+  };
+}
+
+/** A mutating self-verb, to prove mutation flags land on the noun parent. */
+function mutatingSelfVerb(noun: string): VerbSpec {
+  return {
+    path: [noun],
+    summary: `${noun} summary`,
+    params: [],
+    output: {
+      formatters: {
+        plain: () => noun,
+        llm: () => noun,
+        json: () => JSON.stringify({ noun }),
+      },
+    },
+    capability: { needsStore: false, mutates: true, mcp: { expose: true } },
+    // A mutation returns a Task; a bare no-op is enough for structural checks.
+    run: () => ({ _tag: "Pure", value: noun }) as never,
+  };
+}
+
+describe("buildProgram — mixed self+sub-verb noun (setup shape)", () => {
+  /** A noun that is BOTH directly runnable and has sub-verbs — setup's shape. */
+  const mixed: CapabilityModule = {
+    name: "kitish",
+    verbs: [
+      recordingVerb(["kit"], "SELF"),
+      recordingVerb(["kit", "mcp"], "SUB_MCP"),
+      recordingVerb(["kit", "skills"], "SUB_SKILLS"),
+    ],
+  };
+
+  it("registers the noun parent exactly once", () => {
+    const program = projectCli([mixed]);
+    const kits = program.commands.filter((c) => c.name() === "kit");
+    expect(kits).toHaveLength(1);
+    const kit = kits[0];
+    expect(kit?.commands.map((c) => c.name()).sort()).toEqual([
+      "mcp",
+      "skills",
+    ]);
+  });
+
+  it("`kit` (bare) dispatches the self-verb", async () => {
+    const program = projectCli([mixed]);
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        writes.push(String(chunk));
+        return true;
+      });
+    await program.parseAsync(["kit"], { from: "user" });
+    spy.mockRestore();
+    expect(writes.join("")).toContain("SELF");
+    expect(writes.join("")).not.toContain("SUB_");
+  });
+
+  it("`kit mcp` dispatches the sub-verb, not the self-verb", async () => {
+    const program = projectCli([mixed]);
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        writes.push(String(chunk));
+        return true;
+      });
+    await program.parseAsync(["kit", "mcp"], { from: "user" });
+    spy.mockRestore();
+    expect(writes.join("")).toContain("SUB_MCP");
+    expect(writes.join("")).not.toContain("SELF");
+  });
+
+  it("carries a mutating self-verb's mutation flags onto the noun parent", () => {
+    const module: CapabilityModule = {
+      name: "kit2ish",
+      verbs: [mutatingSelfVerb("kit2"), recordingVerb(["kit2", "one"], "ONE")],
+    };
+    const program = projectCli([module]);
+    const kit2 = program.commands.find((c) => c.name() === "kit2");
+    expect(kit2?.options.map((o) => o.long)).toEqual(
+      expect.arrayContaining(["--dry-run", "--undo", "--yes"]),
+    );
+    // The sub-verb is still reachable under the same parent.
+    expect(kit2?.commands.map((c) => c.name())).toContain("one");
+  });
+
+  it("throws at build time when a mixed-noun self-verb declares a positional", () => {
+    // The documented invariant, now enforced: a self-verb sharing a noun with
+    // sub-verbs must have NO positional (else `<noun> <sub>` would shadow the
+    // positional value and Commander would silently drop it from the model).
+    const selfWithPositional: VerbSpec = {
+      path: ["kit3"],
+      summary: "kit3 summary",
+      params: [
+        {
+          kind: "string",
+          name: "target",
+          doc: "a positional",
+          positional: true,
+        },
+      ],
+      output: {
+        formatters: { plain: () => "", llm: () => "", json: () => "{}" },
+      },
+      capability: { needsStore: false, mutates: false, mcp: { expose: true } },
+      run: async () => null,
+    };
+    const module: CapabilityModule = {
+      name: "kit3ish",
+      verbs: [selfWithPositional, recordingVerb(["kit3", "one"], "ONE")],
+    };
+    expect(() => projectCli([module])).toThrow(/must have no positional/);
+  });
+});
+
+describe("buildProgram — sub-verb-only noun invoked bare (U2)", () => {
+  /** A noun with ONLY sub-verbs and no self-verb — block/config/… shape. */
+  const subOnly: CapabilityModule = {
+    name: "gadgetish",
+    verbs: [
+      recordingVerb(["gadget", "list"], "GADGET_LIST"),
+      recordingVerb(["gadget", "show"], "GADGET_SHOW"),
+    ],
+  };
+
+  /** Parse `argv`, capturing everything written to stdout and any thrown exit. */
+  async function run(argv: string[]): Promise<{ out: string; threw: unknown }> {
+    const program = projectCli([subOnly]);
+    const writes: string[] = [];
+    const spy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation((chunk: string | Uint8Array) => {
+        writes.push(String(chunk));
+        return true;
+      });
+    let threw: unknown;
+    try {
+      await program.parseAsync(argv, { from: "user" });
+    } catch (error) {
+      threw = error;
+    } finally {
+      spy.mockRestore();
+    }
+    return { out: writes.join(""), threw };
+  }
+
+  it("`gadget` (bare) prints the SAME page as `gadget --help`, exit 0", async () => {
+    const bare = await run(["gadget"]);
+    const help = await run(["gadget", "--help"]);
+
+    // The bare action returns normally (exit 0) — it never throws the way
+    // `--help` does (commander.helpDisplayed).
+    expect(bare.threw).toBeUndefined();
+    expect(bare.out).toContain("Usage: pragma gadget <verb> [flags]");
+    expect(bare.out).toContain("list");
+    expect(bare.out).toContain("show");
+    // Byte-for-byte identical to the designed `--help` page.
+    expect(bare.out).toBe(help.out);
+  });
+
+  it("`gadget list` still routes to the sub-verb, not the bare-help action", async () => {
+    const routed = await run(["gadget", "list"]);
+    expect(routed.out).toContain("GADGET_LIST");
+    expect(routed.out).not.toContain("Usage: pragma gadget <verb>");
+  });
+
+  it("`gadget bogus` re-raises unknownCommand so the bin can suggest a verb", async () => {
+    // The regression guard: the bare-help action must NOT swallow an
+    // unrecognized sub-verb into a generic "too many arguments" — it re-raises
+    // the same commander.unknownCommand the suggester routes on.
+    const bogus = await run(["gadget", "bogus"]);
+    expect(bogus.out).not.toContain("Usage: pragma gadget <verb>");
+    expect((bogus.threw as { code?: string })?.code).toBe(
+      "commander.unknownCommand",
+    );
+  });
+});
+
+describe("formatRootHelp — grouping", () => {
+  const help = formatRootHelp("pragma", "pragma test", [
+    makeVerb(["info"]),
+    makeVerb(["config", "show"]),
+    makeVerb(["block", "list"]),
+  ]);
+
+  it("shows the task-oriented section titles for live nouns", () => {
+    expect(help).toContain("Explore the design system");
+    expect(help).toContain("Set up & maintain");
+  });
+
+  it("lists the live nouns and always-available mcp", () => {
+    expect(help).toContain("block");
+    expect(help).toContain("config");
+    expect(help).toContain("info");
+    expect(help).toContain("mcp");
+  });
+
+  it("drops nouns that are not present", () => {
+    expect(help).not.toContain("token");
+    expect(help).not.toContain("graphql");
+  });
+
+  it("shows the global flags block", () => {
+    expect(help).toContain("Global flags");
+    expect(help).toContain("--llm");
+    expect(help).toContain("--detail <level>");
+  });
+
+  it("renders the unified root page (restyle golden)", () => {
+    expect(help).toMatchInlineSnapshot(`
+      "pragma — pragma test
+
+      Usage: pragma <command> [subcommand] [flags]
+
+      Explore the design system
+        block   Inspect components & patterns and their anatomy
+
+      Set up & maintain
+        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
+        --llm                  Condensed Markdown output for agents
+        --format <json|plain>  Select output format
+        --detail <level>       Progressive-disclosure level (summary, standard, detailed)
+        --verbose              Diagnostic output on stderr
+        --help                 Show help (works on any command)
+        --version              Show the CLI version
+
+      Run \`pragma <command> --help\` for details, or \`pragma capabilities\` to get oriented."
+    `);
+  });
+});

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

@@ -0,0 +1,280 @@
+/**
+ * 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);
+    }
+  }
+
+  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;
+}