@sdxc/cli 0.0.0-stage → 2026.10.20

package/dist/exec.js

@@ -0,0 +1,136 @@
+/**
+ * Child processes without a shell: arguments reach the program exactly as given, so nothing in
+ * them is expanded or split. The answer is a `Result` carrying the exit code and what the child
+ * printed, and an aborted signal stops the child and answers a cancelled failure.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { spawn } from "node:child_process";
+import { failure, success } from "@sdxc/result";
+import { CancelledError } from "./errors.js";
+/** A child that could not start or exited with a code other than 0. */
+export class ExecError extends Error {
+    name = "ExecError";
+    /** The command as given. */
+    command;
+    /** The exit code, or `null` when the child never started or ended on a signal. */
+    code;
+    stdout;
+    stderr;
+    output;
+    /**
+     * @param message - What went wrong
+     * @param details - The command and what it printed
+     */
+    constructor(message, details) {
+        super(message, { cause: details.cause });
+        this.command = details.command;
+        this.code = details.code;
+        this.stdout = details.stdout ?? "";
+        this.stderr = details.stderr ?? "";
+        this.output = details.output ?? "";
+    }
+}
+/** The command as a shell user would read it, for messages. */
+export function displayCommand(command) {
+    return command
+        .map((part) => (/^[\w./:=@-]+$/.test(part) ? part : JSON.stringify(part)))
+        .join(" ");
+}
+/**
+ * Spawns `command` with `node:child_process`. Output bound for the process's own streams is
+ * inherited directly; output bound for any other stream is piped and forwarded to it.
+ */
+export const spawnExec = (command, request) => new Promise((resolve) => {
+    let settled = false;
+    let settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(outcome);
+    };
+    let [program, ...args] = command;
+    if (program === undefined) {
+        settle(failure(new ExecError("exec needs a command", { command, code: null })));
+        return;
+    }
+    if (request.signal.aborted) {
+        settle(failure(new CancelledError()));
+        return;
+    }
+    let shown = displayCommand(command);
+    let direct = (target, stream) => target === stream;
+    let outTarget = request.stdio === "inherit"
+        ? request.stdout
+        : request.stdio === "stderr"
+            ? request.stderr
+            : null;
+    let errTarget = request.stdio === "inherit" || request.stdio === "stderr" ? request.stderr : null;
+    let stdout = request.stdio === "ignore"
+        ? "ignore"
+        : outTarget === null
+            ? "pipe"
+            : direct(outTarget, process.stdout)
+                ? "inherit"
+                : direct(outTarget, process.stderr)
+                    ? 2
+                    : "pipe";
+    let stderr = request.stdio === "ignore"
+        ? "ignore"
+        : errTarget !== null && direct(errTarget, process.stderr)
+            ? "inherit"
+            : "pipe";
+    let stdin = request.input !== undefined ? "pipe" : request.stdio === "inherit" ? "inherit" : "ignore";
+    let child = spawn(program, args, {
+        cwd: request.cwd,
+        env: { ...request.env },
+        shell: false,
+        stdio: [stdin, stdout, stderr],
+    });
+    let collected = { stdout: "", stderr: "", output: "" };
+    child.stdout?.on("data", (chunk) => {
+        let text = chunk.toString();
+        if (outTarget === null) {
+            collected.stdout += text;
+            collected.output += text;
+        }
+        else
+            outTarget.write(text);
+    });
+    child.stderr?.on("data", (chunk) => {
+        let text = chunk.toString();
+        if (errTarget === null) {
+            collected.stderr += text;
+            collected.output += text;
+        }
+        else
+            errTarget.write(text);
+    });
+    if (request.input !== undefined)
+        child.stdin?.end(request.input);
+    let abort = () => child.kill("SIGTERM");
+    request.signal.addEventListener("abort", abort, { once: true });
+    child.once("error", (error) => {
+        request.signal.removeEventListener("abort", abort);
+        settle(failure(new ExecError(`${shown} could not start: ${error.message}`, {
+            command,
+            code: null,
+            cause: error,
+            ...collected,
+        })));
+    });
+    child.once("close", (code, signal) => {
+        request.signal.removeEventListener("abort", abort);
+        if (request.signal.aborted) {
+            settle(failure(new CancelledError()));
+            return;
+        }
+        if (code === 0) {
+            settle(success({ code, ...collected }));
+            return;
+        }
+        let reason = code === null ? `was stopped by ${signal ?? "a signal"}` : `exited with ${code}`;
+        settle(failure(new ExecError(`${shown} ${reason}`, { command, code, ...collected })));
+    });
+});

