clap-ts 0.2.0 → 0.3.0

package/dist/install.js

@@ -0,0 +1,185 @@
+/**
+ * Put generated completions and man pages where the system will find them.
+ *
+ * ```ts
+ * import { withInstallers } from 'clap-ts/install';
+ *
+ * runMain(withInstallers(main));
+ * // my-tool completions install zsh
+ * // my-tool man install
+ * ```
+ *
+ * Everything respects `XDG_DATA_HOME`, and nothing is written until the target
+ * directory is created, so a dry run can report the path without touching disk.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { generateCompletions } from './completions.js';
+import { generateManPages } from './man.js';
+const XDG_DATA = process.env['XDG_DATA_HOME'] ?? join(homedir(), '.local', 'share');
+const XDG_CONFIG = process.env['XDG_CONFIG_HOME'] ?? join(homedir(), '.config');
+/**
+ * The per-user completion path for a shell.
+ *
+ * bash, zsh and fish load these directories on their own. powershell, elvish
+ * and nushell have no drop-in directory, so those report a line to add to the
+ * profile instead.
+ */
+export function completionTarget(shell, binaryName) {
+    switch (shell) {
+        case 'bash':
+            return { dir: join(XDG_DATA, 'bash-completion', 'completions'), file: binaryName };
+        case 'zsh':
+            return {
+                dir: join(XDG_DATA, 'zsh', 'site-functions'),
+                file: `_${binaryName}`,
+                manualStep: `add ${join(XDG_DATA, 'zsh', 'site-functions')} to $fpath before compinit`,
+            };
+        case 'fish':
+            return { dir: join(XDG_CONFIG, 'fish', 'completions'), file: `${binaryName}.fish` };
+        case 'powershell':
+            return {
+                dir: join(XDG_CONFIG, 'powershell', 'completions'),
+                file: `${binaryName}.ps1`,
+                manualStep: `add \`. ${join(XDG_CONFIG, 'powershell', 'completions', `${binaryName}.ps1`)}\` to $PROFILE`,
+            };
+        case 'elvish':
+            return {
+                dir: join(XDG_CONFIG, 'elvish', 'lib'),
+                file: `${binaryName}.elv`,
+                manualStep: `add \`use ${binaryName}\` to ~/.config/elvish/rc.elv`,
+            };
+        case 'nushell':
+            return {
+                dir: join(XDG_CONFIG, 'nushell', 'completions'),
+                file: `${binaryName}.nu`,
+                manualStep: `add \`source ${join(XDG_CONFIG, 'nushell', 'completions', `${binaryName}.nu`)}\` to your config`,
+            };
+    }
+}
+function write(dir, file, contents, dryRun) {
+    const path = join(dir, file);
+    if (!dryRun) {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(path, contents);
+    }
+    return path;
+}
+/** Write the completion script for one shell to its per-user location. */
+export function installCompletions(command, shell, opts) {
+    const binaryName = opts?.binaryName ?? command.meta.binName ?? command.meta.name;
+    const target = completionTarget(shell, binaryName);
+    const dir = opts?.dir ?? target.dir;
+    const dryRun = opts?.dryRun === true;
+    const path = write(dir, target.file, generateCompletions(command, shell, binaryName), dryRun);
+    return {
+        paths: [path],
+        ...(target.manualStep === undefined ? {} : { manualStep: target.manualStep }),
+        dryRun,
+    };
+}
+/** Write a man page per command into the per-user man directory. */
+export function installManPages(command, opts) {
+    const binaryName = opts?.binaryName ?? command.meta.binName ?? command.meta.name;
+    const dryRun = opts?.dryRun === true;
+    const pages = generateManPages(command, { name: binaryName });
+    const dir = opts?.dir ?? join(XDG_DATA, 'man', 'man1');
+    const paths = [];
+    for (const [file, roff] of pages) {
+        paths.push(write(dir, file, roff, dryRun));
+    }
+    return {
+        paths,
+        manualStep: `add ${join(XDG_DATA, 'man')} to $MANPATH if your system does not read it already`,
+        dryRun,
+    };
+}
+const SHELLS = ['bash', 'zsh', 'fish', 'powershell', 'elvish', 'nushell'];
+/**
+ * Add `completions` and `man` subcommands that both print and install.
+ *
+ * `tool completions bash` writes the script to stdout as before;
+ * `tool completions install bash` puts it where the shell will find it.
+ */
+export function withInstallers(rootCommand) {
+    const completions = {
+        meta: {
+            name: 'completions',
+            description: 'Print or install a shell completion script',
+            aliases: ['completion'],
+            // `completions install zsh` names the shell on the subcommand, so the
+            // shell positional here is only required when printing.
+            subcommandNegatesReqs: true,
+        },
+        args: {
+            shell: {
+                type: 'positional',
+                valueName: 'SHELL',
+                required: true,
+                valueParser: [...SHELLS],
+                description: `Target shell: ${SHELLS.join(', ')}`,
+            },
+        },
+        subCommands: {
+            install: {
+                meta: { name: 'install', description: 'Write the script where the shell will find it' },
+                args: {
+                    shell: {
+                        type: 'positional',
+                        valueName: 'SHELL',
+                        required: true,
+                        valueParser: [...SHELLS],
+                        description: 'Shell to install for',
+                    },
+                    dryRun: { type: 'boolean', description: 'Report the path without writing' },
+                },
+                run({ args, stdout }) {
+                    const result = installCompletions(rootCommand, args['shell'], {
+                        dryRun: args['dryRun'] === true,
+                    });
+                    const verb = result.dryRun ? 'would write' : 'wrote';
+                    stdout.write(`${verb} ${result.paths[0]}\n`);
+                    if (result.manualStep !== undefined) {
+                        stdout.write(`note: ${result.manualStep}\n`);
+                    }
+                },
+            },
+        },
+        run({ args, stdout }) {
+            stdout.write(generateCompletions(rootCommand, args['shell']));
+        },
+    };
+    const man = {
+        meta: { name: 'man', description: 'Print or install man pages' },
+        args: {
+            dryRun: { type: 'boolean', description: 'Report the paths without writing' },
+        },
+        subCommands: {
+            install: {
+                meta: { name: 'install', description: 'Write man pages where man will find them' },
+                args: { dryRun: { type: 'boolean', description: 'Report the paths without writing' } },
+                run({ args, stdout }) {
+                    const result = installManPages(rootCommand, { dryRun: args['dryRun'] === true });
+                    const verb = result.dryRun ? 'would write' : 'wrote';
+                    for (const path of result.paths) {
+                        stdout.write(`${verb} ${path}\n`);
+                    }
+                    if (result.manualStep !== undefined) {
+                        stdout.write(`note: ${result.manualStep}\n`);
+                    }
+                },
+            },
+        },
+        run({ stdout }) {
+            for (const roff of generateManPages(rootCommand).values()) {
+                stdout.write(roff);
+            }
+        },
+    };
+    return {
+        ...rootCommand,
+        subCommands: { ...rootCommand.subCommands, completions, man },
+        lazySubCommands: rootCommand.lazySubCommands,
+    };
+}

