clap-ts 0.2.0 → 0.3.0

package/dist/help.js

@@ -7,25 +7,58 @@
  * and custom styles.
  */
 import { styleText } from 'node:util';
+import { hasSubCommands, possibleValues, subCommandsOf } from './parser.js';
 // ---- Color Support ----
-/** Get terminal width, defaulting to 80 if not available. */
-function getTerminalWidth() {
+/** Get terminal width, honouring termWidth and maxTermWidth, defaulting to 80. */
+function getTerminalWidth(meta) {
+    if (meta.termWidth !== undefined && meta.termWidth > 0) {
+        return meta.termWidth;
+    }
+    let width = 80;
     if (typeof process.stdout?.columns === 'number' && process.stdout.columns > 0) {
-        return process.stdout.columns;
+        width = process.stdout.columns;
+    }
+    if (meta.maxTermWidth !== undefined && meta.maxTermWidth > 0) {
+        width = Math.min(width, meta.maxTermWidth);
     }
-    return 80;
+    return width;
 }
 /** Create style functions, merging optional user overrides. */
-function createStyles(overrides) {
+const NO_STYLE = {
+    bold: (s) => s,
+    yellow: (s) => s,
+    green: (s) => s,
+    cyan: (s) => s,
+    heading: (s) => s,
+    flag: (s) => s,
+    value: (s) => s,
+    command: (s) => s,
+};
+/** Whether colour is on for this command: 'never' off, 'always' forced, else auto. */
+function colourEnabled(meta) {
+    if (meta.color === 'never' || meta.disableColoredHelp === true) {
+        return 'off';
+    }
+    return meta.color === 'always' ? 'force' : 'auto';
+}
+function createStyles(overrides, mode = 'auto') {
+    if (mode === 'off') {
+        return overrides ? { ...NO_STYLE, ...overrides } : NO_STYLE;
+    }
+    // styleText only colourises when it judges the stream capable; `always` goes
+    // around that check with the codes it would have used.
+    const paint = mode === 'force'
+        ? (codes, text) => styleText(codes, text, { validateStream: false })
+        : (codes, text) => styleText(codes, text);
     const defaults = {
-        bold: (s) => styleText('bold', s),
-        yellow: (s) => styleText('yellow', s),
-        green: (s) => styleText('green', s),
-        cyan: (s) => styleText('cyan', s),
-        heading: (s) => styleText(['bold', 'yellow'], s),
-        flag: (s) => styleText('green', s),
-        value: (s) => styleText('cyan', s),
-        command: (s) => styleText('bold', s),
+        bold: (s) => paint('bold', s),
+        yellow: (s) => paint('yellow', s),
+        green: (s) => paint('green', s),
+        cyan: (s) => paint('cyan', s),
+        heading: (s) => paint(['bold', 'yellow'], s),
+        flag: (s) => paint('green', s),
+        value: (s) => paint('cyan', s),
+        command: (s) => paint('bold', s),
     };
     if (!overrides) {
         return defaults;
@@ -35,7 +68,8 @@ function createStyles(overrides) {
 // ---- Help Text Helpers ----
 /** Wrap text to fit within a given width, preserving leading indent. */
 function wrapText(text, maxWidth, indent) {
-    if (text.length + indent <= maxWidth) {
+    const available = Math.max(MIN_DESC_WIDTH, maxWidth - indent);
+    if (text.length <= available) {
         return text;
     }
     const words = text.split(/\s+/);
@@ -46,7 +80,7 @@ function wrapText(text, maxWidth, indent) {
         if (currentLine.length === 0) {
             currentLine = word;
         }
-        else if (currentLine.length + 1 + word.length + indent <= maxWidth) {
+        else if (currentLine.length + 1 + word.length <= available) {
             currentLine += ` ${word}`;
         }
         else {
@@ -93,15 +127,14 @@ function formatArgFlag(key, def, styles) {
         }
     }
     // Value placeholder
-    if (def.type !== 'boolean' || def.valueName) {
-        const valueName = def.valueName ?? def.type.toUpperCase();
-        if (def.numArgs && def.numArgs.min === 0) {
-            parts.push(` ${styles.value(`[${valueName}]`)}`);
-            rawParts.push(` [${valueName}]`);
-        }
-        else {
-            parts.push(` ${styles.value(`<${valueName}>`)}`);
-            rawParts.push(` <${valueName}>`);
+    if (def.type !== 'boolean' || def.valueName || def.valueNames) {
+        const optional = def.numArgs !== undefined && def.numArgs.min === 0;
+        const open = optional ? '[' : '<';
+        const close = optional ? ']' : '>';
+        const names = def.valueNames ?? [def.valueName ?? def.type.toUpperCase()];
+        for (const name of names) {
+            parts.push(` ${styles.value(`${open}${name}${close}`)}`);
+            rawParts.push(` ${open}${name}${close}`);
         }
     }
     return {
@@ -112,27 +145,57 @@ function formatArgFlag(key, def, styles) {
 /** Build the description suffix: [default: x] [env: VAR] [possible values: a, b] */
 function formatArgSuffix(def) {
     const suffixes = [];
-    if (def.default !== undefined && def.type !== 'boolean') {
+    if (def.default !== undefined && def.type !== 'boolean' && !def.hideDefaultValue) {
         const defaultStr = Array.isArray(def.default) ? def.default.join(', ') : String(def.default);
         suffixes.push(`[default: ${defaultStr}]`);
     }
-    if (def.env) {
-        suffixes.push(`[env: ${def.env}]`);
+    if (def.env && !def.hideEnv) {
+        const current = def.hideEnvValues || def.secret ? undefined : process.env[def.env];
+        suffixes.push(current ? `[env: ${def.env}=${current}]` : `[env: ${def.env}]`);
     }
-    if (def.valueParser && Array.isArray(def.valueParser) && def.valueParser.length > 0 && !def.hidePossibleValues) {
-        suffixes.push(`[possible values: ${def.valueParser.join(', ')}]`);
+    if (!def.hidePossibleValues) {
+        const visible = possibleValues(def).filter((v) => !v.hidden);
+        if (visible.length > 0) {
+            suffixes.push(`[possible values: ${visible.map((v) => v.name).join(', ')}]`);
+        }
     }
     if (def.required) {
         suffixes.push('[required]');
     }
+    if (def.deprecated !== undefined && def.deprecated !== false) {
+        suffixes.push(typeof def.deprecated === 'string' ? `[deprecated: ${def.deprecated}]` : '[deprecated]');
+    }
     return suffixes.length > 0 ? ` ${suffixes.join(' ')}` : '';
 }
+/** Description for an arg, preferring the long form in long help. */
+function argDescription(def, isShortHelp) {
+    const base = (!isShortHelp && def.longDescription) || def.description || '';
+    return base + formatArgSuffix(def);
+}
+/** Sort help entries by displayOrder, keeping declaration order as the tiebreak. */
+function byDisplayOrder(entries, nextDisplayOrder) {
+    const hasExplicit = entries.some(([, def]) => def.displayOrder !== undefined);
+    if (!hasExplicit && nextDisplayOrder === undefined) {
+        return entries;
+    }
+    // Args without an explicit order fall in after nextDisplayOrder, keeping
+    // declaration order among themselves.
+    const implicitBase = nextDisplayOrder ?? Number.MAX_SAFE_INTEGER;
+    return entries
+        .map((entry, index) => ({
+        entry,
+        order: entry[1].displayOrder ?? implicitBase + index,
+        index,
+    }))
+        .sort((a, b) => a.order - b.order || a.index - b.index)
+        .map((wrapped) => wrapped.entry);
+}
 /** Append usage parts for options, positionals, and subcommands. */
 function appendUsageParts(usageParts, command) {
     const argsDef = command.args ?? {};
     const hasOptions = Object.values(argsDef).some((d) => d.type !== 'positional' && !d.hidden);
     const positionals = Object.entries(argsDef).filter(([_, d]) => d.type === 'positional');
-    const hasSubcommands = command.subCommands && Object.keys(command.subCommands).length > 0;
+    const hasSubcommands = hasSubCommands(command);
     if (hasOptions) {
         usageParts.push('[OPTIONS]');
     }
@@ -146,7 +209,7 @@ function appendUsageParts(usageParts, command) {
         }
     }
     if (hasSubcommands) {
-        usageParts.push('[COMMAND]');
+        usageParts.push(`[${command.meta.subcommandValueName ?? 'COMMAND'}]`);
     }
 }
 /** Check if an arg should be hidden based on help mode. */
@@ -162,18 +225,60 @@ function isArgHiddenForMode(def, isShortHelp) {
     }
     return false;
 }
+/** Below this many columns beside a flag, help drops to next-line layout. */
+const MIN_DESC_WIDTH = 20;
 /** Render aligned entries (flag + description with padding). */
 function renderAlignedEntries(entries, termWidth, lines) {
     if (entries.length === 0) {
         return;
     }
-    const maxLen = Math.max(...entries.map((e) => e.rawLen));
+    const inline = entries.filter((e) => !e.nextLine);
+    const maxLen = inline.length > 0 ? Math.max(...inline.map((e) => e.rawLen)) : 0;
     const descIndent = maxLen + 4;
+    // A narrow terminal leaves too little room beside the flag to wrap into, so
+    // the whole section drops to next-line help rather than overflowing.
+    const forceNextLine = termWidth - (descIndent + 2) < MIN_DESC_WIDTH;
     for (const entry of entries) {
-        const padding = ' '.repeat(Math.max(2, descIndent - entry.rawLen));
-        const wrappedDesc = wrapText(entry.desc, termWidth, descIndent + 2);
-        lines.push(`${entry.label}${padding}${wrappedDesc}`);
+        if (entry.nextLine || forceNextLine) {
+            lines.push(entry.label);
+            if (entry.desc) {
+                lines.push(`      ${wrapText(entry.desc, termWidth, 6)}`);
+            }
+        }
+        else if (entry.desc) {
+            const padding = ' '.repeat(Math.max(2, descIndent - entry.rawLen));
+            lines.push(`${entry.label}${padding}${wrapText(entry.desc, termWidth, descIndent)}`);
+        }
+        else {
+            lines.push(entry.label);
+        }
+        if (entry.detail) {
+            for (const line of entry.detail) {
+                lines.push(line);
+            }
+        }
+    }
+}
+/**
+ * Per-value help block, as clap renders under an option in long help:
+ *
+ *   Possible values:
+ *   - fast: skip the slow checks
+ */
+function possibleValueDetail(def, styles, isShortHelp) {
+    if (isShortHelp || def.hidePossibleValues) {
+        return undefined;
     }
+    const visible = possibleValues(def).filter((v) => !v.hidden);
+    if (!visible.some((v) => v.help)) {
+        return undefined;
+    }
+    const detail = ['', `      ${styles.heading('Possible values:')}`];
+    for (const value of visible) {
+        detail.push(`      - ${styles.value(value.name)}${value.help ? `: ${value.help}` : ''}`);
+    }
+    detail.push('');
+    return detail;
 }
 // ---- Template Rendering ----
 /**
@@ -189,19 +294,20 @@ function renderHelpTemplate(template, command, styles, termWidth, fullName, isSh
     appendUsageParts(usageParts, command);
     const usageStr = usageParts.join(' ');
     const argsLines = [];
-    renderPositionalSection(argsLines, argsDef, styles, termWidth, isShortHelp);
+    renderPositionalSection(argsLines, argsDef, styles, termWidth, isShortHelp, meta.nextDisplayOrder);
     const argumentsStr = argsLines.join('\n');
     const optLines = [];
     renderOptionsSection(optLines, argsDef, meta, styles, termWidth, isShortHelp);
     const optionsStr = optLines.join('\n');
     const cmdLines = [];
-    if (command.subCommands && Object.keys(command.subCommands).length > 0) {
+    if (hasSubCommands(command)) {
         renderSubcommandSection(cmdLines, command, styles, termWidth, fullName);
     }
     const commandsStr = cmdLines.join('\n');
     return template
         .replaceAll('{name}', meta.name)
         .replaceAll('{version}', meta.version ?? '')
+        .replaceAll('{author}', meta.author ?? '')
         .replaceAll('{about}', meta.about ?? meta.description ?? '')
         .replaceAll('{usage}', usageStr)
         .replaceAll('{all-args}', [argumentsStr, optionsStr].filter(Boolean).join('\n'))
@@ -213,7 +319,7 @@ function renderHelpTemplate(template, command, styles, termWidth, fullName, isSh
 }
 // ---- Section Renderers (extracted for reuse) ----
 /** Render positional arguments section. */
-function renderPositionalSection(lines, argsDef, styles, termWidth, isShortHelp) {
+function renderPositionalSection(lines, argsDef, styles, termWidth, isShortHelp, nextDisplayOrder) {
     const positionals = Object.entries(argsDef).filter(([_, d]) => d.type === 'positional');
     const visiblePositionals = positionals.filter(([_, d]) => !isArgHiddenForMode(d, isShortHelp));
     if (visiblePositionals.length === 0) {
@@ -221,12 +327,17 @@ function renderPositionalSection(lines, argsDef, styles, termWidth, isShortHelp)
     }
     lines.push(styles.heading('Arguments:'));
     const entries = [];
-    for (const [key, def] of visiblePositionals) {
+    for (const [key, def] of byDisplayOrder(visiblePositionals, nextDisplayOrder)) {
         const name = def.valueName ?? key.toUpperCase();
         const label = `  ${styles.value(`<${name}>`)}`;
         const rawLen = name.length + 4;
-        const desc = (def.description ?? '') + formatArgSuffix(def);
-        entries.push({ label, rawLen, desc });
+        entries.push({
+            label,
+            rawLen,
+            desc: argDescription(def, isShortHelp),
+            nextLine: def.nextLineHelp,
+            detail: possibleValueDetail(def, styles, isShortHelp),
+        });
     }
     renderAlignedEntries(entries, termWidth, lines);
 }
@@ -238,7 +349,7 @@ function renderOptionsSection(lines, argsDef, meta, styles, termWidth, isShortHe
     }
     // Group options by helpHeading
     const groups = new Map();
-    const defaultHeading = 'Options';
+    const defaultHeading = meta.nextHelpHeading ?? 'Options';
     for (const entry of options) {
         const heading = entry[1].helpHeading ?? defaultHeading;
         let group = groups.get(heading);
@@ -252,10 +363,15 @@ function renderOptionsSection(lines, argsDef, meta, styles, termWidth, isShortHe
         lines.push('');
         lines.push(styles.heading(`${heading}:`));
         const entries = [];
-        for (const [key, def] of groupOptions) {
+        for (const [key, def] of byDisplayOrder(groupOptions, meta.nextDisplayOrder)) {
             const { flag, rawLen } = formatArgFlag(key, def, styles);
-            const desc = (def.description ?? '') + formatArgSuffix(def);
-            entries.push({ label: `  ${flag}`, rawLen: rawLen + 2, desc });
+            entries.push({
+                label: `  ${flag}`,
+                rawLen: rawLen + 2,
+                desc: argDescription(def, isShortHelp),
+                nextLine: def.nextLineHelp,
+                detail: possibleValueDetail(def, styles, isShortHelp),
+            });
             // Boolean negation: --no-flag
             if (def.type === 'boolean' && def.negativeDescription) {
                 const longName = def.long ?? key;
@@ -270,11 +386,17 @@ function renderOptionsSection(lines, argsDef, meta, styles, termWidth, isShortHe
         }
         // Add built-in --help and --version to the default "Options" group
         if (heading === defaultHeading) {
-            const helpFlag = `  ${styles.flag('-h')}, ${styles.flag('--help')}`;
-            entries.push({ label: helpFlag, rawLen: 14, desc: 'Print help' });
-            if (meta.version) {
+            if (!meta.disableHelpFlag) {
+                const helpFlag = `  ${styles.flag('-h')}, ${styles.flag('--help')}`;
+                entries.push({ label: helpFlag, rawLen: '  -h, --help'.length, desc: 'Print help' });
+            }
+            if (meta.version && !meta.disableVersionFlag) {
                 const versionFlag = `  ${styles.flag('-V')}, ${styles.flag('--version')}`;
-                entries.push({ label: versionFlag, rawLen: 17, desc: 'Print version' });
+                entries.push({
+                    label: versionFlag,
+                    rawLen: '  -V, --version'.length,
+                    desc: 'Print version',
+                });
             }
         }
         renderAlignedEntries(entries, termWidth, lines);
@@ -288,21 +410,27 @@ function renderOptionsSection(lines, argsDef, meta, styles, termWidth, isShortHe
  */
 export function renderHelp(command, parentNames, isShortHelp = false, styleOverrides) {
     const { meta } = command;
-    const styles = createStyles(styleOverrides);
-    const termWidth = getTerminalWidth();
-    const fullName = parentNames ? [...parentNames, meta.name].join(' ') : meta.name;
+    if (meta.overrideHelp !== undefined) {
+        return meta.overrideHelp.endsWith('\n') ? meta.overrideHelp : `${meta.overrideHelp}\n`;
+    }
+    const styles = createStyles(styleOverrides, colourEnabled(meta));
+    const termWidth = getTerminalWidth(meta);
+    const usageName = meta.binName ?? meta.name;
+    const fullName = parentNames ? [...parentNames, usageName].join(' ') : usageName;
     // Custom template override
     if (meta.helpTemplate) {
         return renderHelpTemplate(meta.helpTemplate, command, styles, termWidth, fullName, isShortHelp);
     }
     const lines = [];
     // Before help text
-    if (meta.beforeHelp) {
-        lines.push(meta.beforeHelp);
+    const beforeHelp = (!isShortHelp && meta.beforeLongHelp) || meta.beforeHelp;
+    if (beforeHelp) {
+        lines.push(beforeHelp);
         lines.push('');
     }
     // Header: "Description (name vX.Y.Z)"
-    const nameVersion = meta.version ? `${meta.name} v${meta.version}` : meta.name;
+    const headerName = meta.displayName ?? meta.name;
+    const nameVersion = meta.version ? `${headerName} v${meta.version}` : headerName;
     const headerDesc = meta.about ?? meta.description ?? '';
     if (headerDesc) {
         lines.push(`${headerDesc} (${nameVersion})`);
@@ -317,13 +445,18 @@ export function renderHelp(command, parentNames, isShortHelp = false, styleOverr
     }
     lines.push('');
     // Usage line
-    const usageParts = [styles.heading('Usage:'), styles.command(fullName)];
-    appendUsageParts(usageParts, command);
-    lines.push(usageParts.join(' '));
+    if (meta.overrideUsage !== undefined) {
+        lines.push(`${styles.heading('Usage:')} ${meta.overrideUsage}`);
+    }
+    else {
+        const usageParts = [styles.heading('Usage:'), styles.command(fullName)];
+        appendUsageParts(usageParts, command);
+        lines.push(usageParts.join(' '));
+    }
     // Positional arguments
     const argsDef = command.args ?? {};
     const posLines = [];
-    renderPositionalSection(posLines, argsDef, styles, termWidth, isShortHelp);
+    renderPositionalSection(posLines, argsDef, styles, termWidth, isShortHelp, meta.nextDisplayOrder);
     if (posLines.length > 0) {
         lines.push('');
         lines.push(...posLines);
@@ -333,25 +466,55 @@ export function renderHelp(command, parentNames, isShortHelp = false, styleOverr
     renderOptionsSection(optLines, argsDef, meta, styles, termWidth, isShortHelp);
     lines.push(...optLines);
     // Subcommands
-    const hasSubcommands = command.subCommands && Object.keys(command.subCommands).length > 0;
+    const hasSubcommands = hasSubCommands(command);
     if (hasSubcommands) {
         renderSubcommandSection(lines, command, styles, termWidth, fullName);
     }
     // After help
-    if (meta.afterHelp) {
+    const afterHelp = (!isShortHelp && meta.afterLongHelp) || meta.afterHelp;
+    if (afterHelp) {
         lines.push('');
-        lines.push(meta.afterHelp);
+        lines.push(afterHelp);
     }
     lines.push('');
     return lines.join('\n');
 }
 /** Render the subcommands section of help output. */
+/**
+ * One indented line per visible arg of a subcommand, as clap's flatten_help
+ * shows so `git stash --help` can summarise `push` and `pop` in place.
+ */
+function flattenedSubcommandArgs(sub, styles) {
+    const argsDef = sub.args ?? {};
+    const visible = Object.entries(argsDef).filter(([, def]) => !def.hidden);
+    if (visible.length === 0) {
+        return undefined;
+    }
+    const named = visible.map(([key, def]) => ({
+        raw: def.type === 'positional'
+            ? `<${def.valueName ?? key.toUpperCase()}>`
+            : `--${def.long ?? key}`,
+        def,
+    }));
+    const width = Math.max(...named.map((n) => n.raw.length));
+    return named.map(({ raw, def }) => {
+        const painted = def.type === 'positional' ? styles.value(raw) : styles.flag(raw);
+        const padding = ' '.repeat(width - raw.length + 2);
+        return `      ${painted}${def.description ? `${padding}${def.description}` : ''}`;
+    });
+}
 function renderSubcommandSection(lines, command, styles, termWidth, fullName) {
+    const flatten = command.meta.flattenHelp === true;
     lines.push('');
-    lines.push(styles.heading('Commands:'));
+    lines.push(styles.heading(`${command.meta.subcommandHelpHeading ?? 'Commands'}:`));
     const subEntries = [];
     const rendered = new Set();
-    for (const [name, def] of Object.entries(command.subCommands)) {
+    const subs = Object.entries(subCommandsOf(command));
+    if (subs.some(([, def]) => def.meta.displayOrder !== undefined)) {
+        subs.sort((a, b) => (a[1].meta.displayOrder ?? Number.MAX_SAFE_INTEGER) -
+            (b[1].meta.displayOrder ?? Number.MAX_SAFE_INTEGER));
+    }
+    for (const [name, def] of subs) {
         if (def.meta.hidden) {
             continue;
         }
@@ -359,11 +522,24 @@ function renderSubcommandSection(lines, command, styles, termWidth, fullName) {
             continue;
         }
         rendered.add(name);
+        // Visible aliases and any flag form share the parenthesised suffix.
+        const extras = [...(def.meta.aliases ?? [])];
+        if (def.meta.shortFlag !== undefined) {
+            extras.push(`-${def.meta.shortFlag}`);
+        }
+        if (def.meta.longFlag !== undefined) {
+            extras.push(`--${def.meta.longFlag}`);
+        }
+        for (const alias of def.meta.visibleShortFlagAliases ?? []) {
+            extras.push(`-${alias}`);
+        }
+        for (const alias of def.meta.visibleLongFlagAliases ?? []) {
+            extras.push(`--${alias}`);
+        }
         let label;
         let rawLen;
-        const { aliases } = def.meta;
-        if (aliases && aliases.length > 0) {
-            const aliasStr = aliases.join(', ');
+        if (extras.length > 0) {
+            const aliasStr = extras.join(', ');
             label = `  ${styles.command(name)} (${aliasStr})`;
             rawLen = name.length + aliasStr.length + 5;
         }
@@ -371,8 +547,25 @@ function renderSubcommandSection(lines, command, styles, termWidth, fullName) {
             label = `  ${styles.command(name)}`;
             rawLen = name.length + 2;
         }
-        const desc = def.meta.description ?? '';
-        subEntries.push({ label, rawLen, desc });
+        const deprecated = def.meta.deprecated;
+        const note = deprecated === undefined || deprecated === false
+            ? ''
+            : typeof deprecated === 'string'
+                ? ` [deprecated: ${deprecated}]`
+                : ' [deprecated]';
+        subEntries.push({
+            label,
+            rawLen,
+            desc: (def.meta.description ?? '') + note,
+            detail: flatten ? flattenedSubcommandArgs(def, styles) : undefined,
+        });
+    }
+    if (!command.meta.disableHelpSubcommand) {
+        subEntries.push({
+            label: `  ${styles.command('help')}`,
+            rawLen: 6,
+            desc: 'Print this message or the help of the given subcommand(s)',
+        });
     }
     renderAlignedEntries(subEntries, termWidth, lines);
     lines.push('');
@@ -383,8 +576,12 @@ function renderSubcommandSection(lines, command, styles, termWidth, fullName) {
  */
 export function renderUsage(command, parentNames, styleOverrides) {
     const { meta } = command;
-    const styles = createStyles(styleOverrides);
-    const fullName = parentNames ? [...parentNames, meta.name].join(' ') : meta.name;
+    const styles = createStyles(styleOverrides, colourEnabled(meta));
+    if (meta.overrideUsage !== undefined) {
+        return `${styles.heading('Usage:')} ${meta.overrideUsage}`;
+    }
+    const usageName = meta.binName ?? meta.name;
+    const fullName = parentNames ? [...parentNames, usageName].join(' ') : usageName;
     const usageParts = [styles.heading('Usage:'), styles.command(fullName)];
     appendUsageParts(usageParts, command);
     return usageParts.join(' ');
@@ -392,23 +589,21 @@ export function renderUsage(command, parentNames, styleOverrides) {
 /**
  * Print help to stdout.
  */
-export function showHelp(command, parentNames, isShortHelp = false, styleOverrides) {
-    const text = renderHelp(command, parentNames, isShortHelp, styleOverrides);
-    process.stdout.write(text);
+export function showHelp(command, parentNames, isShortHelp = false, styleOverrides, out = process.stdout) {
+    out.write(renderHelp(command, parentNames, isShortHelp, styleOverrides));
 }
 /**
  * Print version to stdout.
  */
-export function showVersion(meta) {
-    const version = meta.version ?? '0.0.0';
-    process.stdout.write(`${meta.name} ${version}\n`);
+export function showVersion(meta, isShort = false, out = process.stdout) {
+    const version = (!isShort && meta.longVersion) || meta.version || '0.0.0';
+    out.write(`${meta.displayName ?? meta.name} ${version}\n`);
 }
 /**
  * Print an error message with usage hint.
  */
-export function showError(message, command, parentNames, styleOverrides) {
-    const styles = createStyles(styleOverrides);
+export function showError(message, command, parentNames, styleOverrides, out = process.stderr) {
+    const styles = createStyles(styleOverrides, colourEnabled(command.meta));
     const usage = renderUsage(command, parentNames, styleOverrides);
-    const output = `${styles.bold('error:')} ${message}\n\n${usage}\n\nFor more information, try '${styles.flag('--help')}'.\n`;
-    process.stderr.write(output);
+    out.write(`${styles.bold('error:')} ${message}\n\n${usage}\n\nFor more information, try '${styles.flag('--help')}'.\n`);
 }

package/dist/index.d.ts

@@ -3,9 +3,8 @@
  *
  * Re-exports all public API.
  */
-export type { ArgType, ArgAction, NumArgs, ValueParserFn, ValueHint, Shell, ArgDef, ArgsDef, StyleFn, StylesDef, CommandMeta, ArgGroup, ParsedArgs, CommandContext, CommandDef, RunOptions, ParseResult, InferArgValue, InferArgOptional, } from './types.js';
-export { parseArgs, getRawArgs, collectGlobalArgs, mergeGlobalArgs, CliParseError, } from './parser.js';
+export type { ArgType, ArgAction, NumArgs, ValueParserFn, PossibleValue, ValueHint, ColorChoice, ValueSource, Shell, OutputSink, MissingArg, ArgDef, ArgsDef, StyleFn, StylesDef, CommandMeta, ArgGroup, ParsedArgs, CommandContext, CommandDef, RunOptions, ParseResult, InferArgValue, InferArgOptional, } from './types.js';
+export { parseArgs, getRawArgs, collectGlobalArgs, mergeGlobalArgs, subCommandsOf, hasSubCommands, possibleValues, matchesPossibleValue, CliParseError, } from './parser.js';
 export { validate } from './validation.js';
 export { renderHelp, renderUsage, showHelp, showVersion, showError } from './help.js';
 export { defineCommand, defineArgs, defineArg, runCommand, runMain } from './runner.js';
-export { generateCompletions, withCompletions } from './completions.js';

package/dist/index.js

@@ -4,12 +4,12 @@
  * Re-exports all public API.
  */
 // Parser
-export { parseArgs, getRawArgs, collectGlobalArgs, mergeGlobalArgs, CliParseError, } from './parser.js';
+export { parseArgs, getRawArgs, collectGlobalArgs, mergeGlobalArgs, subCommandsOf, hasSubCommands, possibleValues, matchesPossibleValue, CliParseError, } from './parser.js';
 // Validation
 export { validate } from './validation.js';
 // Help renderer
 export { renderHelp, renderUsage, showHelp, showVersion, showError } from './help.js';
 // Runner (main API)
 export { defineCommand, defineArgs, defineArg, runCommand, runMain } from './runner.js';
-// Shell completions
-export { generateCompletions, withCompletions } from './completions.js';
+// Generators live behind subpaths so a running CLI never loads them:
+//   clap-ts/completions, clap-ts/man, clap-ts/markdown

package/dist/install.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 type { CommandDef, Shell } from './types.js';
+/** Where a shell looks for user completions, and what the file must be called. */
+export interface CompletionTarget {
+    readonly dir: string;
+    readonly file: string;
+    /** A line the user must add themselves, when sourcing is not automatic. */
+    readonly manualStep?: string;
+}
+/**
+ * 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 declare function completionTarget(shell: Shell, binaryName: string): CompletionTarget;
+/** What an install did, or would have done. */
+export interface InstallResult {
+    readonly paths: readonly string[];
+    readonly manualStep?: string;
+    readonly dryRun: boolean;
+}
+export interface InstallOptions {
+    /** Report the paths without writing anything. */
+    readonly dryRun?: boolean;
+    /** Write here instead of the per-user location. */
+    readonly dir?: string;
+    /** Binary name; defaults to the command's binName or name. */
+    readonly binaryName?: string;
+}
+/** Write the completion script for one shell to its per-user location. */
+export declare function installCompletions(command: CommandDef, shell: Shell, opts?: InstallOptions): InstallResult;
+/** Write a man page per command into the per-user man directory. */
+export declare function installManPages(command: CommandDef, opts?: InstallOptions): InstallResult;
+/**
+ * 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 declare function withInstallers(rootCommand: CommandDef<any>): CommandDef<any>;