package/dist/flag.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Flag declarations: booleans with a generated `--no-<name>`, and string and number flags that
+ * become repeated (`.multiple()`), comma lists (`.list()`) or take an optional value
+ * (`.optionalValue()`). Each declaration carries the type its handler reads off `ctx.flags`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { PromptDeclaration } from "./prompt.js";
+/** Brands a flag declaration so a command can tell it from an argument. */
+declare const FLAG: unique symbol;
+/** Type-only slot carrying the value a declaration hands its handler. */
+declare const VALUE: unique symbol;
+/** Wraps a value type so an `undefined` inside it survives inference. */
+export interface Carried<T> {
+    value: T;
+}
+/** What a flag reads from the command line. */
+export type FlagKind = "boolean" | "string" | "number";
+/** Everything one flag declares, as the parser and the help read it. */
+export interface FlagSpec {
+    kind: FlagKind;
+    /** The long name, written `--<name>`. */
+    name: string;
+    /** A one-character alias, written `-<short>`. */
+    short: string | undefined;
+    /** Other long names the flag answers to, such as `jobs` for `concurrency`. */
+    aliases: readonly string[];
+    description: string | undefined;
+    /** What the help shows in `<…>` after the flag. */
+    valueName: string | undefined;
+    /**
+     * Whether `default` was declared; a declared `undefined` still counts. A boolean without one
+     * still reads `false` when missing, but a prompt bound to it asks, as one does for a default
+     * of `undefined`.
+     */
+    hasDefault: boolean;
+    default: unknown;
+    /** A missing value is a usage error. Implied by a prompt without a default. */
+    required: boolean;
+    /** Checks each value: every element of a repeated or list flag. */
+    schema: StandardSchemaV1 | undefined;
+    prompt: PromptDeclaration | undefined;
+    /** Repeating the flag collects every value instead of keeping the last. */
+    multiple: boolean;
+    /** One value holds several, separated by commas. */
+    list: boolean;
+    /** The flag may appear bare, which reads as `true`, or with `=value`. */
+    optionalValue: boolean;
+    /** Left out of the help. */
+    hidden: boolean;
+    /** The help section the flag is listed under; `undefined` lists it under "Options". */
+    heading: string | undefined;
+}
+/** A declared flag, typed with the value its handler reads. */
+export interface Flag<Value = unknown> {
+    readonly [FLAG]: FlagSpec;
+    readonly [VALUE]?: Carried<Value>;
+}
+/** The value a flag declaration hands its handler. */
+export type FlagValue<F> = F extends {
+    readonly [VALUE]?: Carried<infer V> | undefined;
+} ? V : never;
+/** Whether `value` is a flag declaration. */
+export declare function isFlag(value: unknown): value is Flag;
+/** The spec behind a flag declaration. */
+export declare function flagSpec(flag: Flag): FlagSpec;
+/** The value of a string or number flag, from the shape its modifiers gave it. */
+type ValueOutput<Item, Required extends boolean, Many extends boolean, Bare extends boolean> = (Many extends true ? Item[] : Required extends true ? Item : Item | undefined) | (Bare extends true ? true : never);
+/** A string or number flag, with the modifiers that reshape its value. */
+export interface ValueFlag<Item, Required extends boolean = false, Many extends boolean = false, Bare extends boolean = false> extends Flag<ValueOutput<Item, Required, Many, Bare>> {
+    /**
+     * Every occurrence is kept, in order: `--tag a --tag b` reads `["a", "b"]`, and a missing
+     * flag reads `[]`.
+     */
+    multiple(): ValueFlag<Item, Required, true, Bare>;
+    /**
+     * Each value is split at commas, with blanks dropped: `--allow-env=HOME,PATH` reads
+     * `["HOME", "PATH"]`. Repeating the flag adds to the list, and a missing flag reads `[]`.
+     */
+    list(): ValueFlag<Item, Required, true, Bare>;
+    /**
+     * The flag may appear bare, which reads `true`, or with a value after `=`, which reads that
+     * value: `--allow-net` grants everything, `--allow-net=api.example.com` one host. A bare
+     * occurrence anywhere wins over values in other occurrences.
+     */
+    optionalValue(): ValueFlag<Item, Required, Many, true>;
+}
+/** Options every flag takes. */
+export interface FlagOptions {
+    description?: string;
+    /** A one-character alias, such as `"f"` for `-f`. */
+    short?: string;
+    /** Other long names the flag answers to. */
+    aliases?: readonly string[];
+    /** Asked when the flag is missing and stdin and stderr are terminals. */
+    prompt?: PromptDeclaration;
+    /** Left out of the help. */
+    hidden?: boolean;
+    /**
+     * Lists the flag in the help under this section title instead of "Options", so a command
+     * with many flags reads in groups. Sections follow in the order their first flag is declared.
+     */
+    heading?: string;
+}
+/** Options a boolean flag takes. */
+export interface BooleanFlagOptions extends FlagOptions {
+    /**
+     * The value when neither `--<name>` nor `--no-<name>` is passed. `undefined` leaves the flag
+     * unset, so a configured default or a later question decides, and the help shows `--[no-]<name>`.
+     * @default false
+     */
+    default?: boolean | undefined;
+}
+/** The handler's value type for a boolean flag declared with `options`. */
+type BooleanValue<Options> = Options extends {
+    default: infer Default;
+} ? undefined extends Default ? boolean | undefined : boolean : boolean;
+/** Options a string or number flag takes. */
+export interface ValueFlagOptions extends FlagOptions {
+    /** What the help shows in `<…>`. @default "value", or "number" for a number flag */
+    valueName?: string;
+    /** Checks each value; its output is what the handler reads. */
+    schema?: StandardSchemaV1;
+    /** The value when the flag is missing, taken as the handler reads it. */
+    default?: unknown;
+    /** A missing flag is a usage error. */
+    required?: boolean;
+}
+/** The handler's value type for a flag declared with `options`, before any modifier. */
+type ItemOf<Options, Fallback> = Options extends {
+    schema: StandardSchemaV1<infer _Input, infer Output>;
+} ? Output : Fallback;
+/** Whether a flag declared with `options` always has a value once the command runs. */
+type IsRequired<Options> = Options extends {
+    default: unknown;
+} ? true : Options extends {
+    required: true;
+} ? true : Options extends {
+    prompt: PromptDeclaration;
+} ? true : false;
+/**
+ * Flag declarations. A flag belongs to the command that declares it, and its key in that
+ * command's `flags` is the property the handler reads.
+ *
+ * @example flags: { dryRun: flag.boolean("dry-run", { description: "Print it and write nothing" }) }
+ * @example flags: { allowNet: flag.string("allow-net").optionalValue().list() }
+ * @example flags: { retries: flag.number("retries", { default: 0 }) }
+ */
+export declare const flag: {
+    /**
+     * `--<name>` reads `true` and `--no-<name>` reads `false`; passing both is a usage error.
+     * Neither reads the `default`: `false`, or `undefined` for a tri-state flag declared with
+     * `default: undefined`.
+     *
+     * @param name - The long name, in kebab case
+     * @example flags: { git: flag.boolean("git", { default: undefined }) } // boolean | undefined
+     */
+    boolean<const Options extends BooleanFlagOptions = Record<never, never>>(name: string, options?: Options): Flag<BooleanValue<Options>>;
+    /**
+     * `--<name> value` or `--<name>=value`, checked by `schema` when one is given.
+     *
+     * @param name - The long name, in kebab case
+     */
+    string<const Options extends ValueFlagOptions = Record<never, never>>(name: string, options?: Options): ValueFlag<ItemOf<Options, string>, IsRequired<Options>>;
+    /**
+     * A string flag read as a number before `schema` checks it; text that is not a number is a
+     * usage error.
+     *
+     * @param name - The long name, in kebab case
+     */
+    number<const Options extends ValueFlagOptions = Record<never, never>>(name: string, options?: Options): ValueFlag<ItemOf<Options, number>, IsRequired<Options>>;
+};
+export {};

