@canonical/pragma-cli 0.34.0 → 0.35.0

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

@@ -0,0 +1,216 @@
+/**
+ * Global-flag pre-parsing, ahead of Commander.
+ *
+ * `--format`, `--verbose`, `--no-headers`, 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.
+ *
+ * ANYWHERE STOPS AT `--`. Everything after the option terminator is the user's
+ * data, not this program's flags: `block lookup -- --format` looks up a block
+ * literally named `--format`. Commander honours the terminator on its own, so
+ * a scan here that ignored it would parse — and strip — tokens Commander was
+ * about to hand through verbatim.
+ *
+ * A FLAG'S VALUE IS NEVER ANOTHER FLAG. `--detail --category css` supplies no
+ * detail; it is a valueless `--detail` followed by a separate flag. Reading the
+ * next token unconditionally would consume `--category` as the value and strip
+ * it, so the filter would vanish and the command would answer over the whole
+ * set instead — a wrong answer with no diagnostic.
+ * Ported from the v1 `parseGlobalFlags`, with two v2 changes: a new `--detail`
+ * flag and the `--format text` value replaced by `plain` (the kernel's
+ * {@link OutputFormat}) — `text` is not accepted; the bin rejects it with the
+ * valid list. The dedicated `--llm` flag was folded into `--format llm`,
+ * leaving auto-detection as the sole implicit trigger. Both the space
+ * (`--format json`) and equals (`--format=json`) forms are recognized.
+ */
+import { DETAIL_LEVELS } from "../../../constants.js";
+/** The end-of-options separator: nothing after it is a flag of this program. */
+const OPTION_TERMINATOR = "--";
+/**
+ * The span of argv this program's flags may occupy — everything before the
+ * option terminator, or all of argv when there is none. Exported for the
+ * bin's retired-flag detection: a retired spelling AFTER the terminator is
+ * an operand, not a flag, and must not trigger a migration message.
+ *
+ * @param argv - The user's arguments.
+ * @returns The scannable span; the same array when no terminator is present.
+ */
+export function selectScanSpan(argv) {
+    const terminator = argv.indexOf(OPTION_TERMINATOR);
+    return terminator === -1 ? argv : argv.slice(0, terminator);
+}
+/**
+ * Whether a token can serve as a flag's value.
+ *
+ * A token starting with `-` is the next flag, not this one's value. Shared by
+ * every reader below so the space form cannot swallow a sibling flag at one
+ * call site while guarding against it at another.
+ *
+ * @param token - The token following a flag, if any.
+ * @returns True when the token is a value rather than another flag.
+ */
+function isFlagValue(token) {
+    return token !== undefined && !token.startsWith("-");
+}
+/**
+ * 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, flag) {
+    const span = selectScanSpan(argv);
+    const equalsPrefix = `${flag}=`;
+    const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
+    if (equalsArg !== undefined) {
+        return equalsArg.slice(equalsPrefix.length);
+    }
+    const spaceIndex = span.indexOf(flag);
+    if (spaceIndex === -1)
+        return undefined;
+    const value = span.at(spaceIndex + 1);
+    return isFlagValue(value) ? value : undefined;
+}
+/**
+ * Read a value flag's raw value exactly as typed, for validation.
+ *
+ * Unlike {@link parseGlobalFlags} this does not normalize — the caller decides
+ * how to reject an unknown value. A bare flag with no following value is
+ * reported as `""` (not `undefined`) so it is rejected rather than silently
+ * falling through. One reader for every validated global value flag, so a
+ * guard applied to one cannot silently miss its siblings.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @param flag - The flag including leading dashes (e.g. `--format`).
+ * @returns The raw value, `""` for a valueless flag, or `undefined`.
+ */
+function readRawFlag(argv, flag) {
+    const span = selectScanSpan(argv);
+    const equalsPrefix = `${flag}=`;
+    const equalsArg = span.find((arg) => arg.startsWith(equalsPrefix));
+    if (equalsArg !== undefined)
+        return equalsArg.slice(equalsPrefix.length);
+    const spaceIndex = span.indexOf(flag);
+    if (spaceIndex === -1)
+        return undefined;
+    // `""` rather than `undefined`: a valueless flag must be REJECTED by the
+    // caller, not fall through to the default.
+    const value = span.at(spaceIndex + 1);
+    return isFlagValue(value) ? value : "";
+}
+/** The raw `--format` value as typed (see {@link readRawFlag}). */
+export function readRawFormat(argv) {
+    return readRawFlag(argv, "--format");
+}
+/**
+ * The raw `--detail` value as typed (see {@link readRawFlag}). Validated by
+ * the bin exactly as `--format` is — an unrecognized level used to be
+ * dropped silently, which is the same defect class as a filter that
+ * evaporates: wrong output with no diagnostic.
+ */
+export function readRawDetail(argv) {
+    return readRawFlag(argv, "--detail");
+}
+/**
+ * The `--verbose=<x>` token, if present. `--verbose` takes no value — one
+ * flag, one spelling — and the program must not accept-and-ignore a second
+ * one: the bin rejects the token this finds.
+ *
+ * @param argv - Raw argv (the user's arguments).
+ * @returns The offending token, or `undefined`.
+ */
+export function findValuedVerbose(argv) {
+    return selectScanSpan(argv).find((arg) => arg.startsWith("--verbose="));
+}
+/** Read the real stdout/env output environment. @note Impure — reads process. */
+function readOutputEnvironment() {
+    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) {
+    const raw = readFlagValue(argv, "--detail");
+    if (raw !== undefined && DETAIL_LEVELS.includes(raw)) {
+        return raw;
+    }
+    return undefined;
+}
+/**
+ * Extract the global flags from raw argv (the user's arguments, argv[2:]).
+ *
+ * Auto-LLM: with no explicit `--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. Any explicit `--format` overrides it —
+ * `--format plain` forces human output down a pipe, `--format llm` forces the
+ * condensed form even on a TTY — as does `PRAGMA_NO_AUTO_LLM`.
+ *
+ * @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, env = readOutputEnvironment()) {
+    const rawFormat = readFlagValue(argv, "--format");
+    const format = rawFormat === "json" ? "json" : rawFormat === "llm" ? "llm" : "plain";
+    const formatRequested = rawFormat !== undefined;
+    const autoLlm = !formatRequested && !env.isTty && !env.noAutoLlm;
+    const detail = readDetail(argv);
+    const span = selectScanSpan(argv);
+    return {
+        llm: format === "llm" || autoLlm,
+        autoLlm,
+        format,
+        verbose: span.includes("--verbose"),
+        // `--no-headers` suppresses the plain-table header row; it is global so
+        // every list-shaped verb honors one spelling.
+        ...(span.includes("--no-headers") ? { noHeaders: true } : {}),
+        // `--quiet` silences success/progress (the report seam, interpreter logs,
+        // onboarding, calm notices) while error rendering stays untouched.
+        ...(span.includes("--quiet") ? { quiet: true } : {}),
+        ...(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 — anywhere before the option terminator, which this
+ * stops at and hands through whole.
+ *
+ * @param argv - The user's arguments.
+ * @returns A new array with global flags stripped.
+ */
+export function stripGlobalFlags(argv) {
+    const result = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv.at(i);
+        if (arg === undefined)
+            continue;
+        // Past the terminator nothing is ours: hand the remainder over untouched,
+        // terminator included, so Commander still sees where options end.
+        if (arg === OPTION_TERMINATOR) {
+            result.push(...argv.slice(i));
+            return result;
+        }
+        if (arg === "--verbose" || arg === "--no-headers" || arg === "--quiet") {
+            continue;
+        }
+        if (arg.startsWith("--format=") || arg.startsWith("--detail=")) {
+            continue;
+        }
+        if (arg === "--format" || arg === "--detail") {
+            // Skip the value ONLY when the next token is one. A valueless flag before
+            // another flag must leave that flag standing.
+            if (isFlagValue(argv.at(i + 1)))
+                i += 1;
+            continue;
+        }
+        result.push(arg);
+    }
+    return result;
+}
+//# sourceMappingURL=globalFlags.js.map

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

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

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

