clap-ts 0.1.0

package/dist/help.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Help renderer - generates clap-style help output.
+ * Respects NO_COLOR, TERM=dumb, CI for color output.
+ * Wraps text to terminal width.
+ * Supports helpHeading grouping, helpTemplate, beforeHelp,
+ * hideShortHelp/hideLongHelp, visibleAlias, hidePossibleValues,
+ * and custom styles.
+ */
+import type { CommandDef, CommandMeta, StylesDef } from './types.js';
+/**
+ * Render the full help text for a command.
+ * Matches clap's help format. Supports helpTemplate override,
+ * helpHeading grouping, beforeHelp, and help mode filtering.
+ */
+export declare function renderHelp(command: CommandDef, parentNames?: string[], isShortHelp?: boolean, styleOverrides?: Partial<StylesDef>): string;
+/**
+ * Render a short usage message (shown on errors).
+ */
+export declare function renderUsage(command: CommandDef, parentNames?: string[], styleOverrides?: Partial<StylesDef>): string;
+/**
+ * Print help to stdout.
+ */
+export declare function showHelp(command: CommandDef, parentNames?: string[], isShortHelp?: boolean, styleOverrides?: Partial<StylesDef>): void;
+/**
+ * Print version to stdout.
+ */
+export declare function showVersion(meta: CommandMeta): void;
+/**
+ * Print an error message with usage hint.
+ */
+export declare function showError(message: string, command: CommandDef, parentNames?: string[], styleOverrides?: Partial<StylesDef>): void;

package/dist/help.js