package/dist/flag.js

@@ -0,0 +1,91 @@
+/**
+ * Flag declarations: booleans with a generated `--no-<name>`, and string and number flags that
+ * become repeated (`.multiple()`), comma lists (`.list()`) or take an optional value
+ * (`.optionalValue()`). Each declaration carries the type its handler reads off `ctx.flags`.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a flag declaration so a command can tell it from an argument. */
+const FLAG = Symbol.for("@sdxc/cli.flag");
+/** Whether `value` is a flag declaration. */
+export function isFlag(value) {
+    return typeof value === "object" && value !== null && FLAG in value;
+}
+/** The spec behind a flag declaration. */
+export function flagSpec(flag) {
+    return flag[FLAG];
+}
+/** Builds the spec shared by every flag kind. */
+function baseSpec(kind, name, options) {
+    return {
+        kind,
+        name,
+        short: options.short,
+        aliases: options.aliases ?? [],
+        description: options.description,
+        valueName: options.valueName,
+        hasDefault: "default" in options,
+        default: options.default,
+        required: options.required === true || (options.prompt !== undefined && !("default" in options)),
+        schema: options.schema,
+        prompt: options.prompt,
+        multiple: false,
+        list: false,
+        optionalValue: false,
+        hidden: options.hidden === true,
+        heading: options.heading,
+    };
+}
+/** A value flag around `spec`, whose modifiers each answer a new declaration. */
+function valueFlag(spec) {
+    return {
+        [FLAG]: spec,
+        multiple: () => valueFlag({ ...spec, multiple: true }),
+        list: () => valueFlag({ ...spec, list: true }),
+        optionalValue: () => valueFlag({ ...spec, optionalValue: true }),
+    };
+}
+/**
+ * Flag declarations. A flag belongs to the command that declares it, and its key in that
+ * command's `flags` is the property the handler reads.
+ *
+ * @example flags: { dryRun: flag.boolean("dry-run", { description: "Print it and write nothing" }) }
+ * @example flags: { allowNet: flag.string("allow-net").optionalValue().list() }
+ * @example flags: { retries: flag.number("retries", { default: 0 }) }
+ */
+export const flag = {
+    /**
+     * `--<name>` reads `true` and `--no-<name>` reads `false`; passing both is a usage error.
+     * Neither reads the `default`: `false`, or `undefined` for a tri-state flag declared with
+     * `default: undefined`.
+     *
+     * @param name - The long name, in kebab case
+     * @example flags: { git: flag.boolean("git", { default: undefined }) } // boolean | undefined
+     */
+    boolean(name, options) {
+        let given = options ?? {};
+        let spec = baseSpec("boolean", name, given);
+        if (!spec.hasDefault)
+            spec.default = false;
+        spec.required = false;
+        return { [FLAG]: spec };
+    },
+    /**
+     * `--<name> value` or `--<name>=value`, checked by `schema` when one is given.
+     *
+     * @param name - The long name, in kebab case
+     */
+    string(name, options) {
+        return valueFlag(baseSpec("string", name, options ?? {}));
+    },
+    /**
+     * A string flag read as a number before `schema` checks it; text that is not a number is a
+     * usage error.
+     *
+     * @param name - The long name, in kebab case
+     */
+    number(name, options) {
+        return valueFlag(baseSpec("number", name, options ?? {}));
+    },
+};

