clap-ts 0.2.0 → 0.3.0

package/dist/runner.js

@@ -4,7 +4,7 @@
  * Supports inferSubcommands, subcommandRequired, allowExternalSubcommands,
  * argsConflictsWithSubcommands, argRequiredElseHelp, and custom styles.
  */
-import { CliParseError, collectGlobalArgs, getRawArgs, mergeGlobalArgs, parseArgs, } from './parser.js';
+import { CliParseError, coerceValue, collectGlobalArgs, getRawArgs, hasSubCommands, kebabToCamel, mergeGlobalArgs, parseArgs, subCommandsOf, } from './parser.js';
 import { validate } from './validation.js';
 import { showError, showHelp, showVersion } from './help.js';
 // ---- defineCommand ----
@@ -53,104 +53,199 @@ export function defineArgs(args) {
 export function defineArg(arg) {
     return arg;
 }
-// ---- Subcommand Resolution ----
+// ---- Config Layer ----
 /**
- * Find a subcommand by prefix matching (inferSubcommands).
- * Returns the match if exactly one, 'ambiguous' if multiple, undefined if none.
+ * The config section that applies to a command, built by walking the path from
+ * the root. A nested object named for a subcommand scopes its contents to that
+ * command; scalar keys stay in scope all the way down.
  */
-function findSubcommandByPrefix(subCommands, token) {
-    const matches = [];
-    for (const [name, def] of Object.entries(subCommands)) {
-        if (name.startsWith(token)) {
-            matches.push({ name, def });
+function configForPath(config, path) {
+    let scope = config;
+    const merged = {};
+    const takeScalars = (from) => {
+        for (const key of Object.keys(from)) {
+            const value = from[key];
+            if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                continue;
+            }
+            merged[key] = value;
         }
-        else if (def.meta.aliases?.some((a) => a.startsWith(token))) {
-            matches.push({ name, def });
+    };
+    takeScalars(scope);
+    for (const segment of path) {
+        const next = scope[segment];
+        if (next === null || typeof next !== 'object' || Array.isArray(next)) {
+            break;
         }
+        scope = next;
+        takeScalars(scope);
     }
-    if (matches.length === 1) {
-        return matches[0];
-    }
-    if (matches.length > 1) {
-        return 'ambiguous';
-    }
-    return undefined;
+    return merged;
 }
 /**
- * Resolve the command chain from the root command and raw args.
- * Supports inferSubcommands for prefix matching.
+ * Fill args the command line and environment left alone from the config.
+ * A default already applied during parsing loses to a config value, which is
+ * what makes the precedence CLI > env > config > default.
  */
-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('-')) {
+function applyConfig(result, command, source, path) {
+    const argsDef = command.args ?? {};
+    // Nothing to fill means nothing to load: with a thunk, a command line that
+    // answered every argument never touches the filesystem.
+    let anyOpen = false;
+    for (const key of Object.keys(argsDef)) {
+        const from = result.valueSources.get(key);
+        if (from !== 'cli' && from !== 'env') {
+            anyOpen = true;
             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;
-                }
-            }
+    }
+    if (!anyOpen) {
+        return result;
+    }
+    const config = typeof source === 'function' ? source() : source;
+    if (config === undefined) {
+        return result;
+    }
+    const section = configForPath(config, path);
+    const args = { ...result.args };
+    const valueSources = new Map(result.valueSources);
+    let changed = false;
+    for (const key of Object.keys(argsDef)) {
+        const raw = section[key];
+        if (raw === undefined) {
+            continue;
+        }
+        const source = valueSources.get(key);
+        if (source === 'cli' || source === 'env') {
+            continue;
         }
-        // allowExternalSubcommands: accept unknown subcommand and stop
-        if (current.meta.allowExternalSubcommands) {
-            remaining.shift();
-            return { command: current, remainingArgs: remaining, parentNames, externalSubcommand: token };
+        const def = argsDef[key];
+        const name = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
+        const coerce = (value) => coerceValue(String(value), def, `config:${name}`);
+        args[key] = Array.isArray(raw) ? raw.map((v) => String(coerce(v))) : coerce(raw);
+        args[kebabToCamel(key)] = args[key];
+        valueSources.set(key, 'config');
+        changed = true;
+    }
+    return changed ? { ...result, args, valueSources } : result;
+}
+/** Required args that argv, the environment and the config all left empty. */
+function missingRequired(command, result) {
+    const argsDef = command.args ?? {};
+    const missing = [];
+    for (const key of Object.keys(argsDef)) {
+        const def = argsDef[key];
+        if (def.required !== true || result.args[key] !== undefined) {
+            continue;
         }
-        // Not a subcommand, stop resolution
+        // requiredUnlessPresent and friends may excuse it; leave those to validate.
+        if (def.requiredUnlessPresent !== undefined || def.requiredUnlessPresentAll !== undefined) {
+            continue;
+        }
+        missing.push({
+            key,
+            def,
+            label: def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`,
+        });
+    }
+    return missing;
+}
+/** Fold values supplied by a fillMissing hook into the result. */
+function applyFilled(result, command, filled) {
+    const argsDef = command.args ?? {};
+    const args = { ...result.args };
+    const explicitlySet = new Set(result.explicitlySet);
+    const valueSources = new Map(result.valueSources);
+    for (const key of Object.keys(filled)) {
+        const def = argsDef[key];
+        const raw = filled[key];
+        if (def === undefined || raw === undefined) {
+            continue;
+        }
+        const name = def.type === 'positional' ? `<${def.valueName ?? key}>` : `--${def.long ?? key}`;
+        const coerce = (value) => typeof value === 'boolean' ? value : coerceValue(String(value), def, `prompt:${name}`);
+        args[key] = Array.isArray(raw) ? raw.map((v) => String(coerce(v))) : coerce(raw);
+        args[kebabToCamel(key)] = args[key];
+        explicitlySet.add(key);
+        valueSources.set(key, 'prompt');
+    }
+    return { ...result, args, explicitlySet, valueSources };
+}
+// ---- Global Args ----
+/**
+ * Overlay inherited global args onto a command. The command's own args win, and
+ * a command with nothing to inherit is returned untouched so the parser's spec
+ * cache still hits.
+ */
+function applyGlobals(command, globals, propagatedVersion) {
+    let hasGlobals = false;
+    for (const _key in globals) {
+        hasGlobals = true;
         break;
     }
-    return { command: current, remainingArgs: remaining, parentNames };
+    const needsVersion = propagatedVersion !== undefined && command.meta.version === undefined;
+    if (!hasGlobals && !needsVersion) {
+        return command;
+    }
+    return {
+        ...command,
+        meta: needsVersion ? { ...command.meta, version: propagatedVersion } : command.meta,
+        args: hasGlobals ? mergeGlobalArgs(globals, command.args ?? {}) : command.args,
+    };
 }
-/** 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;
+/**
+ * Walk a chain of subcommand names from a command, for `app help sub subsub`.
+ * Returns the deepest command reached and the names of its ancestors.
+ */
+function resolveHelpTarget(root, rootParents, path) {
+    let current = root;
+    const parentNames = [...rootParents];
+    for (const name of path) {
+        const next = subCommandsOf(current)[name];
+        if (next === undefined) {
+            break;
+        }
+        parentNames.push(current.meta.name);
+        current = next;
+    }
+    return { command: current, parentNames };
+}
+/**
+ * Overlay global values captured at ancestor levels onto the resolved command's
+ * result. A value given again at this level always wins.
+ */
+function applyInheritedGlobals(result, inherited) {
+    if (inherited.size === 0) {
+        return result;
+    }
+    const args = { ...result.args };
+    const explicitlySet = new Set(result.explicitlySet);
+    const valueSources = new Map(result.valueSources);
+    for (const [key, value] of inherited) {
+        if (explicitlySet.has(key)) {
+            continue;
         }
+        args[kebabToCamel(key)] = value;
+        args[key] = value;
+        explicitlySet.add(key);
+        valueSources.set(key, 'cli');
     }
-    return undefined;
+    return { ...result, args, explicitlySet, valueSources };
 }
 // ---- runCommand ----
 /**
  * Run a specific command with pre-parsed arguments.
  * Executes the setup -> run -> cleanup lifecycle.
  */
-export async function runCommand(command, args, rawArgs = [], subCommand) {
+export async function runCommand(command, args, rawArgs = [], subCommand, valueSources = new Map(), io) {
     const ctx = {
         rawArgs,
         args,
         cmd: command,
         subCommand,
+        valueSources,
+        stdout: io?.stdout ?? process.stdout,
+        stderr: io?.stderr ?? process.stderr,
         data: {},
     };
     let runError;
@@ -227,32 +322,44 @@ function simpleCharDistance(a, b, maxDist) {
 }
 // ---- 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);
-    }
+function handleHelpRequest(command, parentNames, isShortHelp, io) {
+    showHelp(command, parentNames.length > 0 ? parentNames : undefined, isShortHelp, io.styles, io.stdout);
+    io.finish(0);
 }
 /** Handle --version request. */
-function handleVersionRequest(effectiveCommand, rootCommand, shouldExit) {
+function handleVersionRequest(effectiveCommand, rootCommand, isShort, io) {
     const versionMeta = effectiveCommand.meta.version ? effectiveCommand.meta : rootCommand.meta;
-    showVersion(versionMeta);
-    if (shouldExit) {
-        process.exit(0);
-    }
+    showVersion(versionMeta, isShort, io.stdout);
+    io.finish(0);
 }
 /** Handle an unrecognized subcommand with typo suggestion. */
-function handleUnrecognizedSubcommand(unknownName, command, parentNames, shouldExit, styles) {
-    const allNames = collectSubcommandNames(command.subCommands);
+function handleUnrecognizedSubcommand(unknownName, command, parentNames, io) {
+    const allNames = collectSubcommandNames(subCommandsOf(command));
     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);
-    }
+    fail(msg, command, parentNames, io);
+}
+function makeRunIO(opts) {
+    const shouldExit = opts?.exit !== false;
+    return {
+        stdout: opts?.stdout ?? process.stdout,
+        stderr: opts?.stderr ?? process.stderr,
+        styles: opts?.styles,
+        finish(code) {
+            opts?.onExit?.(code);
+            if (shouldExit) {
+                process.exit(code);
+            }
+        },
+    };
+}
+/** Print a usage error against the given command and settle on exit code 2. */
+function fail(message, command, parentNames, io) {
+    showError(message, command, parentNames.length > 0 ? parentNames : undefined, io.styles, io.stderr);
+    io.finish(2);
 }
 // ---- runMain ----
 /**
@@ -265,105 +372,204 @@ function handleUnrecognizedSubcommand(unknownName, command, parentNames, shouldE
  * ```
  */
 export async function runMain(rootCommand, opts) {
+    const io = makeRunIO(opts);
     const shouldExit = opts?.exit !== false;
     const showHelpOnEmpty = opts?.showHelpOnEmpty !== false;
-    const styles = opts?.styles;
+    // Tracked through the descent so an error names the command that failed,
+    // not the root.
+    let errorCommand = rootCommand;
+    let errorParents = [];
     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);
+        let rawArgs = getRawArgs(opts?.argv, rootCommand.meta.noBinaryName === true);
+        // multicall: the name the binary was invoked under selects the subcommand.
+        if (rootCommand.meta.multicall && opts?.argv === undefined) {
+            const invoked = process.argv[1];
+            if (invoked !== undefined) {
+                const base = invoked.slice(invoked.lastIndexOf('/') + 1).replace(/\.[cm]?[jt]s$/, '');
+                rawArgs = [base, ...rawArgs];
+            }
+        }
+        let command = rootCommand;
+        let effectiveCommand = rootCommand;
+        let inheritedGlobals = {};
+        // Values of global args given at an ancestor level. clap carries these down
+        // to the command that finally runs, so `app --verbose serve` reaches serve.
+        const inheritedValues = new Map();
+        let propagatedVersion;
+        let argv = rawArgs;
+        const parentNames = [];
+        let parseResult = parseArgs([], rootCommand);
+        let externalSubcommand;
+        // Descend the subcommand chain one level at a time, parsing as we go: only
+        // the arg spec can say whether a bare token is a subcommand or the value of
+        // a preceding flag.
+        for (;;) {
+            inheritedGlobals = mergeGlobalArgs(inheritedGlobals, collectGlobalArgs(command));
+            if (command.meta.propagateVersion && command.meta.version !== undefined) {
+                propagatedVersion = command.meta.version;
+            }
+            effectiveCommand = applyGlobals(command, inheritedGlobals, propagatedVersion);
+            errorCommand = effectiveCommand;
+            errorParents = [...parentNames];
+            parseResult = parseArgs(argv, effectiveCommand);
+            for (const warning of parseResult.warnings) {
+                io.stderr.write(`warning: ${warning}\n`);
+            }
+            if (command.meta.deprecated !== undefined && command.meta.deprecated !== false) {
+                const reason = typeof command.meta.deprecated === 'string' ? `: ${command.meta.deprecated}` : '';
+                const instead = command.meta.replacedBy === undefined ? '' : `; use '${command.meta.replacedBy}' instead`;
+                io.stderr.write(`warning: '${command.meta.name}' is deprecated${reason}${instead}\n`);
             }
+            // The built-in `help` subcommand: `app help`, `app help sub sub`.
+            if (parseResult.subCommand === undefined &&
+                hasSubCommands(command) &&
+                command.meta.disableHelpSubcommand !== true &&
+                parseResult.positionals[0] === 'help') {
+                const target = resolveHelpTarget(effectiveCommand, parentNames, parseResult.positionals.slice(1));
+                handleHelpRequest(target.command, target.parentNames, false, io);
+                return;
+            }
+            for (const key of Object.keys(inheritedGlobals)) {
+                if (parseResult.explicitlySet.has(key)) {
+                    const value = parseResult.args[key];
+                    if (value !== undefined) {
+                        inheritedValues.set(key, value);
+                    }
+                }
+            }
+            if (parseResult.subCommand === undefined ||
+                parseResult.helpRequested ||
+                parseResult.versionRequested) {
+                break;
+            }
+            if (parseResult.subCommandIsExternal) {
+                externalSubcommand = parseResult.subCommand;
+                break;
+            }
+            if (command.meta.argsConflictsWithSubcommands && parseResult.explicitlySet.size > 0) {
+                fail('arguments cannot be used with subcommands', effectiveCommand, parentNames, io);
+                return;
+            }
+            const next = subCommandsOf(command)[parseResult.subCommand];
+            if (next === undefined) {
+                break;
+            }
+            // A parent's own constraints still apply to the flags given before the
+            // subcommand, unless it opted out with subcommandNegatesReqs.
+            if (!command.meta.subcommandNegatesReqs) {
+                validate(parseResult, effectiveCommand);
+            }
+            parentNames.push(command.meta.name);
+            command = next;
+            argv = parseResult.subCommandArgs;
+        }
+        // External subcommand: hand the name and the untouched remainder to the
+        // command that declared allowExternalSubcommands.
+        if (externalSubcommand !== undefined) {
+            if (effectiveCommand.run) {
+                const parser = effectiveCommand.externalSubcommandValueParser;
+                const externalArgs = parser === undefined
+                    ? parseResult.subCommandArgs
+                    : parseResult.subCommandArgs.map((value) => {
+                        try {
+                            return String(parser(value));
+                        }
+                        catch (error) {
+                            const message = error instanceof Error ? error.message : String(error);
+                            throw new CliParseError(`invalid value '${value}': ${message}`);
+                        }
+                    });
+                await runCommand(effectiveCommand, parseResult.args, externalArgs, externalSubcommand, parseResult.valueSources, io);
+            }
+            io.finish(0);
             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);
+            handleHelpRequest(effectiveCommand, parentNames, parseResult.helpIsShort, io);
             return;
         }
         // Handle --version
         if (parseResult.versionRequested) {
-            handleVersionRequest(effectiveCommand, rootCommand, shouldExit);
+            handleVersionRequest(effectiveCommand, rootCommand, parseResult.versionIsShort, io);
             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);
+            hasSubCommands(rootCommand)) {
+            handleHelpRequest(rootCommand, [], false, io);
             return;
         }
         // argRequiredElseHelp: show help if no args were explicitly provided
         if (command.meta.argRequiredElseHelp && parseResult.explicitlySet.size === 0) {
-            handleHelpRequest(command, parentNames, shouldExit, false, styles);
+            handleHelpRequest(effectiveCommand, parentNames, false, io);
             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 &&
+        if (hasSubCommands(command) &&
             !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);
+                    handleUnrecognizedSubcommand(parseResult.positionals[0], effectiveCommand, parentNames, io);
                 }
                 else {
-                    showError("a subcommand is required but one was not provided", command, parentNames.length > 0 ? parentNames : undefined, styles);
-                    if (shouldExit) {
-                        process.exit(2);
-                    }
+                    fail('a subcommand is required but one was not provided', effectiveCommand, parentNames, io);
                 }
                 return;
             }
             if (parseResult.positionals.length > 0) {
-                handleUnrecognizedSubcommand(parseResult.positionals[0], command, parentNames, shouldExit, styles);
+                handleUnrecognizedSubcommand(parseResult.positionals[0], effectiveCommand, parentNames, io);
                 return;
             }
-            handleHelpRequest(command, parentNames, shouldExit, false, styles);
+            handleHelpRequest(effectiveCommand, parentNames, false, io);
             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);
+        // Fold ancestor-provided global values into the command that runs, then
+        // let the config fill whatever is still on its default.
+        let finalResult = applyInheritedGlobals(parseResult, inheritedValues);
+        if (opts?.config !== undefined) {
+            finalResult = applyConfig(finalResult, effectiveCommand, opts.config, [
+                ...parentNames.slice(1),
+                ...(parentNames.length > 0 ? [command.meta.name] : []),
+            ]);
+        }
+        // Last chance to supply what is still missing, before validation says no.
+        if (opts?.fillMissing !== undefined) {
+            const missing = missingRequired(effectiveCommand, finalResult);
+            if (missing.length > 0) {
+                const filled = await opts.fillMissing(missing, effectiveCommand);
+                if (filled !== undefined) {
+                    finalResult = applyFilled(finalResult, effectiveCommand, filled);
+                }
             }
-            return;
         }
         // Validate parsed args
-        validate(parseResult, effectiveCommand);
+        validate(finalResult, effectiveCommand);
         // Run the command
-        await runCommand(effectiveCommand, parseResult.args, rawArgs);
+        await runCommand(effectiveCommand, finalResult.args, rawArgs, undefined, finalResult.valueSources, io);
+        // If the command's run() didn't call process.exit() itself, exit cleanly.
+        // This prevents the process from hanging when the caller uses `void runMain()`
+        // instead of `await runMain()` — the unawaited Promise would otherwise keep
+        // the event loop alive due to pending NAPI handles or other resources.
+        io.finish(0);
     }
     catch (error) {
         if (error instanceof CliParseError) {
-            showError(error.message, rootCommand, undefined, styles);
-            if (shouldExit) {
-                process.exit(2);
-            }
+            fail(error.message, errorCommand, errorParents, io);
             return;
         }
         // Unexpected error
-        if (shouldExit) {
+        if (shouldExit || opts?.onExit !== undefined) {
             const message = error instanceof Error ? error.message : String(error);
-            process.stderr.write(`error: ${message}\n`);
-            process.exit(1);
+            io.stderr.write(`error: ${message}\n`);
+            io.finish(1);
+            if (!shouldExit) {
+                return;
+            }
         }
         throw error;
     }