clap-ts 0.1.0

package/dist/runner.js

@@ -0,0 +1,370 @@
+/**
+ * Command runner - entry point for CLI execution.
+ * Handles subcommand resolution, lifecycle hooks, error handling.
+ * Supports inferSubcommands, subcommandRequired, allowExternalSubcommands,
+ * argsConflictsWithSubcommands, argRequiredElseHelp, and custom styles.
+ */
+import { CliParseError, collectGlobalArgs, getRawArgs, mergeGlobalArgs, parseArgs, } from './parser.js';
+import { validate } from './validation.js';
+import { showError, showHelp, showVersion } from './help.js';
+// ---- defineCommand ----
+/**
+ * Define a command with full type inference on arguments.
+ * This is the primary API for creating commands.
+ *
+ * ```ts
+ * const cmd = defineCommand({
+ *   meta: { name: 'my-tool', version: '1.0.0', description: 'My tool' },
+ *   args: {
+ *     verbose: { type: 'boolean', short: 'v', description: 'Verbose output' },
+ *     port: { type: 'number', short: 'p', default: 3000, description: 'Port' },
+ *   },
+ *   run({ args }) {
+ *     console.log(args.verbose, args.port);
+ *   },
+ * });
+ * ```
+ */
+export function defineCommand(def) {
+    return def;
+}
+// ---- defineArgs / defineArg ----
+/**
+ * Define a reusable argument group with full type inference.
+ * Use this for shared args that are spread into multiple commands.
+ *
+ * ```ts
+ * const envArgs = defineArgs({
+ *   env: { type: 'string', valueParser: ['dev', 'staging', 'prod'] },
+ *   dev: { type: 'boolean', conflictsWith: ['env', 'staging', 'prod'] },
+ * });
+ * ```
+ */
+export function defineArgs(args) {
+    return args;
+}
+/**
+ * Define a single argument with full type inference.
+ *
+ * ```ts
+ * const portArg = defineArg({ type: 'number', short: 'p', default: 3003 });
+ * ```
+ */
+export function defineArg(arg) {
+    return arg;
+}
+// ---- Subcommand Resolution ----
+/**
+ * Find a subcommand by prefix matching (inferSubcommands).
+ * Returns the match if exactly one, 'ambiguous' if multiple, undefined if none.
+ */
+function findSubcommandByPrefix(subCommands, token) {
+    const matches = [];
+    for (const [name, def] of Object.entries(subCommands)) {
+        if (name.startsWith(token)) {
+            matches.push({ name, def });
+        }
+        else if (def.meta.aliases?.some((a) => a.startsWith(token))) {
+            matches.push({ name, def });
+        }
+    }
+    if (matches.length === 1) {
+        return matches[0];
+    }
+    if (matches.length > 1) {
+        return 'ambiguous';
+    }
+    return undefined;
+}
+/**
+ * Resolve the command chain from the root command and raw args.
+ * Supports inferSubcommands for prefix matching.
+ */
+function resolveCommandChain(rootCommand, rawArgs) {
+    let current = rootCommand;
+    const parentNames = [];
+    const remaining = [...rawArgs];
+    while (remaining.length > 0 && (current.subCommands || current.meta.allowExternalSubcommands)) {
+        const token = remaining[0];
+        // Don't interpret flags as subcommands
+        if (token.startsWith('-')) {
+            break;
+        }
+        // Direct match
+        if (current.subCommands) {
+            const subCmd = current.subCommands[token];
+            if (subCmd) {
+                parentNames.push(current.meta.name);
+                current = subCmd;
+                remaining.shift();
+                continue;
+            }
+            // Alias match
+            const aliasMatch = findSubcommandByAlias(current.subCommands, token);
+            if (aliasMatch) {
+                parentNames.push(current.meta.name);
+                current = aliasMatch;
+                remaining.shift();
+                continue;
+            }
+            // inferSubcommands: try prefix matching
+            if (current.meta.inferSubcommands) {
+                const prefixMatch = findSubcommandByPrefix(current.subCommands, token);
+                if (prefixMatch === 'ambiguous') {
+                    break;
+                }
+                if (prefixMatch) {
+                    parentNames.push(current.meta.name);
+                    current = prefixMatch.def;
+                    remaining.shift();
+                    continue;
+                }
+            }
+        }
+        // allowExternalSubcommands: accept unknown subcommand and stop
+        if (current.meta.allowExternalSubcommands) {
+            remaining.shift();
+            return { command: current, remainingArgs: remaining, parentNames, externalSubcommand: token };
+        }
+        // Not a subcommand, stop resolution
+        break;
+    }
+    return { command: current, remainingArgs: remaining, parentNames };
+}
+/** Find a subcommand definition by alias. */
+function findSubcommandByAlias(subCommands, token) {
+    for (const def of Object.values(subCommands)) {
+        if (def.meta.aliases?.includes(token)) {
+            return def;
+        }
+    }
+    return undefined;
+}
+// ---- runCommand ----
+/**
+ * Run a specific command with pre-parsed arguments.
+ * Executes the setup -> run -> cleanup lifecycle.
+ */
+export async function runCommand(command, args, rawArgs = [], subCommand) {
+    const ctx = {
+        rawArgs,
+        args,
+        cmd: command,
+        subCommand,
+        data: {},
+    };
+    let runError;
+    // Setup phase
+    if (command.setup) {
+        await command.setup(ctx);
+    }
+    // Run phase
+    try {
+        if (command.run) {
+            await command.run(ctx);
+        }
+    }
+    catch (error) {
+        runError = error;
+    }
+    // Cleanup phase (always runs)
+    if (command.cleanup) {
+        try {
+            await command.cleanup(ctx);
+        }
+        catch (error) {
+            runError ??= error;
+        }
+    }
+    if (runError) {
+        if (runError instanceof Error) {
+            throw runError;
+        }
+        throw new Error(JSON.stringify(runError));
+    }
+}
+// ---- Typo Suggestion ----
+/** Collect all known subcommand names and aliases from a command. */
+function collectSubcommandNames(subCommands) {
+    const names = Object.keys(subCommands);
+    for (const def of Object.values(subCommands)) {
+        if (def.meta.aliases) {
+            names.push(...def.meta.aliases);
+        }
+    }
+    return names;
+}
+/**
+ * Find the closest match for a string among candidates using simple character diff.
+ */
+function findClosestSubcommand(target, candidates) {
+    const a = target.toLowerCase();
+    let bestMatch;
+    let bestDist = 4;
+    for (const name of candidates) {
+        const b = name.toLowerCase();
+        const dist = simpleCharDistance(a, b, bestDist);
+        if (dist < bestDist) {
+            bestDist = dist;
+            bestMatch = name;
+        }
+    }
+    return bestMatch;
+}
+/** Quick character-level distance heuristic. */
+function simpleCharDistance(a, b, maxDist) {
+    if (Math.abs(a.length - b.length) >= maxDist) {
+        return maxDist;
+    }
+    let dist = Math.abs(a.length - b.length);
+    const minLen = Math.min(a.length, b.length);
+    for (let i = 0; i < minLen; i++) {
+        if (a[i] !== b[i]) {
+            dist++;
+        }
+    }
+    return dist;
+}
+// ---- runMain helpers ----
+/** Handle --help request with mode and style support. */
+function handleHelpRequest(command, parentNames, shouldExit, isShortHelp, styles) {
+    showHelp(command, parentNames.length > 0 ? parentNames : undefined, isShortHelp, styles);
+    if (shouldExit) {
+        process.exit(0);
+    }
+}
+/** Handle --version request. */
+function handleVersionRequest(effectiveCommand, rootCommand, shouldExit) {
+    const versionMeta = effectiveCommand.meta.version ? effectiveCommand.meta : rootCommand.meta;
+    showVersion(versionMeta);
+    if (shouldExit) {
+        process.exit(0);
+    }
+}
+/** Handle an unrecognized subcommand with typo suggestion. */
+function handleUnrecognizedSubcommand(unknownName, command, parentNames, shouldExit, styles) {
+    const allNames = collectSubcommandNames(command.subCommands);
+    let msg = `unrecognized subcommand '${unknownName}'`;
+    const bestMatch = findClosestSubcommand(unknownName, allNames);
+    if (bestMatch) {
+        msg += `\n\n  tip: a similar subcommand exists: '${bestMatch}'`;
+    }
+    showError(msg, command, parentNames.length > 0 ? parentNames : undefined, styles);
+    if (shouldExit) {
+        process.exit(2);
+    }
+}
+// ---- runMain ----
+/**
+ * Main entry point for CLI applications.
+ * Parses args, resolves subcommands, validates, and runs.
+ *
+ * ```ts
+ * const main = defineCommand({ ... });
+ * runMain(main);
+ * ```
+ */
+export async function runMain(rootCommand, opts) {
+    const shouldExit = opts?.exit !== false;
+    const showHelpOnEmpty = opts?.showHelpOnEmpty !== false;
+    const styles = opts?.styles;
+    try {
+        const rawArgs = getRawArgs(opts?.argv);
+        // Resolve subcommand chain (with inferSubcommands and allowExternalSubcommands)
+        const { command, remainingArgs, parentNames, externalSubcommand } = resolveCommandChain(rootCommand, rawArgs);
+        // Handle external subcommand: pass to parent command's run handler
+        if (externalSubcommand) {
+            if (command.run) {
+                await runCommand(command, {}, remainingArgs, externalSubcommand);
+            }
+            return;
+        }
+        // Merge global args from parent into resolved command
+        const globalArgs = collectGlobalArgs(rootCommand);
+        const effectiveCommand = {
+            ...command,
+            args: command.args ? mergeGlobalArgs(globalArgs, command.args) : globalArgs,
+        };
+        // Parse remaining args against the resolved command
+        const parseResult = parseArgs(remainingArgs, effectiveCommand);
+        // Handle --help
+        if (parseResult.helpRequested) {
+            handleHelpRequest(effectiveCommand, parentNames, shouldExit, parseResult.helpIsShort, styles);
+            return;
+        }
+        // Handle --version
+        if (parseResult.versionRequested) {
+            handleVersionRequest(effectiveCommand, rootCommand, shouldExit);
+            return;
+        }
+        // Show help if no args and command has subcommands
+        if (showHelpOnEmpty &&
+            rawArgs.length === 0 &&
+            rootCommand.subCommands &&
+            Object.keys(rootCommand.subCommands).length > 0) {
+            handleHelpRequest(rootCommand, [], shouldExit, false, styles);
+            return;
+        }
+        // argRequiredElseHelp: show help if no args were explicitly provided
+        if (command.meta.argRequiredElseHelp && parseResult.explicitlySet.size === 0) {
+            handleHelpRequest(command, parentNames, shouldExit, false, styles);
+            return;
+        }
+        // If we resolved to a parent command that has subcommands but no run handler,
+        // and the user didn't pass a valid subcommand, show help or error
+        if (command.subCommands &&
+            Object.keys(command.subCommands).length > 0 &&
+            !command.run &&
+            !parseResult.subCommand) {
+            // subcommandRequired: error if no subcommand
+            if (command.meta.subcommandRequired) {
+                if (parseResult.positionals.length > 0) {
+                    handleUnrecognizedSubcommand(parseResult.positionals[0], command, parentNames, shouldExit, styles);
+                }
+                else {
+                    showError("a subcommand is required but one was not provided", command, parentNames.length > 0 ? parentNames : undefined, styles);
+                    if (shouldExit) {
+                        process.exit(2);
+                    }
+                }
+                return;
+            }
+            if (parseResult.positionals.length > 0) {
+                handleUnrecognizedSubcommand(parseResult.positionals[0], command, parentNames, shouldExit, styles);
+                return;
+            }
+            handleHelpRequest(command, parentNames, shouldExit, false, styles);
+            return;
+        }
+        // argsConflictsWithSubcommands: error if args + subcommand both present
+        if (command.meta.argsConflictsWithSubcommands &&
+            parseResult.subCommand &&
+            parseResult.explicitlySet.size > 0) {
+            showError("arguments cannot be used with subcommands", command, parentNames.length > 0 ? parentNames : undefined, styles);
+            if (shouldExit) {
+                process.exit(2);
+            }
+            return;
+        }
+        // Validate parsed args
+        validate(parseResult, effectiveCommand);
+        // Run the command
+        await runCommand(effectiveCommand, parseResult.args, rawArgs);
+    }
+    catch (error) {
+        if (error instanceof CliParseError) {
+            showError(error.message, rootCommand, undefined, styles);
+            if (shouldExit) {
+                process.exit(2);
+            }
+            return;
+        }
+        // Unexpected error
+        if (shouldExit) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`error: ${message}\n`);
+            process.exit(1);
+        }
+        throw error;
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Core types for the clap-ts CLI framework.
+ * Matches clap's feature set with TypeScript type safety.
+ */
+/** Argument value type - matches clap's value_parser types. */
+export type ArgType = 'boolean' | 'string' | 'number' | 'enum' | 'positional';
+/** How an argument collects values. */
+export type ArgAction = 'set' | 'append' | 'count';
+/** Min/max constraint for number of values an argument accepts. */
+export interface NumArgs {
+    readonly min: number;
+    readonly max: number;
+}
+/** Custom value parser function. Receives raw string, returns parsed value or throws. */
+export type ValueParserFn = (value: string) => unknown;
+/** Full argument definition - matches clap::Arg. */
+export interface ArgDef {
+    /** Value type for this argument. */
+    readonly type: ArgType;
+    /** Human-readable description shown in help. */
+    readonly description?: string;
+    /** Short flag character (e.g., 'v' for -v). */
+    readonly short?: string;
+    /** Long flag name (e.g., 'verbose' for --verbose). Defaults to the arg key. */
+    readonly long?: string;
+    /** Additional aliases (hidden from help). Single-char treated as short, multi-char as long. */
+    readonly alias?: readonly string[];
+    /** Visible aliases shown in help output. Registered as working aliases at parse time. */
+    readonly visibleAlias?: readonly string[];
+    /** Default value when the argument is not provided. */
+    readonly default?: string | number | boolean | readonly string[];
+    /** Value to use when the flag is present but no value given (e.g., --port vs --port=8080). */
+    readonly defaultMissingValue?: string | number | boolean;
+    /**
+     * Conditional default: [otherArgName, otherArgValue, defaultValue].
+     * If the other arg equals the given value, this default is applied.
+     */
+    readonly defaultValueIf?: readonly [string, string, string | number | boolean];
+    /** Whether this argument is required. */
+    readonly required?: boolean;
+    /**
+     * Required unless the named arg(s) are present.
+     * Overrides `required: true` when the specified arg(s) are set.
+     */
+    readonly requiredUnlessPresent?: string | readonly string[];
+    /**
+     * Required if another arg equals a specific value: [argName, argValue].
+     * Makes this arg required when the condition is met.
+     */
+    readonly requiredIfEq?: readonly [string, string];
+    /** Cannot be used with ANY other argument. */
+    readonly exclusive?: boolean;
+    /** Global arg -- inherited by all subcommands. */
+    readonly global?: boolean;
+    /** Environment variable fallback (checked if arg not provided on CLI). */
+    readonly env?: string;
+    /** Display name for the value in help (e.g., "PATH", "PORT"). */
+    readonly valueName?: string;
+    /**
+     * Value validation/parsing. Either:
+     * - A string array of allowed values (enum-like restriction), or
+     * - A function that parses/validates the raw string value (throw to reject).
+     */
+    readonly valueParser?: readonly string[] | ValueParserFn;
+    /** Character to split values on (e.g., ',' for --tags=a,b,c). */
+    readonly valueDelimiter?: string;
+    /** Min/max number of values this arg accepts. */
+    readonly numArgs?: NumArgs;
+    /** Names of args that conflict with this one (mutually exclusive). */
+    readonly conflictsWith?: readonly string[];
+    /** Names of args that must also be present when this one is used. */
+    readonly requires?: readonly string[];
+    /** How values are collected: set (replace), append (collect into array), count. */
+    readonly action?: ArgAction;
+    /** Hide this argument from all help output. */
+    readonly hidden?: boolean;
+    /** Hide this argument from short help (-h) only. */
+    readonly hideShortHelp?: boolean;
+    /** Hide this argument from long help (--help) only. */
+    readonly hideLongHelp?: boolean;
+    /** Hide possible values list from help (when valueParser is string[]). */
+    readonly hidePossibleValues?: boolean;
+    /** Description for the --no-X variant of boolean flags. */
+    readonly negativeDescription?: string;
+    /** Accept values that start with a hyphen (e.g., --grep -pattern). */
+    readonly allowHyphenValues?: boolean;
+    /** Accept negative numbers as values (e.g., --offset -10). */
+    readonly allowNegativeNumbers?: boolean;
+    /** Mark as trailing var arg -- last positional consumes all remaining args. */
+    readonly trailingVarArg?: boolean;
+    /** Positional that requires -- before it (like clap's last()). */
+    readonly last?: boolean;
+    /** Custom section heading in help output (groups args under this heading). */
+    readonly helpHeading?: string;
+}
+/** Record of argument name to definition. */
+export type ArgsDef = Record<string, ArgDef>;
+/** Style function that applies formatting to a string. */
+export type StyleFn = (s: string) => string;
+/** Customizable style definitions for help and error output. */
+export interface StylesDef {
+    /** Bold text (used for error prefix). */
+    readonly bold: StyleFn;
+    /** Yellow text. */
+    readonly yellow: StyleFn;
+    /** Green text. */
+    readonly green: StyleFn;
+    /** Cyan text. */
+    readonly cyan: StyleFn;
+    /** Section headings (e.g., "Usage:", "Options:"). */
+    readonly heading: StyleFn;
+    /** Flag names (e.g., --verbose, -v). */
+    readonly flag: StyleFn;
+    /** Value placeholders (e.g., <PORT>, <ENV>). */
+    readonly value: StyleFn;
+    /** Command/subcommand names. */
+    readonly command: StyleFn;
+}
+/** Command metadata - matches clap::Command attributes. */
+export interface CommandMeta {
+    /** Command name (used in usage line). */
+    readonly name: string;
+    /** Version string (shown with --version). */
+    readonly version?: string;
+    /** Short description (one line, shown in parent's subcommand list). */
+    readonly description?: string;
+    /** Longer "about" text (shown at top of this command's help). */
+    readonly about?: string;
+    /** Extended help text (shown with --help, not -h). */
+    readonly longAbout?: string;
+    /** Text prepended before the help output. */
+    readonly beforeHelp?: string;
+    /** Text appended after the help output. */
+    readonly afterHelp?: string;
+    /** Hide this command from parent's help subcommand list. */
+    readonly hidden?: boolean;
+    /** Visible aliases shown next to the command name in help. */
+    readonly aliases?: readonly string[];
+    /** Require a subcommand to be provided. */
+    readonly subcommandRequired?: boolean;
+    /** Accept partial subcommand names (e.g., 'ser' matches 'serve'). */
+    readonly inferSubcommands?: boolean;
+    /** Accept partial long arg names (e.g., '--verb' matches '--verbose'). */
+    readonly inferLongArgs?: boolean;
+    /** Parent args and subcommands are mutually exclusive. */
+    readonly argsConflictsWithSubcommands?: boolean;
+    /** Accept subcommands not defined in subCommands. Passed to parent run handler. */
+    readonly allowExternalSubcommands?: boolean;
+    /** When a subcommand is present, parent's required args are waived. */
+    readonly subcommandNegatesReqs?: boolean;
+    /** Show help if no arguments are provided (instead of running). */
+    readonly argRequiredElseHelp?: boolean;
+    /**
+     * Custom help template with placeholders:
+     * {name}, {version}, {about}, {usage}, {all-args}, {arguments},
+     * {options}, {commands}, {before-help}, {after-help}
+     */
+    readonly helpTemplate?: string;
+}
+/** Argument group - for organizing related args (like clap's ArgGroup). */
+export interface ArgGroup {
+    /** Group name (for display). */
+    readonly name: string;
+    /** Arg names in this group. */
+    readonly args: readonly string[];
+    /** Whether the group is required (at least one must be set). */
+    readonly required?: boolean;
+    /** Whether args in the group are mutually exclusive. */
+    readonly multiple?: boolean;
+}
+/**
+ * Infer the parsed type from an ArgDef.
+ * - boolean -> boolean
+ * - number -> number
+ * - string/enum/positional -> string
+ * - action: 'append' -> string[]
+ * - action: 'count' -> number
+ */
+export type InferArgValue<A extends ArgDef> = A['action'] extends 'append' ? string[] : A['action'] extends 'count' ? number : A['type'] extends 'boolean' ? boolean : A['type'] extends 'number' ? number : string;
+/**
+ * Infer whether an arg is optional based on required/default.
+ * Args with `required: true` are always non-optional.
+ * Args with a default are always non-optional.
+ * All others may be undefined.
+ */
+export type InferArgOptional<A extends ArgDef, V> = A['required'] extends true ? V : A['default'] extends undefined ? V | undefined : V;
+/** Map an ArgsDef record to parsed argument types. */
+export type ParsedArgs<T extends ArgsDef> = {
+    [K in keyof T]: InferArgOptional<T[K], InferArgValue<T[K]>>;
+};
+/** Context passed to command hooks. */
+export interface CommandContext<T extends ArgsDef = ArgsDef> {
+    /** Raw argv that was parsed. */
+    readonly rawArgs: readonly string[];
+    /** Parsed and validated arguments. */
+    readonly args: ParsedArgs<T>;
+    /** The command definition being executed. */
+    readonly cmd: CommandDef<T>;
+    /** Name of the resolved subcommand, if any. */
+    readonly subCommand?: string;
+    /** Arbitrary user data (for passing state between setup/run/cleanup). */
+    data: Record<string, unknown>;
+}
+/** Full command definition - matches clap::Command. */
+export interface CommandDef<T extends ArgsDef = ArgsDef> {
+    /** Command metadata. */
+    readonly meta: CommandMeta;
+    /** Argument definitions. */
+    readonly args?: T;
+    /** Subcommand definitions (name -> command). */
+    readonly subCommands?: Record<string, CommandDef<any>>;
+    /** Argument groups for validation and help grouping. */
+    readonly groups?: readonly ArgGroup[];
+    /** Called before run. Return value is ignored; throw to abort. */
+    readonly setup?: (ctx: CommandContext<T>) => void | Promise<void>;
+    /** Main command handler. */
+    readonly run?: (ctx: CommandContext<T>) => void | Promise<void>;
+    /** Called after run (even on error). */
+    readonly cleanup?: (ctx: CommandContext<T>) => void | Promise<void>;
+}
+/** Options for runMain / runCommand. */
+export interface RunOptions {
+    /** Override argv (defaults to Bun.argv / process.argv). */
+    readonly argv?: readonly string[];
+    /** Exit process on error (default: true). */
+    readonly exit?: boolean;
+    /** Show help on empty args when command has subcommands (default: true). */
+    readonly showHelpOnEmpty?: boolean;
+    /** Custom styles for help and error output. */
+    readonly styles?: Partial<StylesDef>;
+}
+/** Result of parsing arguments. */
+export interface ParseResult {
+    /** Parsed argument values (key -> value). */
+    readonly args: Record<string, string | number | boolean | string[]>;
+    /** Positional arguments in order. */
+    readonly positionals: readonly string[];
+    /** Arguments after -- separator. */
+    readonly rest: readonly string[];
+    /** The subcommand name if one was matched. */
+    readonly subCommand?: string;
+    /** Whether --help / -h was requested. */
+    readonly helpRequested: boolean;
+    /** Whether -h (short) was used vs --help (long). */
+    readonly helpIsShort: boolean;
+    /** Whether --version / -V was requested. */
+    readonly versionRequested: boolean;
+    /** Unknown flags that were passed. */
+    readonly unknown: readonly string[];
+    /** Set of arg keys that were explicitly provided (not defaults or env). */
+    readonly explicitlySet: ReadonlySet<string>;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core types for the clap-ts CLI framework.
+ * Matches clap's feature set with TypeScript type safety.
+ */
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Argument validation - enforces constraints after parsing.
+ * Matches clap's validation: required, exclusive, conflicts, requires,
+ * valueParser, numArgs, requiredUnlessPresent, requiredIfEq, groups.
+ * Includes typo suggestion via Levenshtein distance.
+ */
+import type { CommandDef, ParseResult } from './types.js';
+/**
+ * Validate parsed results against the command definition.
+ * Throws CliParseError with clap-style error messages.
+ */
+export declare function validate(parseResult: ParseResult, command: CommandDef): void;