package/dist/handler.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `createCommand()`, which pairs a handler with the command it runs. Passing the declaration is
+ * what types `ctx.arguments` and `ctx.flags`; the middleware listed beside the handler, and the
+ * CLI's own when an app augments {@link CLITypes}, type what they publish.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { ArgumentsOf, FlagsOf, Node } from "./command.js";
+import type { AnyCommandContext, CommandContext } from "./context.js";
+import type { Carried } from "./flag.js";
+import type { AnyCommandMiddleware, ChainProperties, CommandResult } from "./middleware.js";
+/**
+ * Augmented by an app to name its CLI, so handlers written in their own files read what the
+ * CLI's middleware publishes, the way `JobTypes` does for jobs.
+ *
+ * @example
+ * declare module "@sdxc/cli" {
+ * 	interface CLITypes {
+ * 		cli: typeof cli;
+ * 	}
+ * }
+ */
+export interface CLITypes {
+}
+/** The middleware chain of the CLI an app named in {@link CLITypes}. */
+type CurrentChain = CLITypes extends {
+    cli: {
+        readonly middleware: infer Chain;
+    };
+} ? Chain extends readonly AnyCommandMiddleware[] ? Chain : [] : [];
+/** The context a command's handler receives, with what its middleware chain installed. */
+export type HandlerContext<Target, Chain extends readonly AnyCommandMiddleware[] = [], Global extends readonly AnyCommandMiddleware[] = CurrentChain> = CommandContext<ArgumentsOf<Target>, FlagsOf<Target>> & ChainProperties<Global> & ChainProperties<Chain>;
+/**
+ * The context of any command that runs behind `Chain`, whatever it parsed: the type a helper
+ * shared by several commands takes, since each command's own context is assignable to it.
+ *
+ * @example
+ * const MAKE = [project(), packageRoot()] as const;
+ * function write(ctx: ChainContext<typeof MAKE>, file: string) { ctx.project.root; }
+ */
+export type ChainContext<Chain extends readonly AnyCommandMiddleware[] = [], Global extends readonly AnyCommandMiddleware[] = CurrentChain> = AnyCommandContext & ChainProperties<Global> & ChainProperties<Chain>;
+/** The work itself: a success exits 0 and a failure exits by its kind. */
+export type CommandHandler<Context> = (context: Context) => CommandResult | Promise<CommandResult>;
+/** Brands a command implementation so `map()` can tell it from a bare handler. */
+declare const ACTION: unique symbol;
+/** Type-only slot naming the command an action was written for. */
+declare const TARGET: unique symbol;
+/** A handler paired with the middleware that runs before it alone. */
+export interface CommandAction<Target = Node, Chain extends readonly AnyCommandMiddleware[] = readonly AnyCommandMiddleware[]> {
+    readonly [ACTION]: true;
+    readonly [TARGET]?: Carried<Target>;
+    readonly middleware: Chain;
+    /** The work itself; a method, so an action written for one chain maps wherever its command does. */
+    handler(this: void, context: HandlerContext<Target, Chain>): CommandResult | Promise<CommandResult>;
+}
+/** Whether `value` is what `createCommand` returns. */
+export declare function isAction(value: unknown): value is CommandAction<Node, readonly AnyCommandMiddleware[]>;
+/**
+ * Types one command's implementation against its declaration, so it can live in its own file
+ * and be mapped through `lazy()`.
+ *
+ * @param target - The declared command (or group) this implements
+ * @param action - The handler, or `{ middleware, handler }` for middleware that runs before
+ * this command alone
+ * @example export default createCommand(sdxc.ui.add, async (ctx) => success());
+ * @example export default createCommand(sdxc.make.job, { middleware: [project()], handler: (ctx) => make(ctx.project) });
+ */
+export declare function createCommand<Target extends Node, const Chain extends readonly AnyCommandMiddleware[] = []>(target: Target, action: CommandHandler<HandlerContext<Target, Chain>> | {
+    middleware: Chain;
+    handler: CommandHandler<HandlerContext<Target, Chain>>;
+}): CommandAction<Target, Chain>;
+export {};