@@ -0,0 +1,59 @@
+/**
+ * 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`, `Set up & maintain`). */
+export function helpHeading(text) {
+    return chalk.bold(text);
+}
+/** Dim secondary text — an example note, or the footer line. */
+export function helpDim(text) {
+    return chalk.dim(text);
+}
+/** A cyan term — a command, verb, flag, or example, as shown in the body. */
+export function helpTerm(text) {
+    return chalk.cyan(text);
+}
+/**
+ * The wordmark's colour.
+ *
+ * `yellow` is a PALETTE slot, not a fixed hue: the 16-colour ANSI palette has no
+ * orange, and this slot is the one terminal themes render as orange — Ubuntu's
+ * among them. Naming the slot rather than a 256-colour or truecolour orange is
+ * what lets the wordmark follow the user's own theme instead of fighting it, and
+ * keeps it legible on light backgrounds where a hardcoded orange would not be.
+ */
+export function helpLogo(text) {
+    return chalk.yellow(text);
+}
+/** The `Usage:` line: a dim label followed by the given command shape. */
+export function helpUsage(body) {
+    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, width) {
+    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());
+}
+//# sourceMappingURL=helpFormat.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpFormat.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/helpFormat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,gDAAgD;AAChD,MAAM,MAAM,GAAG,IAAI,CAAC;AACpB,+DAA+D;AAC/D,MAAM,GAAG,GAAG,IAAI,CAAC;AAEjB,qEAAqE;AACrE,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,OAAO,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,IAA+D,EAC/D,KAAc;IAEd,MAAM,MAAM,GAAG,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,CAAC,EAAE,EAAE,CACtC,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CACvF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,14 @@
+/**
+ * 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 { buildProgram } from "./buildProgram.js";
+export { dispatch, executeVerb, extractParams } from "./dispatch.js";
+export { EXIT, mapExitCode } from "./exitCodes.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";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEnD,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

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

@@ -0,0 +1,197 @@
+/**
+ * The curated root `--help` page.
+ *
+ * The kernel curates the nouns it ships — and only those. It names no domain:
+ * the nouns it does NOT curate lead the page untitled (the header one line up
+ * already carries the distribution's blurb) and describe themselves through
+ * their own verbs, so the front door follows the content instead of naming it.
+ * Every section is reconciled against the *live* nouns (from the registered
+ * verbs), so a noun that is not built yet is dropped and one the kernel has
+ * never heard of still surfaces.
+ */
+import { PROGRAM_LOGO } from "../../../constants.js";
+import { helpColumns, helpDim, helpHeading, helpLogo, helpTerm, helpUsage, } from "./helpFormat.js";
+/**
+ * The kernel's own nouns, grouped by task with curated summaries. Order is
+ * intentional: what people reach for most comes first; agent tooling comes last.
+ *
+ * @param programName - The CLI binary name (the distribution's `name`).
+ * @returns The task-oriented groups, in display order.
+ */
+function buildKernelGroups(programName) {
+    return [
+        {
+            title: "Generate code",
+            nouns: [
+                { noun: "create", summary: "Scaffold components, packages, and apps" },
+            ],
+        },
+        {
+            title: "Query & serve the graph",
+            nouns: [
+                {
+                    noun: "graph",
+                    summary: "Run SPARQL queries or inspect a URI directly",
+                },
+                {
+                    noun: "ontology",
+                    summary: "Explore the loaded ontologies (classes, properties)",
+                },
+            ],
+        },
+        {
+            title: "Set up & maintain",
+            nouns: [
+                { noun: "doctor", summary: "Check environment health" },
+                {
+                    noun: "setup",
+                    summary: "Configure MCP, skills, completions, and the LSP",
+                },
+                {
+                    noun: "sources",
+                    summary: "Build and refresh the local store from packs",
+                },
+                {
+                    noun: "config",
+                    summary: `Read and write ${programName} configuration`,
+                },
+                { noun: "info", summary: "Show version, config, and update status" },
+                { noun: "version", summary: "Print the CLI version" },
+                {
+                    noun: "upgrade",
+                    summary: `Upgrade the ${programName} CLI to the latest version`,
+                },
+            ],
+        },
+        {
+            title: "For AI agents",
+            nouns: [
+                {
+                    noun: "capabilities",
+                    summary: "Discover conventions, tools, and the discovery sequence",
+                },
+                // A colophon is the note at the back of a book: the typeface, the
+                // press, the paper. Nothing depends on it, which is the point — so
+                // this line does not argue for it. Every other summary in this column
+                // promises work done; this one just invites you to look.
+                { noun: "colophon", summary: "Read the credits" },
+                { noun: "skill", summary: "Browse agent skills from the active packs" },
+                { noun: "prompt", summary: "Browse reusable prompt templates" },
+                // Curated for PLACEMENT, not for existence: `mcp serve` is an
+                // ordinary verb like every other, and this group is where a reader
+                // looks for it.
+                { noun: "mcp", summary: "Start the MCP server over stdio" },
+            ],
+        },
+    ];
+}
+/** All distinct, non-hidden top-level nouns present in the registered verbs. */
+function nounsFrom(verbs) {
+    const nouns = new Set();
+    for (const verb of verbs) {
+        if (verb.hidden)
+            continue;
+        nouns.add(verb.path[0]);
+    }
+    return nouns;
+}
+/**
+ * Summarise an uncurated noun from its first live verb — which is the pack's own
+ * `description` whenever the pack ships a `list` (`compilePack` compiles that
+ * verb first). The terminal period a pack sentence carries is dropped so the
+ * column reads as one voice with the kernel's own fragments.
+ */
+function summarizeNoun(noun, verbs) {
+    const first = verbs.find((v) => v.path[0] === noun && !v.hidden);
+    return (first?.summary ?? `${noun} commands`).replace(/\.$/, "");
+}
+/**
+ * Build the curated root help string.
+ *
+ * @param programName - The CLI binary name (the distribution's `name`).
+ * @param description - The program description shown in the header.
+ * @param verbs - All registered verbs, used to derive the live noun set.
+ * @param issuesUrl - Where the preview notice sends feedback; the
+ *   distribution's own, so a fork points at its own tracker.
+ * @param version - The version to stamp on the header. Passed in rather than
+ *   read here so it is the SAME string `--version` prints: `buildProgram`
+ *   resolves `options.version ?? VERSION`, and a host that overrides one must
+ *   not be able to leave the other saying something else.
+ * @returns The formatted, colorized help text.
+ */
+export function formatRootHelp(programName, description, verbs, version, issuesUrl) {
+    const present = nounsFrom(verbs);
+    const kernel = buildKernelGroups(programName);
+    const curated = new Set(kernel.flatMap((g) => g.nouns.map((n) => n.noun)));
+    const groups = [
+        // Everything the kernel's curated table does not claim — in the shipped
+        // binary the bundled domain packs, in a fork whatever it ships. Untitled
+        // and first, so the domain leads the page without the kernel naming it.
+        {
+            nouns: [...present]
+                .filter((n) => !curated.has(n))
+                .sort()
+                .map((noun) => ({ noun, summary: summarizeNoun(noun, verbs) })),
+        },
+        ...kernel.map((g) => ({
+            ...g,
+            nouns: g.nouns.filter((n) => present.has(n.noun)),
+        })),
+    ].filter((g) => g.nouns.length > 0);
+    // One column width across ALL groups so the noun column aligns section to
+    // section, not just within a section.
+    const nounWidth = Math.max(...groups.flatMap((g) => g.nouns.map((n) => n.noun.length)), 0);
+    const lines = [
+        // The wordmark leads when the distribution declares one. A fork ships its
+        // own art or none, so its front door is never branded with someone else's.
+        ...(PROGRAM_LOGO.length > 0 ? [...PROGRAM_LOGO.map(helpLogo), ""] : []),
+        // `<name> v<version> — <blurb>`, the spelling `info` and `capabilities`
+        // already use, so the front door names the build the same way every other
+        // surface does. Dimmed: it answers "which build am I on" for someone who
+        // is already here, and must not compete with the name.
+        `${helpHeading(programName)} ${helpDim(`v${version}`)} — ${description}`,
+        "",
+        // The preview notice. Dimmed and directly under the header, because it
+        // qualifies what the reader has just been told the tool IS — a version
+        // number alone does not say "expect this to move".
+        //
+        // The URL is the distribution's declared `issuesUrl`, never a literal:
+        // `kernel/copy.test.ts` forbids the kernel naming a distribution, and a
+        // fork inviting feedback to someone else's tracker would be worse than a
+        // missing line. It is passed in for the same reason `version` is.
+        helpDim(`This is a preview version. Issues and suggestions: ${issuesUrl}`),
+        "",
+        helpUsage(`${programName} ${helpTerm("<command>")} ${helpDim("[subcommand] [flags]")}`),
+        "",
+    ];
+    for (const group of groups) {
+        if (group.title)
+            lines.push(helpHeading(group.title));
+        lines.push(...helpColumns(group.nouns.map((n) => [n.noun, n.summary]), nounWidth));
+        lines.push("");
+    }
+    // The frozen global-flags block: these doc strings MUST stay byte-consistent
+    // with FIXED_SURFACE.globalFlags (emitSurface.ts) — restyle the LAYOUT only,
+    // never these strings.
+    lines.push(helpHeading("Global flags"));
+    const flags = [
+        [
+            "--format <plain|llm|json>",
+            "Select output format (llm = condensed Markdown for agents)",
+        ],
+        [
+            "--detail <level>",
+            "Progressive-disclosure level (summary, standard, detailed)",
+        ],
+        ["--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"],
+    ];
+    lines.push(...helpColumns(flags));
+    lines.push("");
+    lines.push(helpDim(`Run \`${programName} <command> --help\` for details, or \`${programName} capabilities\` to get oriented.`));
+    return lines.join("\n");
+}
+//# sourceMappingURL=rootHelp.js.map

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

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

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

