@canonical/pragma-cli 0.33.0 → 0.35.0

package/dist/src/kernel/project/cli/buildProgram.js

@@ -0,0 +1,263 @@
+/**
+ * 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, InvalidArgumentError, Option } from "commander";
+import { BIN_NAME, ISSUES_URL, PROGRAM_DESCRIPTION, VERSION, } from "../../../constants.js";
+import { kebabCase } from "../../spec/index.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";
+/** The positional usage token for a param (`<name>` / `[name]`, variadic `...`). */
+function positionalToken(param) {
+    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) {
+    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, text) {
+    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, verb) {
+    for (const param of verb.params) {
+        if (param.positional)
+            continue;
+        const spec = flagSpec(param);
+        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, previous) => {
+                if (param.kind === "enum" &&
+                    !param.values.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);
+        }
+        else if ("default" in param && param.default !== undefined) {
+            command.option(spec, param.doc, param.default);
+        }
+        else {
+            command.option(spec, param.doc);
+        }
+        // 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). 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}`, negationFlagDoc(flag));
+        }
+    }
+    if (verb.capability.mutates) {
+        for (const { flag, doc } of MUTATION_FLAG_DOCS) {
+            command.option(flag, doc);
+        }
+    }
+}
+/** Split Commander's variadic action args into positionals and options. */
+function splitActionArgs(actionArgs) {
+    const positionals = [];
+    let opts = {};
+    for (const arg of actionArgs) {
+        if (typeof arg === "string") {
+            positionals.push(arg);
+        }
+        else if (Array.isArray(arg)) {
+            positionals.push(...arg.filter((value) => typeof value === "string"));
+        }
+        else if (arg instanceof Command) {
+            // The trailing Command instance — skip.
+        }
+        else if (typeof arg === "object" && arg !== null) {
+            opts = arg;
+        }
+    }
+    return { positionals, opts };
+}
+/** Attach one verb as a leaf command under `parent`. */
+function attachVerb(parent, verb, name, programName, globalFlags) {
+    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) => {
+        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, noun, selfVerb, subVerbs, programName, globalFlags, live) {
+    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) => {
+            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], 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, options) {
+    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);
+    // 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, version, issuesUrl));
+    const groups = new Map();
+    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);
+        // 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) {
+                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;
+}
+//# sourceMappingURL=buildProgram.js.map

package/dist/src/kernel/project/cli/buildProgram.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildProgram.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/buildProgram.ts"],"names":[],"mappings":"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"}

package/dist/src/kernel/project/cli/constants.js

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/** The three mutation flags every mutating verb accepts, in display order. */
+export const MUTATION_FLAG_DOCS = [
+    { 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) {
+    return `Disable --${kebab} (on by default).`;
+}
+//# sourceMappingURL=constants.js.map

package/dist/src/kernel/project/cli/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,kBAAkB,GAAuB;IACpD,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,uCAAuC,EAAE;IACnE,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,wCAAwC,EAAE;IACjE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,2CAA2C,EAAE;CACpE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,aAAa,KAAK,mBAAmB,CAAC;AAC/C,CAAC"}