package/dist/handler.js

@@ -0,0 +1,30 @@
+/**
+ * `createCommand()`, which pairs a handler with the command it runs. Passing the declaration is
+ * what types `ctx.arguments` and `ctx.flags`; the middleware listed beside the handler, and the
+ * CLI's own when an app augments {@link CLITypes}, type what they publish.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Brands a command implementation so `map()` can tell it from a bare handler. */
+const ACTION = Symbol.for("@sdxc/cli.action");
+/** Whether `value` is what `createCommand` returns. */
+export function isAction(value) {
+    return typeof value === "object" && value !== null && ACTION in value;
+}
+/**
+ * Types one command's implementation against its declaration, so it can live in its own file
+ * and be mapped through `lazy()`.
+ *
+ * @param target - The declared command (or group) this implements
+ * @param action - The handler, or `{ middleware, handler }` for middleware that runs before
+ * this command alone
+ * @example export default createCommand(sdxc.ui.add, async (ctx) => success());
+ * @example export default createCommand(sdxc.make.job, { middleware: [project()], handler: (ctx) => make(ctx.project) });
+ */
+export function createCommand(target, action) {
+    if (typeof action === "function") {
+        return { [ACTION]: true, middleware: [], handler: action };
+    }
+    return { [ACTION]: true, middleware: action.middleware, handler: action.handler };
+}