@@ -0,0 +1,75 @@
+/**
+ * Turn an unknown command into an actionable "Did you mean?".
+ *
+ * When Commander rejects an unrecognized noun or verb, the bin resolves the
+ * offending token and the set of siblings it should have matched, then raises a
+ * `PragmaError.unknownVerb` (its suggestions ranked by `suggestNames`) rendered
+ * through the shared error renderers — so the plain path gets the same `Error:`
+ * prefix and "Did you mean?" list as every other error. The resolution is
+ * data-driven — a noun→verbs map built from the grammar — so no Commander
+ * internals leak into the suggester.
+ */
+/**
+ * Curated suggestions for a token whose JOB exists under other names. Edit
+ * distance cannot rank these — `status` is nowhere near `info` textually —
+ * but a user typing the conventional spelling deserves the commands that own
+ * the job here, not the nearest-looking noun. Consulted before fuzzy ranking;
+ * adding a second spelling as a real command is the one thing this table must
+ * never become.
+ */
+const CURATED_SUGGESTIONS = {
+    status: ["info", "doctor"],
+};
+/**
+ * The curated suggestions for an unknown token, if any.
+ *
+ * @param token - The unresolved command token.
+ * @returns The commands that own the token's job, or `undefined`.
+ */
+export function curatedSuggestions(token) {
+    return CURATED_SUGGESTIONS[token];
+}
+/**
+ * Build the noun → verb-labels map from the registered verbs.
+ *
+ * Hidden verbs are excluded. A self-verb (path length 1, e.g. `["info"]`)
+ * contributes an entry with no sub-verbs.
+ *
+ * @param verbs - All registered verbs.
+ * @returns A map from noun to its verb labels (empty for self-verbs).
+ */
+export function nounVerbMap(verbs) {
+    const map = new Map();
+    for (const verb of verbs) {
+        if (verb.hidden)
+            continue;
+        const [noun, sub] = verb.path;
+        const labels = map.get(noun) ?? [];
+        if (sub)
+            labels.push(sub);
+        map.set(noun, labels);
+    }
+    return map;
+}
+/**
+ * Locate the first token that does not resolve against the known commands.
+ *
+ * @param positionals - The stripped positional args (no flags), in order.
+ * @param nouns - The noun → verb-labels map from {@link nounVerbMap}.
+ * @returns The unresolved token with its candidates, or `undefined` when the
+ *   args resolve cleanly.
+ */
+export function resolveUnknownCommand(positionals, nouns) {
+    const [noun, verb] = positionals;
+    if (noun === undefined)
+        return undefined;
+    if (!nouns.has(noun)) {
+        return { token: noun, candidates: [...nouns.keys()] };
+    }
+    const labels = nouns.get(noun) ?? [];
+    if (verb !== undefined && labels.length > 0 && !labels.includes(verb)) {
+        return { token: verb, candidates: labels };
+    }
+    return undefined;
+}
+//# sourceMappingURL=suggest.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../../../../src/kernel/project/cli/suggest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAgD;IACvE,MAAM,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa;IAEb,OAAO,mBAAmB,CAAC,KAAK,CAAC,CAAC;AACpC,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAA0B;IACpD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,MAAM;YAAE,SAAS;QAC1B,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC;QAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,GAAG;YAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAA8B,EAC9B,KAA6C;IAE7C,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,WAAW,CAAC;IACjC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAEzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACrB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;IACrC,IAAI,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}