clap-ts 0.1.0 → 0.2.1

package/README.md

@@ -515,6 +515,62 @@ runMain(rootCommand, {
 });
 ```
 
+### Shell Completions
+
+Add Tab completion for bash, zsh, fish, and powershell with one line:
+
+```ts
+import { defineCommand, runMain, withCompletions } from 'clap-ts';
+
+const root = defineCommand({
+  meta: { name: 'my-cli', version: '1.0.0' },
+  args: { /* ... */ },
+  subCommands: { /* ... */ },
+});
+
+// Auto-adds a `completions` subcommand
+runMain(withCompletions(root));
+```
+
+Users then enable completions in their shell:
+
+```bash
+# bash - add to ~/.bashrc
+eval "$(my-cli completions bash)"
+
+# zsh - add to ~/.zshrc
+eval "$(my-cli completions zsh)"
+
+# fish - save to completions dir
+my-cli completions fish > ~/.config/fish/completions/my-cli.fish
+
+# powershell - add to $PROFILE
+my-cli completions powershell >> $PROFILE
+```
+
+Generated scripts support flags, subcommands, aliases, enum values, and value hints (file/dir completion):
+
+```ts
+const cmd = defineCommand({
+  meta: { name: 'tool' },
+  args: {
+    config: { type: 'string', valueHint: 'filePath' },   // Tab completes files
+    outDir: { type: 'string', valueHint: 'dirPath' },    // Tab completes directories
+    host: { type: 'string', valueHint: 'hostname' },     // Tab completes hostnames
+    env: { type: 'string', valueParser: ['dev', 'prod'] }, // Tab shows dev, prod
+  },
+});
+```
+
+You can also generate scripts manually without the subcommand:
+
+```ts
+import { generateCompletions } from 'clap-ts';
+
+const bashScript = generateCompletions(root, 'bash');
+const zshScript = generateCompletions(root, 'zsh', 'custom-binary-name');
+```
+
 ### runMain
 
 Entry point for CLI applications. Handles argv parsing, subcommand resolution, validation, help/version, and error display.
@@ -733,12 +789,11 @@ bun run bench/parse.bench.ts
 | hidePossibleValues | Yes | Yes |
 | Hidden args/commands | Yes | Yes |
 | Type-safe parsed args | derive macro | generics |
-| Shell completions | Yes | Not yet |
+| Shell completions (bash/zsh/fish/powershell) | Yes | Yes |
 | Man page generation | Yes | Not yet |
 
 ## Roadmap
 
-- Shell completion generation (bash/zsh/fish)
 - Man page generation
 - Markdown help output
 

package/dist/completions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shell completion generation -- static scripts and dynamic runtime completions.
+ * Matches clap_complete's feature set: bash, zsh, fish, powershell.
+ *
+ * Two modes:
+ * 1. Static: generateCompletions() returns a shell script string to source
+ * 2. Dynamic: completeEnv() checks env vars, outputs completions, returns true if handled
+ */
+import type { CommandDef, Shell } from './types.js';
+/**
+ * Generate a shell completion script for the given command and shell.
+ *
+ * Usage:
+ * ```ts
+ * const script = generateCompletions(rootCommand, 'bash', 'my-cli');
+ * fs.writeFileSync('completions.bash', script);
+ * ```
+ *
+ * Users source the generated script in their shell config:
+ * - bash: `source completions.bash` or copy to `~/.local/share/bash-completion/completions/`
+ * - zsh: copy to a directory in `$fpath` (e.g., `~/.zsh/completions/`)
+ * - fish: copy to `~/.config/fish/completions/`
+ * - powershell: add to `$PROFILE`
+ */
+export declare function generateCompletions(command: CommandDef, shell: Shell, binaryName?: string): string;
+/**
+ * Return a new command with a `completions` subcommand auto-injected.
+ * The subcommand generates shell completion scripts when invoked.
+ *
+ * ```ts
+ * const root = defineCommand({ ... });
+ * runMain(withCompletions(root));
+ * ```
+ *
+ * Then users run:
+ * ```bash
+ * eval "$(my-cli completions bash)"
+ * ```
+ */
+export declare function withCompletions(rootCommand: CommandDef<any>): CommandDef<any>;

package/dist/completions.js

@@ -0,0 +1,523 @@
+/**
+ * Shell completion generation -- static scripts and dynamic runtime completions.
+ * Matches clap_complete's feature set: bash, zsh, fish, powershell.
+ *
+ * Two modes:
+ * 1. Static: generateCompletions() returns a shell script string to source
+ * 2. Dynamic: completeEnv() checks env vars, outputs completions, returns true if handled
+ */
+/** Extract completion-relevant data from a CommandDef tree. */
+function buildCompletionTree(command, name) {
+    const flags = [];
+    const argsDef = command.args ?? {};
+    for (const [key, def] of Object.entries(argsDef)) {
+        if (def.type === 'positional') {
+            continue;
+        }
+        const longName = def.long ?? key;
+        flags.push({
+            key,
+            short: def.short,
+            long: longName,
+            description: def.description ?? '',
+            takesValue: def.type !== 'boolean' && def.action !== 'count',
+            possibleValues: Array.isArray(def.valueParser) ? def.valueParser : [],
+            valueHint: def.valueHint,
+            hidden: def.hidden ?? false,
+        });
+    }
+    // Always include --help and --version
+    flags.push({ key: 'help', short: 'h', long: 'help', description: 'Print help', takesValue: false, possibleValues: [], hidden: false });
+    if (command.meta.version) {
+        flags.push({ key: 'version', short: 'V', long: 'version', description: 'Print version', takesValue: false, possibleValues: [], hidden: false });
+    }
+    const subcommands = [];
+    const childNodes = new Map();
+    if (command.subCommands) {
+        for (const [subName, subDef] of Object.entries(command.subCommands)) {
+            subcommands.push({
+                name: subName,
+                description: subDef.meta.description ?? '',
+                aliases: subDef.meta.aliases ?? [],
+                hidden: subDef.meta.hidden ?? false,
+            });
+            childNodes.set(subName, buildCompletionTree(subDef, subName));
+        }
+    }
+    return {
+        name: name ?? command.meta.name,
+        flags,
+        subcommands,
+        childNodes,
+    };
+}
+// ---- Helpers ----
+/** Escape single quotes for shell strings. */
+function esc(s) {
+    return s.replaceAll("'", "'\\''");
+}
+/** Escape double quotes for shell strings. */
+function escDq(s) {
+    return s.replaceAll('"', '\\"').replaceAll('$', '\\$').replaceAll('`', '\\`');
+}
+/** Sanitize a name for use as a shell function/variable name. */
+function sanitize(s) {
+    return s.replaceAll(/[^a-zA-Z0-9_]/g, '_');
+}
+// ---- Bash Generator ----
+function generateBash(root, binaryName) {
+    const funcName = `_${sanitize(binaryName)}`;
+    const lines = [];
+    lines.push(`# bash completion for ${binaryName}`);
+    lines.push(`# Generated by clap-ts`);
+    lines.push('');
+    // Generate completion function for each command level
+    generateBashFunction(root, funcName, binaryName, lines);
+    lines.push('');
+    lines.push(`complete -o default -o bashdefault -F ${funcName} ${binaryName}`);
+    lines.push('');
+    return lines.join('\n');
+}
+function generateBashFunction(node, funcName, fullCommand, lines) {
+    lines.push(`${funcName}() {`);
+    lines.push('    local cur prev words cword');
+    lines.push('    _init_completion || return');
+    lines.push('');
+    // Build flag list
+    const visibleFlags = node.flags.filter((f) => !f.hidden);
+    const flagWords = [];
+    for (const f of visibleFlags) {
+        flagWords.push(`--${f.long}`);
+        if (f.short) {
+            flagWords.push(`-${f.short}`);
+        }
+    }
+    // Build subcommand list
+    const visibleSubs = node.subcommands.filter((s) => !s.hidden);
+    const subWords = visibleSubs.map((s) => s.name);
+    // Handle value completion for flags that take values
+    const valueFlagCases = [];
+    for (const f of visibleFlags) {
+        if (!f.takesValue)
+            continue;
+        const flagNames = [`--${f.long}`];
+        if (f.short)
+            flagNames.push(`-${f.short}`);
+        const pattern = flagNames.join('|');
+        if (f.possibleValues.length > 0) {
+            valueFlagCases.push(`        ${pattern})`);
+            valueFlagCases.push(`            COMPREPLY=( $(compgen -W '${f.possibleValues.join(' ')}' -- "$cur") )`);
+            valueFlagCases.push('            return ;;');
+        }
+        else if (f.valueHint) {
+            const compgen = bashValueHintCompgen(f.valueHint);
+            if (compgen) {
+                valueFlagCases.push(`        ${pattern})`);
+                valueFlagCases.push(`            ${compgen}`);
+                valueFlagCases.push('            return ;;');
+            }
+        }
+    }
+    if (valueFlagCases.length > 0) {
+        lines.push('    case "$prev" in');
+        lines.push(...valueFlagCases);
+        lines.push('    esac');
+        lines.push('');
+    }
+    // Handle subcommand dispatch
+    if (visibleSubs.length > 0) {
+        lines.push('    # Check for subcommand');
+        lines.push('    local subcmd=""');
+        lines.push('    for ((i=1; i < cword; i++)); do');
+        lines.push('        case "${words[i]}" in');
+        for (const sub of visibleSubs) {
+            const allNames = [sub.name, ...sub.aliases];
+            lines.push(`            ${allNames.join('|')})`);
+            lines.push(`                subcmd="${sub.name}"; break ;;`);
+        }
+        lines.push('        esac');
+        lines.push('    done');
+        lines.push('');
+        // Dispatch to child function
+        lines.push('    case "$subcmd" in');
+        for (const sub of visibleSubs) {
+            const childFunc = `${funcName}_${sanitize(sub.name)}`;
+            lines.push(`        ${sub.name})`);
+            lines.push(`            ${childFunc}; return ;;`);
+        }
+        lines.push('    esac');
+        lines.push('');
+    }
+    // Default: complete with flags and subcommands
+    const allWords = [...flagWords, ...subWords].join(' ');
+    lines.push(`    COMPREPLY=( $(compgen -W '${allWords}' -- "$cur") )`);
+    lines.push('}');
+    lines.push('');
+    // Recurse for child commands
+    for (const sub of visibleSubs) {
+        const childNode = node.childNodes.get(sub.name);
+        if (childNode) {
+            const childFunc = `${funcName}_${sanitize(sub.name)}`;
+            generateBashFunction(childNode, childFunc, `${fullCommand} ${sub.name}`, lines);
+        }
+    }
+}
+function bashValueHintCompgen(hint) {
+    switch (hint) {
+        case 'filePath': return 'COMPREPLY=( $(compgen -f -- "$cur") )';
+        case 'dirPath': return 'COMPREPLY=( $(compgen -d -- "$cur") )';
+        case 'anyPath': return 'COMPREPLY=( $(compgen -f -- "$cur") )';
+        case 'executablePath': return 'COMPREPLY=( $(compgen -c -- "$cur") )';
+        case 'commandName': return 'COMPREPLY=( $(compgen -c -- "$cur") )';
+        case 'hostname': return 'COMPREPLY=( $(compgen -A hostname -- "$cur") )';
+        case 'username': return 'COMPREPLY=( $(compgen -u -- "$cur") )';
+        case 'url': return undefined;
+        case 'emailAddress': return undefined;
+    }
+}
+// ---- Zsh Generator ----
+function generateZsh(root, binaryName) {
+    const funcName = `_${sanitize(binaryName)}`;
+    const lines = [];
+    lines.push(`#compdef ${binaryName}`);
+    lines.push('');
+    lines.push(`# zsh completion for ${binaryName}`);
+    lines.push('# Generated by clap-ts');
+    lines.push('');
+    generateZshFunction(root, funcName, lines);
+    lines.push('');
+    lines.push(`if [ "$funcstack[1]" = "${funcName}" ]; then`);
+    lines.push(`    ${funcName} "$@"`);
+    lines.push('else');
+    lines.push(`    compdef ${funcName} ${binaryName}`);
+    lines.push('fi');
+    lines.push('');
+    return lines.join('\n');
+}
+function generateZshFunction(node, funcName, lines) {
+    lines.push(`${funcName}() {`);
+    lines.push('    local -a args');
+    lines.push('');
+    const visibleFlags = node.flags.filter((f) => !f.hidden);
+    const visibleSubs = node.subcommands.filter((s) => !s.hidden);
+    // Build _arguments specs for flags
+    const argSpecs = [];
+    for (const f of visibleFlags) {
+        const desc = escDq(f.description);
+        if (f.takesValue) {
+            const valueSpec = zshValueSpec(f);
+            if (f.short) {
+                argSpecs.push(`'(-${f.short} --${f.long})-${f.short}[${desc}]${valueSpec}'`);
+                argSpecs.push(`'(-${f.short} --${f.long})--${f.long}[${desc}]${valueSpec}'`);
+            }
+            else {
+                argSpecs.push(`'--${f.long}[${desc}]${valueSpec}'`);
+            }
+        }
+        else {
+            if (f.short) {
+                argSpecs.push(`'(-${f.short} --${f.long})-${f.short}[${desc}]'`);
+                argSpecs.push(`'(-${f.short} --${f.long})--${f.long}[${desc}]'`);
+            }
+            else {
+                argSpecs.push(`'--${f.long}[${desc}]'`);
+            }
+        }
+    }
+    if (visibleSubs.length > 0) {
+        argSpecs.push("'1: :->command'");
+        argSpecs.push("'*::arg:->args'");
+    }
+    if (argSpecs.length > 0) {
+        lines.push('    _arguments -C \\');
+        for (let i = 0; i < argSpecs.length; i++) {
+            const sep = i < argSpecs.length - 1 ? ' \\' : '';
+            lines.push(`        ${argSpecs[i]}${sep}`);
+        }
+        lines.push('');
+    }
+    if (visibleSubs.length > 0) {
+        lines.push('    case "$state" in');
+        lines.push('        command)');
+        const subDescs = visibleSubs.map((s) => `'${s.name}:${escDq(s.description)}'`);
+        lines.push(`            _values 'command' ${subDescs.join(' ')}`);
+        lines.push('            ;;');
+        lines.push('        args)');
+        lines.push('            case "$words[1]" in');
+        for (const sub of visibleSubs) {
+            const childFunc = `${funcName}_${sanitize(sub.name)}`;
+            const allNames = [sub.name, ...sub.aliases];
+            lines.push(`                ${allNames.join('|')})`);
+            lines.push(`                    ${childFunc} ;;`);
+        }
+        lines.push('            esac');
+        lines.push('            ;;');
+        lines.push('    esac');
+    }
+    lines.push('}');
+    lines.push('');
+    // Recurse for child commands
+    for (const sub of visibleSubs) {
+        const childNode = node.childNodes.get(sub.name);
+        if (childNode) {
+            const childFunc = `${funcName}_${sanitize(sub.name)}`;
+            generateZshFunction(childNode, childFunc, lines);
+        }
+    }
+}
+function zshValueSpec(f) {
+    if (f.possibleValues.length > 0) {
+        const vals = f.possibleValues.join(' ');
+        return `:${f.key}:(${vals})`;
+    }
+    if (f.valueHint) {
+        return zshValueHintSpec(f.valueHint, f.key);
+    }
+    return `:${f.key}:`;
+}
+function zshValueHintSpec(hint, key) {
+    switch (hint) {
+        case 'filePath': return `:${key}:_files`;
+        case 'dirPath': return `:${key}:_directories`;
+        case 'anyPath': return `:${key}:_files`;
+        case 'executablePath': return `:${key}:_command_names`;
+        case 'commandName': return `:${key}:_command_names`;
+        case 'hostname': return `:${key}:_hosts`;
+        case 'username': return `:${key}:_users`;
+        case 'url': return `:${key}:_urls`;
+        case 'emailAddress': return `:${key}:`;
+    }
+}
+// ---- Fish Generator ----
+function generateFish(root, binaryName) {
+    const lines = [];
+    lines.push(`# fish completion for ${binaryName}`);
+    lines.push('# Generated by clap-ts');
+    lines.push('');
+    generateFishCommands(root, binaryName, [], lines);
+    return lines.join('\n');
+}
+function generateFishCommands(node, binaryName, parentSubcommands, lines) {
+    const visibleFlags = node.flags.filter((f) => !f.hidden);
+    const visibleSubs = node.subcommands.filter((s) => !s.hidden);
+    // Build condition: only show these completions when we're at this command level
+    let condition;
+    if (parentSubcommands.length === 0) {
+        if (visibleSubs.length > 0) {
+            // Root level with subcommands: show only when no subcommand has been seen
+            const allSubNames = collectAllSubcommandNames(node);
+            condition = `not __fish_seen_subcommand_from ${allSubNames.join(' ')}`;
+        }
+        else {
+            condition = '';
+        }
+    }
+    else {
+        const lastSub = parentSubcommands[parentSubcommands.length - 1];
+        condition = `__fish_seen_subcommand_from ${lastSub}`;
+    }
+    const condFlag = condition ? `-n '${condition}'` : '';
+    // Register flags
+    for (const f of visibleFlags) {
+        const parts = [`complete -c ${binaryName}`];
+        if (condFlag)
+            parts.push(condFlag);
+        if (f.short)
+            parts.push(`-s ${f.short}`);
+        parts.push(`-l ${f.long}`);
+        if (f.description)
+            parts.push(`-d '${esc(f.description)}'`);
+        if (f.takesValue) {
+            parts.push('-r'); // requires argument
+            if (f.possibleValues.length > 0) {
+                parts.push(`-a '${f.possibleValues.join(' ')}'`);
+            }
+            else if (f.valueHint) {
+                const fishHint = fishValueHint(f.valueHint);
+                if (fishHint)
+                    parts.push(fishHint);
+            }
+        }
+        lines.push(parts.join(' '));
+    }
+    // Register subcommands
+    for (const sub of visibleSubs) {
+        const parts = [`complete -c ${binaryName}`];
+        if (condFlag)
+            parts.push(condFlag);
+        parts.push(`-a '${sub.name}'`);
+        if (sub.description)
+            parts.push(`-d '${esc(sub.description)}'`);
+        lines.push(parts.join(' '));
+        // Also register aliases
+        for (const alias of sub.aliases) {
+            const aliasParts = [`complete -c ${binaryName}`];
+            if (condFlag)
+                aliasParts.push(condFlag);
+            aliasParts.push(`-a '${alias}'`);
+            if (sub.description)
+                aliasParts.push(`-d '${esc(sub.description)}'`);
+            lines.push(aliasParts.join(' '));
+        }
+    }
+    lines.push('');
+    // Recurse for child commands
+    for (const sub of visibleSubs) {
+        const childNode = node.childNodes.get(sub.name);
+        if (childNode) {
+            generateFishCommands(childNode, binaryName, [...parentSubcommands, sub.name], lines);
+        }
+    }
+}
+function collectAllSubcommandNames(node) {
+    const names = [];
+    for (const sub of node.subcommands) {
+        if (!sub.hidden) {
+            names.push(sub.name);
+            names.push(...sub.aliases);
+        }
+    }
+    return names;
+}
+function fishValueHint(hint) {
+    switch (hint) {
+        case 'filePath': return '-F';
+        case 'dirPath': return "-xa '(__fish_complete_directories)'";
+        case 'anyPath': return '-F';
+        case 'executablePath': return "-a '(__fish_complete_command)'";
+        case 'commandName': return "-a '(__fish_complete_command)'";
+        case 'hostname': return "-a '(__fish_print_hostnames)'";
+        case 'username': return "-a '(__fish_complete_users)'";
+        case 'url': return undefined;
+        case 'emailAddress': return undefined;
+    }
+}
+// ---- PowerShell Generator ----
+function generatePowerShell(root, binaryName) {
+    const lines = [];
+    lines.push(`# PowerShell completion for ${binaryName}`);
+    lines.push('# Generated by clap-ts');
+    lines.push('');
+    lines.push(`Register-ArgumentCompleter -CommandName '${binaryName}' -ScriptBlock {`);
+    lines.push('    param($wordToComplete, $commandAst, $cursorPosition)');
+    lines.push('');
+    lines.push('    $tokens = $commandAst.CommandElements | ForEach-Object { $_.ToString() }');
+    lines.push('    $tokens = $tokens[1..($tokens.Length - 1)]  # Remove command name');
+    lines.push('');
+    generatePowerShellNode(root, '    ', '$tokens', 0, lines);
+    lines.push('}');
+    lines.push('');
+    return lines.join('\n');
+}
+function generatePowerShellNode(node, indent, tokensVar, depth, lines) {
+    const visibleFlags = node.flags.filter((f) => !f.hidden);
+    const visibleSubs = node.subcommands.filter((s) => !s.hidden);
+    // Check if we need to dispatch to a subcommand
+    if (visibleSubs.length > 0) {
+        lines.push(`${indent}# Check for subcommand at position ${depth}`);
+        lines.push(`${indent}if (${tokensVar}.Length -gt ${depth}) {`);
+        lines.push(`${indent}    switch (${tokensVar}[${depth}]) {`);
+        for (const sub of visibleSubs) {
+            const allNames = [sub.name, ...sub.aliases].map((n) => `'${n}'`).join(', ');
+            lines.push(`${indent}        {$_ -in ${allNames}} {`);
+            const childNode = node.childNodes.get(sub.name);
+            if (childNode) {
+                generatePowerShellNode(childNode, indent + '            ', tokensVar, depth + 1, lines);
+            }
+            lines.push(`${indent}            return`);
+            lines.push(`${indent}        }`);
+        }
+        lines.push(`${indent}    }`);
+        lines.push(`${indent}}`);
+        lines.push('');
+    }
+    // Complete flags and subcommands at this level
+    const completions = [];
+    for (const f of visibleFlags) {
+        const desc = escDq(f.description);
+        completions.push(`${indent}[System.Management.Automation.CompletionResult]::new('--${f.long}', '--${f.long}', 'ParameterName', '${escDq(f.description)}')`);
+        if (f.short) {
+            completions.push(`${indent}[System.Management.Automation.CompletionResult]::new('-${f.short}', '-${f.short}', 'ParameterName', '${escDq(f.description)}')`);
+        }
+    }
+    for (const sub of visibleSubs) {
+        completions.push(`${indent}[System.Management.Automation.CompletionResult]::new('${sub.name}', '${sub.name}', 'Command', '${escDq(sub.description)}')`);
+    }
+    for (const c of completions) {
+        lines.push(c);
+    }
+}
+// ---- Public API: Static Generation ----
+/**
+ * Generate a shell completion script for the given command and shell.
+ *
+ * Usage:
+ * ```ts
+ * const script = generateCompletions(rootCommand, 'bash', 'my-cli');
+ * fs.writeFileSync('completions.bash', script);
+ * ```
+ *
+ * Users source the generated script in their shell config:
+ * - bash: `source completions.bash` or copy to `~/.local/share/bash-completion/completions/`
+ * - zsh: copy to a directory in `$fpath` (e.g., `~/.zsh/completions/`)
+ * - fish: copy to `~/.config/fish/completions/`
+ * - powershell: add to `$PROFILE`
+ */
+export function generateCompletions(command, shell, binaryName) {
+    const name = binaryName ?? command.meta.name;
+    const root = buildCompletionTree(command, name);
+    switch (shell) {
+        case 'bash': return generateBash(root, name);
+        case 'zsh': return generateZsh(root, name);
+        case 'fish': return generateFish(root, name);
+        case 'powershell': return generatePowerShell(root, name);
+    }
+}
+// ---- Public API: Auto-inject completions subcommand ----
+const VALID_SHELLS = ['bash', 'zsh', 'fish', 'powershell'];
+/**
+ * Return a new command with a `completions` subcommand auto-injected.
+ * The subcommand generates shell completion scripts when invoked.
+ *
+ * ```ts
+ * const root = defineCommand({ ... });
+ * runMain(withCompletions(root));
+ * ```
+ *
+ * Then users run:
+ * ```bash
+ * eval "$(my-cli completions bash)"
+ * ```
+ */
+export function withCompletions(rootCommand) {
+    const completionsCmd = {
+        meta: {
+            name: 'completions',
+            description: 'Generate shell completion script',
+            aliases: ['completion'],
+        },
+        args: {
+            shell: {
+                type: 'positional',
+                valueName: 'SHELL',
+                required: true,
+                description: 'Target shell: bash, zsh, fish, or powershell',
+            },
+        },
+        run({ args }) {
+            const shell = String(args['shell']);
+            if (!VALID_SHELLS.includes(shell)) {
+                process.stderr.write(`error: invalid shell '${shell}'. Valid options: ${VALID_SHELLS.join(', ')}\n`);
+                process.exit(2);
+            }
+            process.stdout.write(generateCompletions(rootCommand, shell));
+        },
+    };
+    return {
+        ...rootCommand,
+        subCommands: {
+            ...rootCommand.subCommands,
+            completions: completionsCmd,
+        },
+    };
+}

