clap-ts 0.2.0 → 0.3.0

package/dist/argfile.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Response files and stdin, the `@file` convention git, gcc and java use for
+ * command lines too long to type or to pass through the shell's ARG_MAX.
+ *
+ * ```ts
+ * import { expandArgFiles, readStdin } from 'clap-ts/argfile';
+ *
+ * await runMain(main, { argv: expandArgFiles() });
+ * ```
+ *
+ * clap has no equivalent, so the shape here follows gcc: one argument per line,
+ * `#` comments and blank lines skipped, quoted runs kept together, and a
+ * literal `@` escaped as `@@`.
+ */
+export interface ArgFileOptions {
+    /** Prefix marking a response file (default '@'). */
+    readonly prefix?: string;
+    /** How deep a response file may reference another (default 5). */
+    readonly maxDepth?: number;
+    /** Read a file's text. Defaults to reading UTF-8 from disk. */
+    readonly read?: (path: string) => string;
+}
+/**
+ * Split response-file text into arguments.
+ *
+ * Whitespace separates, `#` at the start of a line comments the rest of it out,
+ * and single or double quotes group a run containing spaces. A backslash
+ * escapes the next character inside or outside quotes.
+ */
+export declare function parseArgFile(text: string): string[];
+/**
+ * Replace every `@file` in argv with that file's arguments.
+ *
+ * Reads `process.argv` when given nothing. A response file may reference
+ * another up to `maxDepth`; `@@` is a literal argument starting with `@`, and
+ * everything after a bare `--` is left alone.
+ */
+export declare function expandArgFiles(argv?: readonly string[], opts?: ArgFileOptions): string[];
+/**
+ * Read all of stdin as text, for the `-` convention meaning "read from stdin".
+ *
+ * Resolves to undefined when stdin is a terminal, so an interactive run does
+ * not hang waiting for input that is never coming.
+ */
+export declare function readStdin(): Promise<string | undefined>;
+/**
+ * Resolve a path argument, reading stdin when it is `-`.
+ *
+ * ```ts
+ * const source = await readPathOrStdin(args.input);
+ * ```
+ */
+export declare function readPathOrStdin(path: string, opts?: {
+    readonly read?: (path: string) => string;
+}): Promise<string>;

package/dist/argfile.js