package/dist/log.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A levelled logger wired to the verbosity arguments a CLI already declares.
+ *
+ * ```ts
+ * import { loggerFrom } from 'clap-ts/log';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'tool' },
+ *   args: {
+ *     verbose: { type: 'boolean', short: 'v', action: 'count', description: 'More output' },
+ *     quiet: { type: 'boolean', short: 'q', description: 'Errors only' },
+ *   },
+ *   run(ctx) {
+ *     const log = loggerFrom(ctx);
+ *     log.info('starting');   // shown by default
+ *     log.debug('details');   // shown with -v
+ *   },
+ * });
+ * ```
+ *
+ * Everything goes to stderr, leaving stdout for the command's actual output so
+ * a pipeline is not polluted by progress chatter.
+ */
+import type { OutputSink } from './types.js';
+/** Ordered from quietest to loudest. */
+export declare const LEVELS: readonly ['silent', 'error', 'warn', 'info', 'debug', 'trace'];
+export type LogLevel = (typeof LEVELS)[number];
+export interface Logger {
+    readonly level: LogLevel;
+    /** Whether a message at this level would be shown. */
+    enabled(level: LogLevel): boolean;
+    error(message: string, ...rest: unknown[]): void;
+    warn(message: string, ...rest: unknown[]): void;
+    info(message: string, ...rest: unknown[]): void;
+    debug(message: string, ...rest: unknown[]): void;
+    trace(message: string, ...rest: unknown[]): void;
+    /** A logger writing the same place at a different level. */
+    withLevel(level: LogLevel): Logger;
+}
+export interface LoggerOptions {
+    /** Level to log at (default 'info'). */
+    readonly level?: LogLevel;
+    /** Where messages go (default process.stderr). */
+    readonly sink?: OutputSink;
+    /** Prefix each line, for instance with the tool name. */
+    readonly prefix?: string;
+    /** Force colour on or off; defaults to whatever the stream supports. */
+    readonly color?: boolean;
+}
+/** Build a logger writing to a sink. */
+export declare function createLogger(opts?: LoggerOptions): Logger;
+export interface LevelFromArgsOptions {
+    /** Name of the count-action verbosity arg (default 'verbose'). */
+    readonly verboseKey?: string;
+    /** Name of the quiet flag (default 'quiet'). */
+    readonly quietKey?: string;
+    /** Name of an explicit level arg, which overrides the other two. */
+    readonly levelKey?: string;
+    /** Level with no flags given (default 'info'). */
+    readonly base?: LogLevel;
+}
+/**
+ * Work out a level from parsed arguments.
+ *
+ * An explicit level wins. Otherwise `--quiet` drops to errors only, and each
+ * `-v` climbs one step, so `-vv` reaches trace from the default of info.
+ */
+export declare function levelFromArgs(args: Record<string, unknown>, opts?: LevelFromArgsOptions): LogLevel;
+/**
+ * A logger for a command context, taking its level from the parsed arguments
+ * and writing to the context's stderr so the testing helpers capture it.
+ */
+export declare function loggerFrom(ctx: {
+    readonly args: unknown;
+    readonly stderr: OutputSink;
+}, opts?: LoggerOptions & LevelFromArgsOptions): Logger;
+/** A logger that discards everything, for tests and dry runs. */
+export declare const silentLogger: Logger;