@@ -0,0 +1,414 @@
+/**
+ * Help renderer - generates clap-style help output.
+ * Respects NO_COLOR, TERM=dumb, CI for color output.
+ * Wraps text to terminal width.
+ * Supports helpHeading grouping, helpTemplate, beforeHelp,
+ * hideShortHelp/hideLongHelp, visibleAlias, hidePossibleValues,
+ * and custom styles.
+ */
+import { styleText } from 'node:util';
+// ---- Color Support ----
+/** Get terminal width, defaulting to 80 if not available. */
+function getTerminalWidth() {
+    if (typeof process.stdout?.columns === 'number' && process.stdout.columns > 0) {
+        return process.stdout.columns;
+    }
+    return 80;
+}
+/** Create style functions, merging optional user overrides. */
+function createStyles(overrides) {
+    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),
+    };
+    if (!overrides) {
+        return defaults;
+    }
+    return { ...defaults, ...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) {
+        return text;
+    }
+    const words = text.split(/\s+/);
+    const lines = [];
+    let currentLine = '';
+    const padding = ' '.repeat(indent);
+    for (const word of words) {
+        if (currentLine.length === 0) {
+            currentLine = word;
+        }
+        else if (currentLine.length + 1 + word.length + indent <= maxWidth) {
+            currentLine += ` ${word}`;
+        }
+        else {
+            lines.push(currentLine);
+            currentLine = word;
+        }
+    }
+    if (currentLine.length > 0) {
+        lines.push(currentLine);
+    }
+    return lines.join(`\n${padding}`);
+}
+/** Format a flag string for display: "-s, --long, --visible-alias <VALUE>" */
+function formatArgFlag(key, def, styles) {
+    const parts = [];
+    const rawParts = [];
+    // Short flag
+    if (def.short) {
+        parts.push(styles.flag(`-${def.short}`));
+        rawParts.push(`-${def.short}`);
+    }
+    // Long flag
+    const longName = def.long ?? key;
+    if (def.short) {
+        parts.push(`, ${styles.flag(`--${longName}`)}`);
+        rawParts.push(`, --${longName}`);
+    }
+    else {
+        // Pad to align with flags that have short
+        parts.push(`    ${styles.flag(`--${longName}`)}`);
+        rawParts.push(`    --${longName}`);
+    }
+    // Visible aliases (shown in help, unlike hidden aliases)
+    if (def.visibleAlias) {
+        for (const alias of def.visibleAlias) {
+            if (alias.length === 1) {
+                parts.push(`, ${styles.flag(`-${alias}`)}`);
+                rawParts.push(`, -${alias}`);
+            }
+            else {
+                parts.push(`, ${styles.flag(`--${alias}`)}`);
+                rawParts.push(`, --${alias}`);
+            }
+        }
+    }
+    // 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}>`);
+        }
+    }
+    return {
+        flag: parts.join(''),
+        rawLen: rawParts.join('').length,
+    };
+}
+/** Build the description suffix: [default: x] [env: VAR] [possible values: a, b] */
+function formatArgSuffix(def) {
+    const suffixes = [];
+    if (def.default !== undefined && def.type !== 'boolean') {
+        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.valueParser && Array.isArray(def.valueParser) && def.valueParser.length > 0 && !def.hidePossibleValues) {
+        suffixes.push(`[possible values: ${def.valueParser.join(', ')}]`);
+    }
+    if (def.required) {
+        suffixes.push('[required]');
+    }
+    return suffixes.length > 0 ? ` ${suffixes.join(' ')}` : '';
+}
+/** 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;
+    if (hasOptions) {
+        usageParts.push('[OPTIONS]');
+    }
+    for (const [key, def] of positionals) {
+        const name = def.valueName ?? key.toUpperCase();
+        if (def.required) {
+            usageParts.push(`<${name}>`);
+        }
+        else {
+            usageParts.push(`[${name}]`);
+        }
+    }
+    if (hasSubcommands) {
+        usageParts.push('[COMMAND]');
+    }
+}
+/** Check if an arg should be hidden based on help mode. */
+function isArgHiddenForMode(def, isShortHelp) {
+    if (def.hidden) {
+        return true;
+    }
+    if (isShortHelp && def.hideShortHelp) {
+        return true;
+    }
+    if (!isShortHelp && def.hideLongHelp) {
+        return true;
+    }
+    return false;
+}
+/** 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 descIndent = maxLen + 4;
+    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}`);
+    }
+}
+// ---- Template Rendering ----
+/**
+ * Render help using a custom template with placeholders.
+ * Placeholders: {name}, {version}, {about}, {usage}, {all-args},
+ * {arguments}, {options}, {commands}, {before-help}, {after-help}
+ */
+function renderHelpTemplate(template, command, styles, termWidth, fullName, isShortHelp) {
+    const { meta } = command;
+    const argsDef = command.args ?? {};
+    // Build each section as a string
+    const usageParts = [styles.heading('Usage:'), styles.command(fullName)];
+    appendUsageParts(usageParts, command);
+    const usageStr = usageParts.join(' ');
+    const argsLines = [];
+    renderPositionalSection(argsLines, argsDef, styles, termWidth, isShortHelp);
+    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) {
+        renderSubcommandSection(cmdLines, command, styles, termWidth, fullName);
+    }
+    const commandsStr = cmdLines.join('\n');
+    return template
+        .replaceAll('{name}', meta.name)
+        .replaceAll('{version}', meta.version ?? '')
+        .replaceAll('{about}', meta.about ?? meta.description ?? '')
+        .replaceAll('{usage}', usageStr)
+        .replaceAll('{all-args}', [argumentsStr, optionsStr].filter(Boolean).join('\n'))
+        .replaceAll('{arguments}', argumentsStr)
+        .replaceAll('{options}', optionsStr)
+        .replaceAll('{commands}', commandsStr)
+        .replaceAll('{before-help}', meta.beforeHelp ?? '')
+        .replaceAll('{after-help}', meta.afterHelp ?? '');
+}
+// ---- Section Renderers (extracted for reuse) ----
+/** Render positional arguments section. */
+function renderPositionalSection(lines, argsDef, styles, termWidth, isShortHelp) {
+    const positionals = Object.entries(argsDef).filter(([_, d]) => d.type === 'positional');
+    const visiblePositionals = positionals.filter(([_, d]) => !isArgHiddenForMode(d, isShortHelp));
+    if (visiblePositionals.length === 0) {
+        return;
+    }
+    lines.push(styles.heading('Arguments:'));
+    const entries = [];
+    for (const [key, def] of visiblePositionals) {
+        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 });
+    }
+    renderAlignedEntries(entries, termWidth, lines);
+}
+/** Render options section, grouped by helpHeading. */
+function renderOptionsSection(lines, argsDef, meta, styles, termWidth, isShortHelp) {
+    const options = Object.entries(argsDef).filter(([_, d]) => d.type !== 'positional' && !isArgHiddenForMode(d, isShortHelp));
+    if (options.length === 0) {
+        return;
+    }
+    // Group options by helpHeading
+    const groups = new Map();
+    const defaultHeading = 'Options';
+    for (const entry of options) {
+        const heading = entry[1].helpHeading ?? defaultHeading;
+        let group = groups.get(heading);
+        if (!group) {
+            group = [];
+            groups.set(heading, group);
+        }
+        group.push(entry);
+    }
+    for (const [heading, groupOptions] of groups) {
+        lines.push('');
+        lines.push(styles.heading(`${heading}:`));
+        const entries = [];
+        for (const [key, def] of groupOptions) {
+            const { flag, rawLen } = formatArgFlag(key, def, styles);
+            const desc = (def.description ?? '') + formatArgSuffix(def);
+            entries.push({ label: `  ${flag}`, rawLen: rawLen + 2, desc });
+            // Boolean negation: --no-flag
+            if (def.type === 'boolean' && def.negativeDescription) {
+                const longName = def.long ?? key;
+                const negFlag = `    ${styles.flag(`--no-${longName}`)}`;
+                const negRawLen = longName.length + 10;
+                entries.push({
+                    label: `  ${negFlag}`,
+                    rawLen: negRawLen + 2,
+                    desc: def.negativeDescription,
+                });
+            }
+        }
+        // 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) {
+                const versionFlag = `  ${styles.flag('-V')}, ${styles.flag('--version')}`;
+                entries.push({ label: versionFlag, rawLen: 17, desc: 'Print version' });
+            }
+        }
+        renderAlignedEntries(entries, termWidth, lines);
+    }
+}
+// ---- Main Renderer ----
+/**
+ * Render the full help text for a command.
+ * Matches clap's help format. Supports helpTemplate override,
+ * helpHeading grouping, beforeHelp, and help mode filtering.
+ */
+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;
+    // 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);
+        lines.push('');
+    }
+    // Header: "Description (name vX.Y.Z)"
+    const nameVersion = meta.version ? `${meta.name} v${meta.version}` : meta.name;
+    const headerDesc = meta.about ?? meta.description ?? '';
+    if (headerDesc) {
+        lines.push(`${headerDesc} (${nameVersion})`);
+    }
+    else {
+        lines.push(nameVersion);
+    }
+    // Long about (if any, only in long help mode)
+    if (meta.longAbout && !isShortHelp) {
+        lines.push('');
+        lines.push(meta.longAbout);
+    }
+    lines.push('');
+    // Usage line
+    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);
+    if (posLines.length > 0) {
+        lines.push('');
+        lines.push(...posLines);
+    }
+    // Options (grouped by helpHeading)
+    const optLines = [];
+    renderOptionsSection(optLines, argsDef, meta, styles, termWidth, isShortHelp);
+    lines.push(...optLines);
+    // Subcommands
+    const hasSubcommands = command.subCommands && Object.keys(command.subCommands).length > 0;
+    if (hasSubcommands) {
+        renderSubcommandSection(lines, command, styles, termWidth, fullName);
+    }
+    // After help
+    if (meta.afterHelp) {
+        lines.push('');
+        lines.push(meta.afterHelp);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/** Render the subcommands section of help output. */
+function renderSubcommandSection(lines, command, styles, termWidth, fullName) {
+    lines.push('');
+    lines.push(styles.heading('Commands:'));
+    const subEntries = [];
+    const rendered = new Set();
+    for (const [name, def] of Object.entries(command.subCommands)) {
+        if (def.meta.hidden) {
+            continue;
+        }
+        if (rendered.has(name)) {
+            continue;
+        }
+        rendered.add(name);
+        let label;
+        let rawLen;
+        const { aliases } = def.meta;
+        if (aliases && aliases.length > 0) {
+            const aliasStr = aliases.join(', ');
+            label = `  ${styles.command(name)} (${aliasStr})`;
+            rawLen = name.length + aliasStr.length + 5;
+        }
+        else {
+            label = `  ${styles.command(name)}`;
+            rawLen = name.length + 2;
+        }
+        const desc = def.meta.description ?? '';
+        subEntries.push({ label, rawLen, desc });
+    }
+    renderAlignedEntries(subEntries, termWidth, lines);
+    lines.push('');
+    lines.push(`Use ${styles.command(`${fullName} <command> --help`)} for more information about a command.`);
+}
+/**
+ * Render a short usage message (shown on errors).
+ */
+export function renderUsage(command, parentNames, styleOverrides) {
+    const { meta } = command;
+    const styles = createStyles(styleOverrides);
+    const fullName = parentNames ? [...parentNames, meta.name].join(' ') : meta.name;
+    const usageParts = [styles.heading('Usage:'), styles.command(fullName)];
+    appendUsageParts(usageParts, command);
+    return usageParts.join(' ');
+}
+/**
+ * Print help to stdout.
+ */
+export function showHelp(command, parentNames, isShortHelp = false, styleOverrides) {
+    const text = renderHelp(command, parentNames, isShortHelp, styleOverrides);
+    process.stdout.write(text);
+}
+/**
+ * Print version to stdout.
+ */
+export function showVersion(meta) {
+    const version = meta.version ?? '0.0.0';
+    process.stdout.write(`${meta.name} ${version}\n`);
+}
+/**
+ * Print an error message with usage hint.
+ */
+export function showError(message, command, parentNames, styleOverrides) {
+    const styles = createStyles(styleOverrides);
+    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);
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * clap-ts - A type-safe CLI argument parser for TypeScript, inspired by Rust's clap.
+ *
+ * Re-exports all public API.
+ */
+export type { ArgType, ArgAction, NumArgs, ValueParserFn, 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 { validate } from './validation.js';
+export { renderHelp, renderUsage, showHelp, showVersion, showError } from './help.js';
+export { defineCommand, defineArgs, defineArg, runCommand, runMain } from './runner.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * clap-ts - A type-safe CLI argument parser for TypeScript, inspired by Rust's clap.
+ *
+ * Re-exports all public API.
+ */
+// Parser
+export { parseArgs, getRawArgs, collectGlobalArgs, mergeGlobalArgs, 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';

package/dist/parser.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Argument parser - delegates core tokenizing to node:util parseArgs,
+ * then layers on: env fallback, type coercion, count/append actions,
+ * numArgs with defaultMissingValue, global args, kebab-to-camel mapping,
+ * subcommand detection, and default values.
+ *
+ * node:util parseArgs handles:
+ *   --flag, --flag=value, --flag value, -f, -fvalue, -abc (combined booleans),
+ *   -- separator, positionals
+ *
+ * We handle on top:
+ *   conflictsWith / requires (in validation.ts),
+ *   env variable fallback, action: 'append' (via multiple:true), action: 'count',
+ *   numArgs with defaultMissingValue, global args merge, valueParser enum validation
+ *   (in validation.ts), number type coercion, kebab-to-camel mapping,
+ *   required arg validation (in validation.ts), typo suggestions (in validation.ts),
+ *   valueDelimiter splitting, function valueParser, trailingVarArg, last,
+ *   allowHyphenValues, allowNegativeNumbers, inferLongArgs, defaultValueIf.
+ */
+import type { ArgsDef, ParseResult, CommandDef } from './types.js';
+/** Get the raw argv slice (after the binary/script path). */
+export declare function getRawArgs(argv?: readonly string[]): string[];
+export declare class CliParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse raw argument tokens against a command definition.
+ *
+ * Uses node:util parseArgs for core tokenizing, then layers on all clap-ts features.
+ */
+export declare function parseArgs(rawArgs: readonly string[], command: CommandDef): ParseResult;
+/**
+ * Collect global args from a command.
+ * Returns a merged ArgsDef of all global args.
+ */
+export declare function collectGlobalArgs(command: CommandDef): ArgsDef;
+/**
+ * Merge global args into a subcommand's args.
+ * Global args from the parent are added to the child unless the child
+ * already defines an arg with the same name.
+ */
+export declare function mergeGlobalArgs(parentGlobals: ArgsDef, childArgs: ArgsDef): ArgsDef;