package/dist/index.d.ts

@@ -3,8 +3,9 @@
  *
  * 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 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 { 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

@@ -11,3 +11,5 @@ export { validate } from './validation.js';
 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';

package/dist/types.d.ts

@@ -13,6 +13,10 @@ export interface NumArgs {
 }
 /** Custom value parser function. Receives raw string, returns parsed value or throws. */
 export type ValueParserFn = (value: string) => unknown;
+/** Hint for shell completion behavior -- guides what kind of values to complete. */
+export type ValueHint = 'filePath' | 'dirPath' | 'anyPath' | 'executablePath' | 'commandName' | 'hostname' | 'username' | 'url' | 'emailAddress';
+/** Supported shells for completion script generation. */
+export type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
 /** Full argument definition - matches clap::Arg. */
 export interface ArgDef {
     /** Value type for this argument. */
@@ -92,6 +96,8 @@ export interface ArgDef {
     readonly last?: boolean;
     /** Custom section heading in help output (groups args under this heading). */
     readonly helpHeading?: string;
+    /** Hint for shell completion -- guides what kind of values to suggest (files, dirs, hosts, etc.). */
+    readonly valueHint?: ValueHint;
 }
 /** Record of argument name to definition. */
 export type ArgsDef = Record<string, ArgDef>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clap-ts",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A type-safe CLI argument parser for TypeScript, inspired by Rust's clap crate. Full clap-style parsing, validation, help generation, and subcommand support with zero dependencies.",
   "type": "module",
   "main": "dist/index.js",