package/dist/log.js

@@ -0,0 +1,164 @@
+/**
+ * A levelled logger wired to the verbosity arguments a CLI already declares.
+ *
+ * ```ts
+ * import { loggerFrom } from 'clap-ts/log';
+ *
+ * const main = defineCommand({
+ *   meta: { name: 'tool' },
+ *   args: {
+ *     verbose: { type: 'boolean', short: 'v', action: 'count', description: 'More output' },
+ *     quiet: { type: 'boolean', short: 'q', description: 'Errors only' },
+ *   },
+ *   run(ctx) {
+ *     const log = loggerFrom(ctx);
+ *     log.info('starting');   // shown by default
+ *     log.debug('details');   // shown with -v
+ *   },
+ * });
+ * ```
+ *
+ * Everything goes to stderr, leaving stdout for the command's actual output so
+ * a pipeline is not polluted by progress chatter.
+ */
+import { styleText } from 'node:util';
+/** Ordered from quietest to loudest. */
+export const LEVELS = ['silent', 'error', 'warn', 'info', 'debug', 'trace'];
+const RANK = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3,
+    debug: 4,
+    trace: 5,
+};
+const PLAIN = (text) => text;
+function labels(color) {
+    const paint = (codes, text) => color ? styleText(codes, text, { validateStream: false }) : text;
+    return {
+        error: paint('red', 'error'),
+        warn: paint('yellow', 'warning'),
+        info: paint('cyan', 'info'),
+        debug: paint('magenta', 'debug'),
+        trace: paint('gray', 'trace'),
+    };
+}
+/**
+ * Render one extra value.
+ *
+ * An Error is the most common thing to log and `JSON.stringify` turns it into
+ * `{}`, losing the message. A cyclic object throws outright, which would take
+ * the CLI down for the sake of a log line, so serialisation falls back to
+ * String rather than propagating.
+ */
+function renderValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value instanceof Error) {
+        return value.stack ?? `${value.name}: ${value.message}`;
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    if (typeof value === 'bigint' || typeof value === 'symbol' || typeof value === 'function') {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value, safeReplacer()) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** A replacer that names a cycle instead of throwing on it. */
+function safeReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value !== 'object' || value === null) {
+            return value;
+        }
+        if (seen.has(value)) {
+            return '[Circular]';
+        }
+        seen.add(value);
+        return value;
+    };
+}
+function format(rest) {
+    if (rest.length === 0) {
+        return '';
+    }
+    return ` ${rest.map(renderValue).join(' ')}`;
+}
+/** Build a logger writing to a sink. */
+export function createLogger(opts) {
+    const level = opts?.level ?? 'info';
+    const sink = opts?.sink ?? process.stderr;
+    const color = opts?.color ?? styleText('red', 'x') !== 'x';
+    const tag = labels(color);
+    const prefix = opts?.prefix === undefined ? '' : `${opts.prefix} `;
+    const threshold = RANK[level];
+    const write = (at, message, rest) => {
+        if (RANK[at] > threshold) {
+            return;
+        }
+        sink.write(`${prefix}${tag[at]}: ${message}${format(rest)}\n`);
+    };
+    const logger = {
+        level,
+        enabled: (at) => RANK[at] <= threshold,
+        error: (message, ...rest) => {
+            write('error', message, rest);
+        },
+        warn: (message, ...rest) => {
+            write('warn', message, rest);
+        },
+        info: (message, ...rest) => {
+            write('info', message, rest);
+        },
+        debug: (message, ...rest) => {
+            write('debug', message, rest);
+        },
+        trace: (message, ...rest) => {
+            write('trace', message, rest);
+        },
+        withLevel: (next) => createLogger({ ...opts, level: next }),
+    };
+    return logger;
+}
+/**
+ * Work out a level from parsed arguments.
+ *
+ * An explicit level wins. Otherwise `--quiet` drops to errors only, and each
+ * `-v` climbs one step, so `-vv` reaches trace from the default of info.
+ */
+export function levelFromArgs(args, opts) {
+    const explicit = args[opts?.levelKey ?? 'logLevel'];
+    if (typeof explicit === 'string' && LEVELS.includes(explicit)) {
+        return explicit;
+    }
+    if (args[opts?.quietKey ?? 'quiet'] === true) {
+        return 'error';
+    }
+    const base = RANK[opts?.base ?? 'info'];
+    const verbose = args[opts?.verboseKey ?? 'verbose'];
+    const steps = typeof verbose === 'number' ? verbose : verbose === true ? 1 : 0;
+    return LEVELS[Math.min(base + steps, LEVELS.length - 1)];
+}
+/**
+ * A logger for a command context, taking its level from the parsed arguments
+ * and writing to the context's stderr so the testing helpers capture it.
+ */
+export function loggerFrom(
+// Structural rather than CommandContext<T>, so any command's context fits
+// without the generic having to be named at the call site.
+ctx, opts) {
+    return createLogger({
+        ...opts,
+        sink: opts?.sink ?? ctx.stderr,
+        level: opts?.level ?? levelFromArgs(ctx.args, opts),
+    });
+}
+/** A logger that discards everything, for tests and dry runs. */
+export const silentLogger = createLogger({ level: 'silent', sink: { write: PLAIN } });