@@ -0,0 +1,155 @@
+/**
+ * Response files and stdin, the `@file` convention git, gcc and java use for
+ * command lines too long to type or to pass through the shell's ARG_MAX.
+ *
+ * ```ts
+ * import { expandArgFiles, readStdin } from 'clap-ts/argfile';
+ *
+ * await runMain(main, { argv: expandArgFiles() });
+ * ```
+ *
+ * clap has no equivalent, so the shape here follows gcc: one argument per line,
+ * `#` comments and blank lines skipped, quoted runs kept together, and a
+ * literal `@` escaped as `@@`.
+ */
+import { readFileSync } from 'node:fs';
+import { getRawArgs } from './parser.js';
+/**
+ * Split response-file text into arguments.
+ *
+ * Whitespace separates, `#` at the start of a line comments the rest of it out,
+ * and single or double quotes group a run containing spaces. A backslash
+ * escapes the next character inside or outside quotes.
+ */
+export function parseArgFile(text) {
+    const args = [];
+    let current = '';
+    let quote;
+    let hasToken = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '\\' && i + 1 < text.length) {
+            current += text[i + 1];
+            hasToken = true;
+            i++;
+            continue;
+        }
+        if (quote !== undefined) {
+            if (ch === quote) {
+                quote = undefined;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            hasToken = true;
+            continue;
+        }
+        // A comment runs to the end of its line, and only starts a token boundary.
+        if (ch === '#' && !hasToken) {
+            while (i < text.length && text[i] !== '\n') {
+                i++;
+            }
+            continue;
+        }
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
+            if (hasToken) {
+                args.push(current);
+                current = '';
+                hasToken = false;
+            }
+            continue;
+        }
+        current += ch;
+        hasToken = true;
+    }
+    if (quote !== undefined) {
+        throw new Error(`unterminated ${quote === '"' ? 'double' : 'single'} quote in response file`);
+    }
+    if (hasToken) {
+        args.push(current);
+    }
+    return args;
+}
+/**
+ * Replace every `@file` in argv with that file's arguments.
+ *
+ * Reads `process.argv` when given nothing. A response file may reference
+ * another up to `maxDepth`; `@@` is a literal argument starting with `@`, and
+ * everything after a bare `--` is left alone.
+ */
+export function expandArgFiles(argv = getRawArgs(), opts) {
+    const prefix = opts?.prefix ?? '@';
+    const maxDepth = opts?.maxDepth ?? 5;
+    const read = opts?.read ?? ((path) => readFileSync(path, 'utf8'));
+    const expand = (tokens, depth) => {
+        const out = [];
+        let escaped = false;
+        for (const token of tokens) {
+            if (escaped || !token.startsWith(prefix) || token.length === prefix.length) {
+                out.push(token);
+                if (token === '--') {
+                    escaped = true;
+                }
+                continue;
+            }
+            // `@@file` means a literal argument that happens to start with `@`.
+            if (token.startsWith(prefix + prefix)) {
+                out.push(token.slice(prefix.length));
+                continue;
+            }
+            if (depth >= maxDepth) {
+                throw new Error(`response files nested more than ${String(maxDepth)} deep at '${token}'`);
+            }
+            const path = token.slice(prefix.length);
+            let text;
+            try {
+                text = read(path);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                throw new Error(`cannot read response file '${path}': ${message}`);
+            }
+            out.push(...expand(parseArgFile(text), depth + 1));
+        }
+        return out;
+    };
+    return expand(argv, 0);
+}
+/**
+ * Read all of stdin as text, for the `-` convention meaning "read from stdin".
+ *
+ * Resolves to undefined when stdin is a terminal, so an interactive run does
+ * not hang waiting for input that is never coming.
+ */
+export async function readStdin() {
+    if (process.stdin.isTTY === true) {
+        return undefined;
+    }
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Resolve a path argument, reading stdin when it is `-`.
+ *
+ * ```ts
+ * const source = await readPathOrStdin(args.input);
+ * ```
+ */
+export async function readPathOrStdin(path, opts) {
+    if (path === '-') {
+        const text = await readStdin();
+        if (text === undefined) {
+            throw new Error('reading from stdin was requested but stdin is a terminal');
+        }
+        return text;
+    }
+    const read = opts?.read ?? ((p) => readFileSync(p, 'utf8'));
+    return read(path);
+}

package/dist/completions.d.ts

@@ -7,6 +7,7 @@
  * 2. Dynamic: completeEnv() checks env vars, outputs completions, returns true if handled
  */
 import type { CommandDef, Shell } from './types.js';
+export type { Shell, ValueHint } from './types.js';
 /**
  * Generate a shell completion script for the given command and shell.
  *
@@ -21,6 +22,8 @@ import type { CommandDef, Shell } from './types.js';
  * - 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 declare function generateCompletions(command: CommandDef, shell: Shell, binaryName?: string): string;
 /**
@@ -37,4 +40,4 @@ export declare function generateCompletions(command: CommandDef, shell: Shell, b
  * eval "$(my-cli completions bash)"
  * ```
  */
-export declare function withCompletions<T extends CommandDef>(rootCommand: T): T;
+export declare function withCompletions(rootCommand: CommandDef<any>): CommandDef<any>;

package/dist/completions.js

@@ -6,12 +6,25 @@
  * 1. Static: generateCompletions() returns a shell script string to source
  * 2. Dynamic: completeEnv() checks env vars, outputs completions, returns true if handled
  */
+import { possibleValues, subCommandsOf } from './parser.js';
 /** Extract completion-relevant data from a CommandDef tree. */
 function buildCompletionTree(command, name) {
     const flags = [];
+    const positionals = [];
     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;
@@ -21,20 +34,24 @@ function buildCompletionTree(command, name) {
             long: longName,
             description: def.description ?? '',
             takesValue: def.type !== 'boolean' && def.action !== 'count',
-            possibleValues: Array.isArray(def.valueParser) ? def.valueParser : [],
+            possibleValues: possibleValues(def)
+                .filter((v) => !v.hidden)
+                .map((v) => v.name),
             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) {
+    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 = [];
     const childNodes = new Map();
-    if (command.subCommands) {
-        for (const [subName, subDef] of Object.entries(command.subCommands)) {
+    {
+        for (const [subName, subDef] of Object.entries(subCommandsOf(command))) {
             subcommands.push({
                 name: subName,
                 description: subDef.meta.description ?? '',
@@ -46,7 +63,9 @@ function buildCompletionTree(command, name) {
     }
     return {
         name: name ?? command.meta.name,
+        description: command.meta.description ?? command.meta.about ?? '',
         flags,
+        positionals,
         subcommands,
         childNodes,
     };
@@ -285,7 +304,12 @@ function zshValueHintSpec(hint, key) {
         case 'hostname': return `:${key}:_hosts`;
         case 'username': return `:${key}:_users`;
         case 'url': return `:${key}:_urls`;
-        case 'emailAddress': return `:${key}:`;
+        case 'commandString': return `:${key}:_cmdstring`;
+        case 'commandWithArguments': return `:${key}:_command_names -e`;
+        case 'emailAddress':
+        case 'other':
+        case 'unknown':
+            return `:${key}:`;
     }
 }
 // ---- Fish Generator ----
@@ -434,7 +458,6 @@ function generatePowerShellNode(node, indent, tokensVar, depth, lines) {
     // 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)}')`);
@@ -447,6 +470,158 @@ function generatePowerShellNode(node, indent, tokensVar, depth, lines) {
         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, binaryName) {
+    const cases = [];
+    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, path, cases) {
+    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, binaryName) {
+    const lines = [];
+    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) {
+    switch (hint) {
+        case 'filePath':
+        case 'anyPath':
+        case 'executablePath':
+            return 'path';
+        case 'dirPath':
+            return 'directory';
+        default:
+            return 'string';
+    }
+}
+function collectNushellCommand(node, path, lines) {
+    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.
@@ -462,6 +637,8 @@ function generatePowerShellNode(node, indent, tokensVar, depth, lines) {
  * - 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, shell, binaryName) {
     const name = binaryName ?? command.meta.name;
@@ -471,10 +648,19 @@ export function generateCompletions(command, shell, binaryName) {
         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 = ['bash', 'zsh', 'fish', 'powershell'];
+const VALID_SHELLS = [
+    'bash',
+    'zsh',
+    'fish',
+    'powershell',
+    'elvish',
+    'nushell',
+];
 /**
  * Return a new command with a `completions` subcommand auto-injected.
  * The subcommand generates shell completion scripts when invoked.
@@ -501,16 +687,12 @@ export function withCompletions(rootCommand) {
                 type: 'positional',
                 valueName: 'SHELL',
                 required: true,
-                description: 'Target shell: bash, zsh, fish, or powershell',
+                description: `Target shell: ${VALID_SHELLS.join(', ')}`,
+                valueParser: [...VALID_SHELLS],
             },
         },
-        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));
+        run({ args, stdout }) {
+            stdout.write(generateCompletions(rootCommand, String(args['shell'])));
         },
     };
     return {
@@ -519,5 +701,6 @@ export function withCompletions(rootCommand) {
             ...rootCommand.subCommands,
             completions: completionsCmd,
         },
+        lazySubCommands: rootCommand.lazySubCommands,
     };
 }

package/dist/config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Configuration file loading, layered under the command line and environment.
+ *
+ * ```ts
+ * import { loadConfig } from 'clap-ts/config';
+ *
+ * const config = loadConfig('mytool');
+ * await runMain(main, { config: config?.values });
+ * ```
+ *
+ * Precedence ends up as command line, then environment, then config file, then
+ * the argument's own default. `ctx.valueSources` reports which one won.
+ *
+ * Only JSON is understood out of the box, which keeps this dependency-free.
+ * Point `parse` at a TOML or YAML reader to accept those.
+ *
+ * The search costs one `existsSync` per candidate per directory, so it is
+ * O(directories x candidates) and independent of how many files those
+ * directories hold. Listing each directory once instead would be one syscall
+ * per level, but `readdirSync` is O(entries): measured against a 2000-entry
+ * directory it took 117us where four `existsSync` calls took 2.4us. Walking up
+ * through a large directory is exactly the case that has to stay cheap.
+ */
+/** A loaded configuration file. */
+export interface LoadedConfig {
+    /** The parsed contents, ready for `RunOptions.config`. */
+    readonly values: Record<string, unknown>;
+    /** Absolute path of the file the values came from. */
+    readonly path: string;
+}
+export interface ConfigOptions {
+    /**
+     * File names to look for, in order of preference. Defaults to
+     * `.<name>rc`, `.<name>rc.json`, `<name>.config.json` and `.config/<name>.json`.
+     */
+    readonly files?: readonly string[];
+    /** Directory to start searching from (default: `process.cwd()`). */
+    readonly cwd?: string;
+    /** Stop searching at this directory, inclusive (default: the home directory). */
+    readonly stopAt?: string;
+    /**
+     * Read this key out of a `package.json` found during the walk. Defaults to
+     * the tool name; pass `null` to skip package.json entirely.
+     */
+    readonly packageJsonKey?: string | null;
+    /** Parse a file's text. Defaults to `JSON.parse`. */
+    readonly parse?: (text: string, path: string) => unknown;
+    /** Load exactly this file and skip the search. */
+    readonly path?: string;
+    /** Search parent directories as well as `cwd` (default: true). */
+    readonly searchParents?: boolean;
+    /**
+     * Stop once a directory holding `package.json` or `.git` has been examined.
+     * Cuts the walk to the project, which is where a project's config lives.
+     */
+    readonly stopAtProjectRoot?: boolean;
+}
+/**
+ * Find and read the nearest configuration file, walking up from `cwd`.
+ *
+ * Returns `undefined` when nothing is found, and throws only when a file exists
+ * but cannot be read or parsed: a broken config should be loud, a missing one
+ * should not.
+ */
+export declare function loadConfig(name: string, opts?: ConfigOptions): LoadedConfig | undefined;
+/**
+ * Load a config and hand back the run options to spread into `runMain`.
+ *
+ * ```ts
+ * await runMain(main, { ...configOptions('mytool') });
+ * ```
+ */
+export declare function configOptions(name: string, opts?: ConfigOptions): {
+    config: () => Record<string, unknown> | undefined;
+};