clap-ts 0.3.0 → 0.4.0

package/src/completions.ts

@@ -0,0 +1,865 @@
+/**
+ * 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, ValueHint } from './types.js';
+import { possibleValues, subCommandsOf } from './parser.js';
+
+export type { Shell, ValueHint } from './types.js';
+
+// ---- Internal: Command Tree Traversal ----
+
+interface FlagInfo {
+  key: string;
+  short?: string;
+  long: string;
+  description: string;
+  takesValue: boolean;
+  possibleValues: readonly string[];
+  valueHint?: ValueHint;
+  hidden: boolean;
+}
+
+interface PositionalInfo {
+  key: string;
+  name: string;
+  description: string;
+  required: boolean;
+  possibleValues: readonly string[];
+  valueHint?: ValueHint;
+  hidden: boolean;
+}
+
+interface SubcommandInfo {
+  name: string;
+  description: string;
+  aliases: readonly string[];
+  hidden: boolean;
+}
+
+interface CompletionNode {
+  name: string;
+  description: string;
+  flags: FlagInfo[];
+  positionals: PositionalInfo[];
+  subcommands: SubcommandInfo[];
+  childNodes: Map<string, CompletionNode>;
+}
+
+/** Extract completion-relevant data from a CommandDef tree. */
+function buildCompletionTree(command: CommandDef, name?: string): CompletionNode {
+  const flags: FlagInfo[] = [];
+  const positionals: PositionalInfo[] = [];
+  const argsDef = command.args ?? {};
+
+  for (const [key, def] of Object.entries(argsDef)) {
+    if (def.type === 'positional') {
+      positionals.push({
+        key,
+        name: def.valueName ?? key,
+        description: def.description ?? '',
+        required: def.required ?? false,
+        possibleValues: possibleValues(def)
+          .filter((v) => !v.hidden)
+          .map((v) => v.name),
+        valueHint: def.valueHint,
+        hidden: def.hidden ?? false,
+      });
+      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: possibleValues(def)
+        .filter((v) => !v.hidden)
+        .map((v) => v.name),
+      valueHint: def.valueHint,
+      hidden: def.hidden ?? false,
+    });
+  }
+
+  // Always include --help and --version
+  if (command.meta.disableHelpFlag !== true) {
+    flags.push({ key: 'help', short: 'h', long: 'help', description: 'Print help', takesValue: false, possibleValues: [], hidden: false });
+  }
+  if (command.meta.version && command.meta.disableVersionFlag !== true) {
+    flags.push({ key: 'version', short: 'V', long: 'version', description: 'Print version', takesValue: false, possibleValues: [], hidden: false });
+  }
+
+  const subcommands: SubcommandInfo[] = [];
+  const childNodes = new Map<string, CompletionNode>();
+
+  {
+    for (const [subName, subDef] of Object.entries(subCommandsOf(command))) {
+      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,
+    description: command.meta.description ?? command.meta.about ?? '',
+    flags,
+    positionals,
+    subcommands,
+    childNodes,
+  };
+}
+
+// ---- Helpers ----
+
+/** Escape single quotes for shell strings. */
+function esc(s: string): string {
+  return s.replaceAll("'", "'\\''");
+}
+
+/** Escape double quotes for shell strings. */
+function escDq(s: string): string {
+  return s.replaceAll('"', '\\"').replaceAll('$', '\\$').replaceAll('`', '\\`');
+}
+
+/** Sanitize a name for use as a shell function/variable name. */
+function sanitize(s: string): string {
+  return s.replaceAll(/[^a-zA-Z0-9_]/g, '_');
+}
+
+// ---- Bash Generator ----
+
+function generateBash(root: CompletionNode, binaryName: string): string {
+  const funcName = `_${sanitize(binaryName)}`;
+  const lines: string[] = [];
+
+  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: CompletionNode,
+  funcName: string,
+  fullCommand: string,
+  lines: string[],
+): void {
+  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: string[] = [];
+  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: string[] = [];
+  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: ValueHint): string | undefined {
+  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: CompletionNode, binaryName: string): string {
+  const funcName = `_${sanitize(binaryName)}`;
+  const lines: string[] = [];
+
+  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: CompletionNode,
+  funcName: string,
+  lines: string[],
+): void {
+  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: string[] = [];
+  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: FlagInfo): string {
+  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: ValueHint, key: string): string {
+  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 'commandString': return `:${key}:_cmdstring`;
+    case 'commandWithArguments': return `:${key}:_command_names -e`;
+    case 'emailAddress':
+    case 'other':
+    case 'unknown':
+      return `:${key}:`;
+  }
+}
+
+// ---- Fish Generator ----
+
+function generateFish(root: CompletionNode, binaryName: string): string {
+  const lines: string[] = [];
+
+  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: CompletionNode,
+  binaryName: string,
+  parentSubcommands: string[],
+  lines: string[],
+): void {
+  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: string;
+  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: CompletionNode): string[] {
+  const names: string[] = [];
+  for (const sub of node.subcommands) {
+    if (!sub.hidden) {
+      names.push(sub.name);
+      names.push(...sub.aliases);
+    }
+  }
+  return names;
+}
+
+function fishValueHint(hint: ValueHint): string | undefined {
+  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: CompletionNode, binaryName: string): string {
+  const lines: string[] = [];
+
+  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: CompletionNode,
+  indent: string,
+  tokensVar: string,
+  depth: number,
+  lines: string[],
+): void {
+  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: string[] = [];
+  for (const f of visibleFlags) {
+    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);
+  }
+}
+
+
+// ---- Elvish Generator ----
+
+/**
+ * Elvish completions are a map from command path (segments joined by ';') to a
+ * lambda emitting candidates, which is how clap_complete shapes them: the
+ * completer walks the words it has seen to build the key, then calls it.
+ */
+function generateElvish(root: CompletionNode, binaryName: string): string {
+  const cases: string[] = [];
+  collectElvishCases(root, [binaryName], cases);
+
+  return [
+    `# elvish completion for ${binaryName}`,
+    '# Generated by clap-ts',
+    '',
+    'use builtin;',
+    'use str;',
+    '',
+    `set edit:completion:arg-completer[${binaryName}] = {|@words|`,
+    '    fn spaces {|n|',
+    "        builtin:repeat $n ' ' | str:join ''",
+    '    }',
+    '    fn cand {|text desc|',
+    "        edit:complex-candidate $text &display=$text' '(spaces (- 14 (wcswidth $text)))$desc",
+    '    }',
+    `    var command = '${esc(binaryName)}'`,
+    '    for word $words[1..-1] {',
+    "        if (str:has-prefix $word '-') {",
+    '            break',
+    '        }',
+    "        set command = $command';'$word",
+    '    }',
+    '    var completions = [',
+    ...cases,
+    '    ]',
+    '    if (has-key $completions $command) {',
+    '        $completions[$command]',
+    '    }',
+    '}',
+    '',
+  ].join('\n');
+}
+
+function collectElvishCases(
+  node: CompletionNode,
+  path: readonly string[],
+  cases: string[],
+): void {
+  const key = path.join(';');
+  cases.push(`        &'${esc(key)}'= {`);
+
+  for (const f of node.flags) {
+    if (f.hidden) {
+      continue;
+    }
+    const desc = esc(f.description.replaceAll('\n', ' '));
+    if (f.short) {
+      cases.push(`            cand -${f.short} '${desc}'`);
+    }
+    cases.push(`            cand --${f.long} '${desc}'`);
+  }
+  for (const sub of node.subcommands) {
+    if (sub.hidden) {
+      continue;
+    }
+    const desc = esc(sub.description.replaceAll('\n', ' '));
+    for (const name of [sub.name, ...sub.aliases]) {
+      cases.push(`            cand ${name} '${desc}'`);
+    }
+  }
+
+  cases.push('        }');
+
+  for (const sub of node.subcommands) {
+    const child = node.childNodes.get(sub.name);
+    if (child) {
+      collectElvishCases(child, [...path, sub.name], cases);
+    }
+  }
+}
+
+// ---- Nushell Generator ----
+
+/**
+ * Nushell completes through `extern` declarations, one per command path, with
+ * a `nu-complete` helper per argument that restricts its values.
+ */
+function generateNushell(root: CompletionNode, binaryName: string): string {
+  const lines: string[] = [];
+
+  lines.push(`# nushell completion for ${binaryName}`);
+  lines.push('# Generated by clap-ts');
+  lines.push('');
+  lines.push('module completions {');
+  lines.push('');
+
+  collectNushellCommand(root, [binaryName], lines);
+
+  lines.push('}');
+  lines.push('');
+  lines.push('export use completions *');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/** Nushell type annotation for a value, from its hint. */
+function nushellType(hint: ValueHint | undefined): string {
+  switch (hint) {
+    case 'filePath':
+    case 'anyPath':
+    case 'executablePath':
+      return 'path';
+    case 'dirPath':
+      return 'directory';
+    default:
+      return 'string';
+  }
+}
+
+function collectNushellCommand(
+  node: CompletionNode,
+  path: readonly string[],
+  lines: string[],
+): void {
+  const commandPath = path.join(' ');
+  const visibleFlags = node.flags.filter((f) => !f.hidden);
+  const visiblePositionals = node.positionals.filter((a) => !a.hidden);
+
+  // Value completers first: nushell resolves them by name within the module.
+  for (const arg of [...visibleFlags, ...visiblePositionals]) {
+    if (arg.possibleValues.length === 0) {
+      continue;
+    }
+    lines.push(`  def "nu-complete ${commandPath} ${arg.key}" [] {`);
+    lines.push(`    [ ${arg.possibleValues.map((v) => `"${escDq(v)}"`).join(' ')} ]`);
+    lines.push('  }');
+    lines.push('');
+  }
+
+  if (node.description) {
+    lines.push(`  # ${node.description.replaceAll('\n', ' ')}`);
+  }
+  lines.push(`  export extern "${commandPath}" [`);
+
+  for (const f of visibleFlags) {
+    const short = f.short ? `(-${f.short})` : '';
+    let value = '';
+    if (f.takesValue) {
+      value =
+        f.possibleValues.length > 0
+          ? `: string@"nu-complete ${commandPath} ${f.key}"`
+          : `: ${nushellType(f.valueHint)}`;
+    }
+    const comment = f.description ? ` # ${f.description.replaceAll('\n', ' ')}` : '';
+    lines.push(`    --${f.long}${short}${value}${comment}`);
+  }
+
+  for (const arg of visiblePositionals) {
+    const optional = arg.required ? '' : '?';
+    const type =
+      arg.possibleValues.length > 0
+        ? `string@"nu-complete ${commandPath} ${arg.key}"`
+        : nushellType(arg.valueHint);
+    const comment = arg.description ? ` # ${arg.description.replaceAll('\n', ' ')}` : '';
+    lines.push(`    ${arg.name}${optional}: ${type}${comment}`);
+  }
+
+  lines.push('  ]');
+  lines.push('');
+
+  for (const sub of node.subcommands) {
+    if (sub.hidden) {
+      continue;
+    }
+    const child = node.childNodes.get(sub.name);
+    if (child) {
+      collectNushellCommand(child, [...path, sub.name], lines);
+    }
+  }
+}
+
+// ---- 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`
+ * - elvish: source from `~/.config/elvish/rc.elv`
+ * - nushell: save and `source` it from `$nu.config-path`
+ */
+export function generateCompletions(
+  command: CommandDef,
+  shell: Shell,
+  binaryName?: string,
+): string {
+  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);
+    case 'elvish': return generateElvish(root, name);
+    case 'nushell': return generateNushell(root, name);
+  }
+}
+
+// ---- Public API: Auto-inject completions subcommand ----
+
+const VALID_SHELLS: readonly Shell[] = [
+  'bash',
+  'zsh',
+  'fish',
+  'powershell',
+  'elvish',
+  'nushell',
+];
+
+/**
+ * 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: CommandDef<any>): CommandDef<any> {
+  const completionsCmd: CommandDef = {
+    meta: {
+      name: 'completions',
+      description: 'Generate shell completion script',
+      aliases: ['completion'],
+    },
+    args: {
+      shell: {
+        type: 'positional' as const,
+        valueName: 'SHELL',
+        required: true,
+        description: `Target shell: ${VALID_SHELLS.join(', ')}`,
+        valueParser: [...VALID_SHELLS],
+      },
+    },
+    run({ args, stdout }) {
+      stdout.write(generateCompletions(rootCommand, String(args['shell']) as Shell));
+    },
+  };
+
+  return {
+    ...rootCommand,
+    subCommands: {
+      ...rootCommand.subCommands,
+      completions: completionsCmd,
+    },
+    lazySubCommands: rootCommand.lazySubCommands,
+  };
+}
+