package/dist/man.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Man page generation, matching the roff clap_mangen produces.
+ *
+ * A page carries the sections `man` expects in order: NAME, SYNOPSIS,
+ * DESCRIPTION, OPTIONS, SUBCOMMANDS, then the extra text, VERSION and AUTHORS.
+ * Subcommands get their own pages, named `parent-child.1` the way clap does.
+ */
+import type { CommandDef, ManOptions } from './types.js';
+export type { ManOptions } from './types.js';
+/**
+ * Render a man page for one command as roff source.
+ *
+ * ```ts
+ * writeFileSync('my-tool.1', renderManPage(command));
+ * ```
+ */
+export declare function renderManPage(command: CommandDef, opts?: ManOptions): string;
+/**
+ * Render a man page for the command and every subcommand beneath it, keyed by
+ * file name. Nested pages are named `parent-child.1`, as clap_mangen does.
+ *
+ * ```ts
+ * for (const [file, roff] of generateManPages(command)) {
+ *   writeFileSync(path.join(outDir, file), roff);
+ * }
+ * ```
+ */
+export declare function generateManPages(command: CommandDef, opts?: ManOptions): Map<string, string>;

package/dist/man.js

@@ -0,0 +1,234 @@
+/**
+ * Man page generation, matching the roff clap_mangen produces.
+ *
+ * A page carries the sections `man` expects in order: NAME, SYNOPSIS,
+ * DESCRIPTION, OPTIONS, SUBCOMMANDS, then the extra text, VERSION and AUTHORS.
+ * Subcommands get their own pages, named `parent-child.1` the way clap does.
+ */
+import { hasSubCommands, possibleValues, subCommandsOf } from './parser.js';
+// ---- Escaping ----
+/**
+ * Escape text for roff. A leading dot would start a request, a backslash starts
+ * an escape, a hyphen renders as a soft hyphen unless escaped, and an
+ * apostrophe goes through the \*(Aq string defined in the preamble.
+ */
+function esc(text) {
+    return text
+        .replaceAll('\\', '\\e')
+        .replaceAll("'", '\\*(Aq')
+        .replaceAll('-', '\\-')
+        .replaceAll(/^\./gm, '\\&.');
+}
+function bold(text) {
+    return `\\fB${esc(text)}\\fR`;
+}
+function italic(text) {
+    return `\\fI${esc(text)}\\fR`;
+}
+// ---- Arg helpers ----
+function valuePlaceholder(key, def) {
+    if (def.valueNames && def.valueNames.length > 0) {
+        return def.valueNames.map((n) => italic(n)).join(' ');
+    }
+    return italic(def.valueName ?? (def.long ?? key).toUpperCase());
+}
+/** The bracket pair around an option in the synopsis: required or optional. */
+function markers(def) {
+    return def.required ? ['', ''] : ['[', ']'];
+}
+/** `\fB-c\fR|\fB--config\fR` for one option, with its value if it takes one. */
+function optionForms(key, def) {
+    const forms = [];
+    if (def.short) {
+        forms.push(bold(`-${def.short}`));
+    }
+    forms.push(bold(`--${def.long ?? key}`));
+    let rendered = forms.join('|');
+    if (def.type !== 'boolean' && def.action !== 'count') {
+        rendered += `=${valuePlaceholder(key, def)}`;
+    }
+    return rendered;
+}
+function isVisible(def) {
+    return !def.hidden && !def.hideLongHelp;
+}
+// ---- Sections ----
+function renderSynopsis(name, command) {
+    const argsDef = command.args ?? {};
+    const parts = [bold(name)];
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type === 'positional' || !isVisible(def)) {
+            continue;
+        }
+        const [open, close] = markers(def);
+        const repeat = def.action === 'append' || def.action === 'count' ? '...' : '';
+        parts.push(`${open}${optionForms(key, def)}${close}${repeat}`);
+    }
+    if (command.meta.disableHelpFlag !== true) {
+        parts.push(`[${bold('-h')}|${bold('--help')}]`);
+    }
+    if (command.meta.version && command.meta.disableVersionFlag !== true) {
+        parts.push(`[${bold('-V')}|${bold('--version')}]`);
+    }
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type !== 'positional' || !isVisible(def)) {
+            continue;
+        }
+        const name_ = italic(def.valueName ?? key);
+        const repeat = def.trailingVarArg ? '...' : '';
+        parts.push(def.required ? `${name_}${repeat}` : `[${name_}]${repeat}`);
+    }
+    if (hasSubCommands(command)) {
+        parts.push(`[${italic('subcommands')}]`);
+    }
+    return parts.join(' ');
+}
+/** A `.TP` entry: the term, its description, then any trailing notes. */
+function renderEntry(term, def, key, lines) {
+    lines.push('.TP');
+    lines.push(term);
+    const description = def.longDescription ?? def.description ?? '';
+    lines.push(description ? esc(description) : '');
+    const notes = [];
+    if (def.default !== undefined && !def.hideDefaultValue) {
+        const shown = Array.isArray(def.default) ? def.default.join(', ') : String(def.default);
+        notes.push(`${italic('Default value:')} ${esc(shown)}`);
+    }
+    if (def.env && !def.hideEnv) {
+        notes.push(`${italic('Environment:')} ${esc(def.env)}`);
+    }
+    for (const note of notes) {
+        lines.push('.br');
+        lines.push(note);
+    }
+    const values = def.hidePossibleValues ? [] : possibleValues(def).filter((v) => !v.hidden);
+    if (values.length > 0) {
+        lines.push('.br');
+        lines.push(`${italic('Possible values:')}`);
+        lines.push('.RS 14');
+        for (const value of values) {
+            lines.push('.IP \\(bu 2');
+            lines.push(value.help ? `${esc(value.name)}: ${esc(value.help)}` : esc(value.name));
+        }
+        lines.push('.RE');
+    }
+    void key;
+}
+function renderOptions(command, lines) {
+    const argsDef = command.args ?? {};
+    const options = Object.entries(argsDef).filter(([, def]) => def.type !== 'positional' && isVisible(def));
+    const positionals = Object.entries(argsDef).filter(([, def]) => def.type === 'positional' && isVisible(def));
+    const hasHelp = command.meta.disableHelpFlag !== true;
+    const hasVersion = command.meta.version !== undefined && command.meta.disableVersionFlag !== true;
+    if (options.length === 0 && positionals.length === 0 && !hasHelp && !hasVersion) {
+        return false;
+    }
+    lines.push('.SH OPTIONS');
+    for (const [key, def] of options) {
+        const forms = [];
+        if (def.short) {
+            forms.push(bold(`-${def.short}`));
+        }
+        forms.push(bold(`--${def.long ?? key}`));
+        let term = forms.join(', ');
+        if (def.type !== 'boolean' && def.action !== 'count') {
+            term += `=${valuePlaceholder(key, def)}`;
+        }
+        renderEntry(term, def, key, lines);
+    }
+    if (hasHelp) {
+        lines.push('.TP', `${bold('-h')}, ${bold('--help')}`, 'Print help');
+    }
+    if (hasVersion) {
+        lines.push('.TP', `${bold('-V')}, ${bold('--version')}`, 'Print version');
+    }
+    for (const [key, def] of positionals) {
+        const name = italic(def.valueName ?? key);
+        renderEntry(def.required ? name : `[${name}]`, def, key, lines);
+    }
+    return true;
+}
+function renderSubcommands(name, command, lines) {
+    const subs = Object.entries(subCommandsOf(command)).filter(([, def]) => !def.meta.hidden);
+    if (subs.length === 0) {
+        return;
+    }
+    lines.push('.SH SUBCOMMANDS');
+    for (const [subName, def] of subs) {
+        lines.push('.TP');
+        lines.push(esc(`${name}-${subName}(1)`));
+        lines.push(esc(def.meta.description ?? def.meta.about ?? ''));
+    }
+}
+// ---- Public API ----
+/**
+ * Render a man page for one command as roff source.
+ *
+ * ```ts
+ * writeFileSync('my-tool.1', renderManPage(command));
+ * ```
+ */
+export function renderManPage(command, opts) {
+    const { meta } = command;
+    const name = opts?.name ?? meta.binName ?? meta.displayName ?? meta.name;
+    const section = opts?.section ?? '1';
+    const manual = opts?.manual ?? '';
+    const title = meta.version ? `${name} ${meta.version}` : name;
+    const lines = [
+        '.ie \\n(.g .ds Aq \\(aq',
+        ".el .ds Aq '",
+        `.TH ${esc(name)} ${esc(section)} "${esc(manual)}" "${esc(title)}"`,
+    ];
+    lines.push('.SH NAME');
+    const summary = meta.description ?? meta.about ?? '';
+    lines.push(summary ? `${esc(name)} \\- ${esc(summary)}` : esc(name));
+    lines.push('.SH SYNOPSIS');
+    lines.push(renderSynopsis(name, command));
+    lines.push('.SH DESCRIPTION');
+    const description = meta.longAbout ?? meta.about ?? meta.description ?? '';
+    if (description) {
+        lines.push(esc(description));
+    }
+    renderOptions(command, lines);
+    renderSubcommands(name, command, lines);
+    const extra = meta.afterLongHelp ?? meta.afterHelp;
+    if (extra) {
+        lines.push('.SH EXTRA');
+        lines.push(esc(extra));
+    }
+    if (meta.version) {
+        lines.push('.SH VERSION');
+        lines.push(`v${esc(meta.longVersion ?? meta.version)}`);
+    }
+    if (meta.author) {
+        lines.push('.SH AUTHORS');
+        lines.push(esc(meta.author));
+    }
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Render a man page for the command and every subcommand beneath it, keyed by
+ * file name. Nested pages are named `parent-child.1`, as clap_mangen does.
+ *
+ * ```ts
+ * for (const [file, roff] of generateManPages(command)) {
+ *   writeFileSync(path.join(outDir, file), roff);
+ * }
+ * ```
+ */
+export function generateManPages(command, opts) {
+    const pages = new Map();
+    const section = opts?.section ?? '1';
+    const walk = (node, name) => {
+        pages.set(`${name}.${section}`, renderManPage(node, { ...opts, name }));
+        for (const [subName, sub] of Object.entries(subCommandsOf(node))) {
+            if (sub.meta.hidden) {
+                continue;
+            }
+            walk(sub, `${name}-${subName}`);
+        }
+    };
+    const rootName = opts?.name ?? command.meta.binName ?? command.meta.name;
+    walk(command, rootName);
+    return pages;
+}