package/dist/help.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Help rendered from the contract: the usage line, the description, the subcommands, the
+ * arguments, then the flags with their value names and defaults, under their headings. Every `--help` and every usage
+ * error prints it, so the text and what the parser accepts come from one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { Style } from "./style.js";
+import type { Entry } from "./tree.js";
+/** What the help knows about the program beyond the contract. */
+export interface HelpProgram {
+    version: string | undefined;
+    /** Shown at the root when the root group has no description of its own. */
+    description: string | undefined;
+}
+/** Renders `entry`'s help, ending with a newline. */
+export declare function renderHelp(entry: Entry, program: HelpProgram, style: Style): string;

package/dist/help.js

@@ -0,0 +1,141 @@
+/**
+ * Help rendered from the contract: the usage line, the description, the subcommands, the
+ * arguments, then the flags with their value names and defaults, under their headings. Every `--help` and every usage
+ * error prints it, so the text and what the parser accepts come from one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { groupSpec, isGroup } from "./command.js";
+import { visibleWidth } from "./style.js";
+/** Renders `entry`'s help, ending with a newline. */
+export function renderHelp(entry, program, style) {
+    let node = entry.node;
+    let sections = [];
+    let lines = [];
+    if (isGroup(node))
+        lines.push(`${entry.title} <command> [options]`);
+    if (!isGroup(node) || entry.arguments.length > 0 || entry.flags.length > 0) {
+        let usage = [entry.title];
+        for (let argument of entry.arguments)
+            usage.push(argumentLabel(argument.key, argument.spec));
+        usage.push("[options]");
+        lines.push(usage.join(" "));
+    }
+    let indent = " ".repeat("Usage: ".length);
+    sections.push(`${style.bold("Usage:")} ${lines.join(`\n${indent}`)}`);
+    let description = isGroup(node) ? groupSpec(node).description : node.description;
+    if (entry.parent === undefined)
+        description ??= program.description;
+    if (description !== undefined)
+        sections.push(description);
+    if (isGroup(node)) {
+        let rows = [];
+        for (let [name, child] of entry.children) {
+            let spec = isGroup(child.node) ? groupSpec(child.node) : child.node;
+            if (spec.hidden)
+                continue;
+            rows.push([name, spec.description ?? ""]);
+        }
+        sections.push(section("Commands:", rows, style));
+    }
+    if (entry.arguments.length > 0) {
+        let rows = entry.arguments.map(({ key, spec }) => {
+            let notes = spec.description ?? "";
+            if (spec.hasDefault)
+                notes = withDefault(notes, spec.default);
+            return [argumentLabel(key, spec), notes];
+        });
+        sections.push(section("Arguments:", rows, style));
+    }
+    let headings = new Map([["Options", []]]);
+    for (let { spec } of entry.flags) {
+        if (spec.hidden)
+            continue;
+        let heading = spec.heading ?? "Options";
+        let rows = headings.get(heading) ?? [];
+        headings.set(heading, rows);
+        rows.push([flagLabel(spec), flagNotes(spec)]);
+    }
+    let builtins = headings.get("Options");
+    if (entry.tasks)
+        builtins.push(["--no-progress", "Print tasks without animation"]);
+    if (program.version !== undefined && entry.parent === undefined) {
+        builtins.push(["--version", "Print the version"]);
+    }
+    builtins.push(["-h, --help", "Show this help"]);
+    for (let [heading, rows] of headings)
+        sections.push(section(`${heading}:`, rows, style));
+    if (!isGroup(node) && node.examples.length > 0) {
+        let program = entry.title.split(" ")[0];
+        let lines = node.examples.map((example) => `  ${program} ${example}`);
+        sections.push(`${style.bold("Examples:")}\n${lines.join("\n")}`);
+    }
+    return `${sections.join("\n\n")}\n`;
+}
+/** A titled section of aligned rows, flag and command names styled. */
+function section(title, rows, style) {
+    let width = Math.max(0, ...rows.map(([left]) => visibleWidth(left)));
+    let lines = rows.map(([left, right]) => {
+        let padded = left + " ".repeat(width - visibleWidth(left));
+        return right === "" ? `  ${style.cyan(left)}` : `  ${style.cyan(padded)}  ${right}`;
+    });
+    return `${style.bold(title)}\n${lines.join("\n")}`;
+}
+/** `<name>`, `[name]` or `<name...>`, as the usage line writes an argument. */
+function argumentLabel(key, spec) {
+    let name = spec.valueName ?? key;
+    if (spec.variadic)
+        return spec.min > 0 ? `<${name}...>` : `[${name}...]`;
+    return spec.min > 0 ? `<${name}>` : `[${name}]`;
+}
+/**
+ * The left column for one flag: its short alias, its names, and its value. A boolean shows the
+ * spelling that changes something: `--name` when it defaults to false, `--no-name` when it
+ * defaults to true, and `--[no-]name` when it asks or is left unset.
+ */
+function flagLabel(spec) {
+    let names = [];
+    if (spec.short !== undefined)
+        names.push(`-${spec.short}`);
+    if (spec.kind === "boolean") {
+        let prefix = spec.prompt !== undefined || spec.default === undefined
+            ? "[no-]"
+            : spec.default === true
+                ? "no-"
+                : "";
+        names.push(`--${prefix}${spec.name}`);
+        for (let alias of spec.aliases)
+            names.push(`--${prefix}${alias}`);
+        return names.join(", ");
+    }
+    for (let name of [spec.name, ...spec.aliases])
+        names.push(`--${name}`);
+    let value = spec.valueName ?? (spec.kind === "number" ? "number" : "value");
+    if (spec.list)
+        value = `${value},...`;
+    let label = names.join(", ");
+    return spec.optionalValue ? `${label}[=<${value}>]` : `${label} <${value}>`;
+}
+/** The right column for one flag: its description, whether it repeats, and its default. */
+function flagNotes(spec) {
+    let notes = spec.description ?? "";
+    if (spec.multiple)
+        notes = `${notes} (repeatable)`.trim();
+    if (spec.required && spec.prompt === undefined)
+        notes = `${notes} (required)`.trim();
+    if (spec.kind !== "boolean" && spec.hasDefault)
+        notes = withDefault(notes, spec.default);
+    return notes;
+}
+/** A default value as the help prints it. */
+function display(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** `notes` with the default appended, when there is one worth showing. */
+function withDefault(notes, value) {
+    if (value === undefined || (Array.isArray(value) && value.length === 0))
+        return notes;
+    let shown = Array.isArray(value) ? value.map(display).join(",") : display(value);
+    return `${notes} (default: ${shown})`.trim();
+}