@guanghechen/commander 1.0.12 → 2.1.0

package/lib/esm/index.mjs

@@ -1,155 +1,1034 @@
-import { Command as Command$1 } from 'commander';
-import { commandExistsSync } from '@guanghechen/cli';
-export * from '@guanghechen/cli';
-import { safeExec } from '@guanghechen/exec';
-import select from '@inquirer/select';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
-class Command extends Command$1 {
-    _actionHandler;
-    _optionValues;
-    _storeOptionsAsProperties;
-    _version;
-    _versionOptionName;
-    constructor() {
-        super();
-        this._optionValues = {};
-        this._storeOptionsAsProperties = false;
+class CommanderError extends Error {
+    kind;
+    commandPath;
+    constructor(kind, message, commandPath) {
+        super(message);
+        this.name = 'CommanderError';
+        this.kind = kind;
+        this.commandPath = commandPath;
+    }
+    format() {
+        return `Error: ${this.message}\nRun "${this.commandPath} --help" for usage.`;
+    }
+}
+
+class DefaultReporter {
+    debug(message, ...args) {
+        console.debug(message, ...args);
+    }
+    info(message, ...args) {
+        console.info(message, ...args);
+    }
+    warn(message, ...args) {
+        console.warn(message, ...args);
+    }
+    error(message, ...args) {
+        console.error(message, ...args);
+    }
+}
+const BUILTIN_HELP_OPTION = {
+    long: 'help',
+    short: 'h',
+    type: 'boolean',
+    description: 'Show help information',
+};
+const BUILTIN_VERSION_OPTION = {
+    long: 'version',
+    short: 'V',
+    type: 'boolean',
+    description: 'Show version number',
+};
+class Command {
+    #name;
+    #description;
+    #version;
+    #aliases;
+    #helpSubcommandEnabled;
+    #options = [];
+    #arguments = [];
+    #subcommands = [];
+    #action;
+    #parent;
+    constructor(config) {
+        this.#name = config.name;
+        this.#description = config.description;
+        this.#version = config.version;
+        this.#aliases = config.aliases ?? [];
+        this.#helpSubcommandEnabled = config.help ?? false;
+    }
+    get name() {
+        return this.#name;
+    }
+    get aliases() {
+        return this.#aliases;
+    }
+    get description() {
+        return this.#description;
+    }
+    get version() {
+        return this.#version ?? this.#parent?.version;
+    }
+    get parent() {
+        return this.#parent;
+    }
+    get options() {
+        return [...this.#options];
+    }
+    get arguments() {
+        return [...this.#arguments];
+    }
+    option(opt) {
+        this.#validateOptionConfig(opt);
+        this.#checkOptionUniqueness(opt);
+        this.#options.push(opt);
+        return this;
+    }
+    argument(arg) {
+        this.#validateArgumentConfig(arg);
+        this.#arguments.push(arg);
+        return this;
     }
     action(fn) {
-        const listener = (args) => {
-            const expectedArgsCount = this.registeredArguments.length;
-            const actionArgs = [
-                args.slice(0, expectedArgsCount),
-                this.opts(),
-                args.slice(expectedArgsCount),
-                this,
-            ];
-            const actionResult = fn.apply(this, actionArgs);
-            return actionResult;
-        };
-        this._actionHandler = listener;
+        this.#action = fn;
         return this;
     }
-    opts() {
-        const nodes = [this];
-        for (let parent = this.parent; parent != null; parent = parent.parent) {
-            nodes.push(parent);
+    subcommand(cmd) {
+        if (this.#helpSubcommandEnabled && (cmd.#name === 'help' || cmd.#aliases.includes('help'))) {
+            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
+        }
+        cmd.#parent = this;
+        this.#subcommands.push(cmd);
+        return this;
+    }
+    async run(params) {
+        const { argv, envs, reporter } = params;
+        try {
+            const processedArgv = this.#processHelpSubcommand(argv);
+            const { command, remaining } = this.#route(processedArgv);
+            const allOptions = command.#getMergedOptions();
+            const hasUserHelp = allOptions.some(o => o.long === 'help' && !command.#isBuiltinOption(o));
+            const hasUserVersion = allOptions.some(o => o.long === 'version' && !command.#isBuiltinOption(o));
+            if (!hasUserHelp && command.#hasHelpFlag(remaining, allOptions)) {
+                console.log(command.formatHelp());
+                return;
+            }
+            if (!hasUserVersion && command.#hasVersionFlag(remaining, allOptions)) {
+                console.log(command.version ?? 'unknown');
+                return;
+            }
+            const { opts, args } = command.parse(remaining);
+            const ctx = {
+                cmd: command,
+                envs,
+                reporter: reporter ?? new DefaultReporter(),
+                argv,
+            };
+            for (const opt of allOptions) {
+                if (opt.apply && opts[opt.long] !== undefined) {
+                    opt.apply(opts[opt.long], ctx);
+                }
+            }
+            const actionParams = { ctx, opts, args };
+            if (command.#action) {
+                try {
+                    await command.#action(actionParams);
+                }
+                catch (err) {
+                    if (err instanceof Error) {
+                        console.error(`Error: ${err.message}`);
+                    }
+                    else {
+                        console.error('Error: action failed');
+                    }
+                    process.exit(1);
+                }
+            }
+            else if (command.#subcommands.length > 0) {
+                console.log(command.formatHelp());
+            }
+            else {
+                throw new CommanderError('ConfigurationError', `no action defined for command "${command.#getCommandPath()}"`, command.#getCommandPath());
+            }
+        }
+        catch (err) {
+            if (err instanceof CommanderError) {
+                console.error(err.format());
+                process.exit(2);
+                return;
+            }
+            throw err;
+        }
+    }
+    parse(argv) {
+        const allOptions = this.#getMergedOptions();
+        const opts = {};
+        const args = [];
+        for (const opt of allOptions) {
+            if (opt.default !== undefined) {
+                opts[opt.long] = opt.default;
+            }
+            else if (opt.type === 'boolean') {
+                opts[opt.long] = false;
+            }
+            else if (opt.type === 'string[]' || opt.type === 'number[]') {
+                opts[opt.long] = [];
+            }
+        }
+        let remaining = [...argv];
+        const resolverOptions = allOptions.filter(o => o.resolver);
+        for (const opt of resolverOptions) {
+            const result = opt.resolver(remaining);
+            opts[opt.long] = result.value;
+            remaining = result.remaining;
+        }
+        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(allOptions, true);
+        remaining = this.#normalizeArgv(remaining, booleanOptions);
+        let i = 0;
+        while (i < remaining.length) {
+            const token = remaining[i];
+            if (token === '--') {
+                args.push(...remaining.slice(i + 1));
+                break;
+            }
+            if (token.startsWith('--')) {
+                i = this.#parseLongOption(remaining, i, optionByLong, opts);
+                continue;
+            }
+            if (token.startsWith('-') && token.length > 1) {
+                i = this.#parseShortOption(remaining, i, optionByShort, opts);
+                continue;
+            }
+            args.push(token);
+            i += 1;
+        }
+        for (const opt of allOptions) {
+            if (opt.required && opts[opt.long] === undefined) {
+                throw new CommanderError('MissingRequired', `missing required option "--${opt.long}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
+            }
+        }
+        for (const opt of allOptions) {
+            if (opt.choices && opts[opt.long] !== undefined) {
+                const value = opts[opt.long];
+                const values = Array.isArray(value) ? value : [value];
+                const choices = opt.choices;
+                for (const v of values) {
+                    if (!choices.includes(v)) {
+                        throw new CommanderError('InvalidChoice', `invalid value "${v}" for option "--${opt.long}". Allowed: ${opt.choices.join(', ')}`, this.#getCommandPath());
+                    }
+                }
+            }
+        }
+        const requiredArgs = this.#arguments.filter(a => a.kind === 'required');
+        if (args.length < requiredArgs.length) {
+            const missing = requiredArgs.slice(args.length).map(a => a.name);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        return { opts, args };
+    }
+    formatHelp() {
+        const lines = [];
+        const allOptions = this.#getMergedOptions();
+        lines.push(this.#description);
+        lines.push('');
+        const commandPath = this.#getCommandPath();
+        let usage = `Usage: ${commandPath}`;
+        if (allOptions.length > 0)
+            usage += ' [options]';
+        if (this.#subcommands.length > 0)
+            usage += ' [command]';
+        for (const arg of this.#arguments) {
+            if (arg.kind === 'required') {
+                usage += ` <${arg.name}>`;
+            }
+            else if (arg.kind === 'optional') {
+                usage += ` [${arg.name}]`;
+            }
+            else {
+                usage += ` [${arg.name}...]`;
+            }
+        }
+        lines.push(usage);
+        lines.push('');
+        if (allOptions.length > 0) {
+            lines.push('Options:');
+            const optLines = [];
+            for (const opt of allOptions) {
+                let sig = opt.short ? `-${opt.short}, ` : '    ';
+                sig += `--${opt.long}`;
+                const effectiveType = opt.type ?? 'string';
+                if (effectiveType !== 'boolean') {
+                    sig += ' <value>';
+                }
+                let desc = opt.description;
+                if (opt.default !== undefined && effectiveType !== 'boolean') {
+                    desc += ` (default: ${JSON.stringify(opt.default)})`;
+                }
+                if (opt.choices) {
+                    desc += ` [choices: ${opt.choices.join(', ')}]`;
+                }
+                optLines.push({ sig, desc });
+                if (effectiveType === 'boolean') {
+                    optLines.push({
+                        sig: `    --no-${opt.long}`,
+                        desc: opt.description,
+                    });
+                }
+            }
+            const maxSigLen = Math.max(...optLines.map(l => l.sig.length));
+            for (const { sig, desc } of optLines) {
+                const padding = ' '.repeat(maxSigLen - sig.length + 2);
+                lines.push(`  ${sig}${padding}${desc}`);
+            }
+            lines.push('');
         }
-        const options = {};
-        for (let i = nodes.length - 1; i >= 0; --i) {
-            const o = nodes[i];
-            if (o._storeOptionsAsProperties) {
-                for (const option of o.options) {
-                    const key = option.attributeName();
-                    options[key] = key === o._versionOptionName ? o._version : o[key];
+        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommands.length > 0;
+        if (this.#subcommands.length > 0) {
+            lines.push('Commands:');
+            const cmdLines = [];
+            if (showHelpSubcommand) {
+                cmdLines.push({ name: 'help', desc: 'Show help for a command' });
+            }
+            for (const sub of this.#subcommands) {
+                let name = sub.#name;
+                if (sub.#aliases.length > 0) {
+                    name += `, ${sub.#aliases.join(', ')}`;
+                }
+                cmdLines.push({ name, desc: sub.#description });
+            }
+            const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
+            for (const { name, desc } of cmdLines) {
+                const padding = ' '.repeat(maxNameLen - name.length + 2);
+                lines.push(`  ${name}${padding}${desc}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    getCompletionMeta() {
+        const allOptions = this.#getMergedOptions();
+        const options = [];
+        for (const opt of allOptions) {
+            const effectiveType = opt.type ?? 'string';
+            options.push({
+                long: opt.long,
+                short: opt.short,
+                description: opt.description,
+                takesValue: effectiveType !== 'boolean',
+                choices: opt.choices,
+            });
+        }
+        return {
+            name: this.#name,
+            description: this.#description,
+            aliases: this.#aliases,
+            options,
+            subcommands: this.#subcommands.map(sub => sub.getCompletionMeta()),
+        };
+    }
+    #processHelpSubcommand(argv) {
+        if (!this.#helpSubcommandEnabled || this.#subcommands.length === 0)
+            return argv;
+        if (argv.length < 1 || argv[0] !== 'help')
+            return argv;
+        if (argv.length === 1) {
+            return ['--help'];
+        }
+        const subName = argv[1];
+        const sub = this.#subcommands.find(c => c.#name === subName || c.#aliases.includes(subName));
+        if (sub) {
+            return [subName, '--help', ...argv.slice(2)];
+        }
+        return argv;
+    }
+    #route(argv) {
+        let current = this;
+        let idx = 0;
+        while (idx < argv.length) {
+            const token = argv[idx];
+            if (token.startsWith('-'))
+                break;
+            const sub = current.#subcommands.find(c => c.#name === token || c.#aliases.includes(token));
+            if (!sub)
+                break;
+            current = sub;
+            idx += 1;
+        }
+        return { command: current, remaining: argv.slice(idx) };
+    }
+    #parseLongOption(argv, idx, optionByLong, opts) {
+        const token = argv[idx];
+        const eqIdx = token.indexOf('=');
+        let optName;
+        let inlineValue;
+        if (eqIdx !== -1) {
+            optName = token.slice(2, eqIdx);
+            inlineValue = token.slice(eqIdx + 1);
+        }
+        else {
+            optName = token.slice(2);
+        }
+        const opt = optionByLong.get(optName);
+        if (!opt) {
+            throw new CommanderError('UnknownOption', `unknown option "--${optName}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
+        }
+        if (opt.type === 'boolean') {
+            if (inlineValue !== undefined) {
+                if (inlineValue === 'true') {
+                    opts[optName] = true;
+                }
+                else if (inlineValue === 'false') {
+                    opts[optName] = false;
+                }
+                else {
+                    throw new CommanderError('InvalidBooleanValue', `invalid value "${inlineValue}" for boolean option "--${optName}". Use "true" or "false"`, this.#getCommandPath());
                 }
             }
             else {
-                const optionValues = o._optionValues;
-                for (const key of Object.getOwnPropertyNames(optionValues)) {
-                    options[key] = optionValues[key];
+                opts[optName] = true;
+            }
+            return idx + 1;
+        }
+        let value;
+        let nextIdx = idx;
+        if (inlineValue !== undefined) {
+            value = inlineValue;
+        }
+        else if (idx + 1 < argv.length) {
+            value = argv[idx + 1];
+            nextIdx += 1;
+        }
+        else {
+            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
+        }
+        this.#applyValue(opt, value, opts);
+        return nextIdx + 1;
+    }
+    #parseShortOption(argv, idx, optionByShort, opts) {
+        const token = argv[idx];
+        if (token.includes('=')) {
+            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
+        }
+        const flags = token.slice(1);
+        for (let j = 0; j < flags.length; j++) {
+            const flag = flags[j];
+            const opt = optionByShort.get(flag);
+            if (!opt) {
+                throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
+            }
+            if (opt.type === 'boolean') {
+                opts[opt.long] = true;
+                continue;
+            }
+            if (j < flags.length - 1) {
+                throw new CommanderError('UnsupportedShortSyntax', `"-${flags}" is not supported. Use "-${flags.slice(0, j + 1)} ${flags.slice(j + 1)}" or separate options`, this.#getCommandPath());
+            }
+            if (idx + 1 < argv.length && !argv[idx + 1].startsWith('-')) {
+                const value = argv[idx + 1];
+                this.#applyValue(opt, value, opts);
+                return idx + 2;
+            }
+            throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
+        }
+        return idx + 1;
+    }
+    #applyValue(opt, rawValue, opts) {
+        const type = opt.type ?? 'string';
+        let parsedValue = rawValue;
+        if (opt.coerce) {
+            parsedValue = opt.coerce(rawValue);
+        }
+        else {
+            switch (type) {
+                case 'string':
+                case 'string[]':
+                    parsedValue = rawValue;
+                    break;
+                case 'number':
+                case 'number[]': {
+                    const num = Number(rawValue);
+                    if (Number.isNaN(num)) {
+                        throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${opt.long}"`, this.#getCommandPath());
+                    }
+                    parsedValue = num;
+                    break;
                 }
             }
         }
-        return options;
+        if (type === 'string[]' || type === 'number[]') {
+            const currentValue = opts[opt.long];
+            const current = Array.isArray(currentValue) ? currentValue : [];
+            opts[opt.long] = [...current, parsedValue];
+        }
+        else {
+            opts[opt.long] = parsedValue;
+        }
+    }
+    #getMergedOptions() {
+        const ancestors = [];
+        for (let node = this; node; node = node.#parent) {
+            ancestors.unshift(node);
+        }
+        const optionMap = new Map();
+        const hasUserHelp = ancestors.some(c => c.#options.some(o => o.long === 'help'));
+        const hasUserVersion = ancestors.some(c => c.#options.some(o => o.long === 'version'));
+        if (!hasUserHelp) {
+            optionMap.set('help', BUILTIN_HELP_OPTION);
+        }
+        if (!hasUserVersion) {
+            optionMap.set('version', BUILTIN_VERSION_OPTION);
+        }
+        for (const ancestor of ancestors) {
+            for (const opt of ancestor.#options) {
+                optionMap.set(opt.long, opt);
+            }
+        }
+        const shortToLong = new Map();
+        for (const [long, opt] of optionMap) {
+            if (opt.short) {
+                const existing = shortToLong.get(opt.short);
+                if (existing && existing !== long) {
+                    throw new CommanderError('OptionConflict', `short option "-${opt.short}" is used by both "--${existing}" and "--${long}"`, this.#getCommandPath());
+                }
+                shortToLong.set(opt.short, long);
+            }
+        }
+        return Array.from(optionMap.values());
+    }
+    #validateOptionConfig(opt) {
+        if (opt.long.startsWith('no-')) {
+            throw new CommanderError('ConfigurationError', `option long name cannot start with "no-": "${opt.long}"`, this.#getCommandPath());
+        }
+        if (opt.required && opt.default !== undefined) {
+            throw new CommanderError('ConfigurationError', `option "--${opt.long}" cannot be both required and have a default value`, this.#getCommandPath());
+        }
+        if (opt.type === 'boolean' && opt.required) {
+            throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" cannot be required`, this.#getCommandPath());
+        }
+    }
+    #checkOptionUniqueness(opt) {
+        if (this.#options.some(o => o.long === opt.long)) {
+            throw new CommanderError('OptionConflict', `option "--${opt.long}" is already defined`, this.#getCommandPath());
+        }
+        if (opt.short && this.#options.some(o => o.short === opt.short)) {
+            throw new CommanderError('OptionConflict', `short option "-${opt.short}" is already defined`, this.#getCommandPath());
+        }
+    }
+    #validateArgumentConfig(arg) {
+        if (arg.kind === 'variadic') {
+            if (this.#arguments.some(a => a.kind === 'variadic')) {
+                throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
+            }
+        }
+        if (this.#arguments.length > 0) {
+            const last = this.#arguments[this.#arguments.length - 1];
+            if (last.kind === 'variadic') {
+                throw new CommanderError('ConfigurationError', 'variadic argument must be the last argument', this.#getCommandPath());
+            }
+        }
+        if (arg.kind === 'required') {
+            const hasOptional = this.#arguments.some(a => a.kind === 'optional' || a.kind === 'variadic');
+            if (hasOptional) {
+                throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot come after optional/variadic arguments`, this.#getCommandPath());
+            }
+        }
+    }
+    #isBuiltinOption(opt) {
+        return opt === BUILTIN_HELP_OPTION || opt === BUILTIN_VERSION_OPTION;
+    }
+    #buildOptionMaps(allOptions, excludeResolver = false) {
+        const optionByLong = new Map();
+        const optionByShort = new Map();
+        const booleanOptions = new Set();
+        for (const opt of allOptions) {
+            if (excludeResolver && opt.resolver)
+                continue;
+            optionByLong.set(opt.long, opt);
+            if (opt.short) {
+                optionByShort.set(opt.short, opt);
+            }
+            if (opt.type === 'boolean') {
+                booleanOptions.add(opt.long);
+            }
+        }
+        return { optionByLong, optionByShort, booleanOptions };
+    }
+    #hasHelpFlag(argv, allOptions) {
+        return this.#hasBuiltinFlag(argv, 'help', 'h', allOptions);
+    }
+    #hasVersionFlag(argv, allOptions) {
+        return this.#hasBuiltinFlag(argv, 'version', 'V', allOptions);
+    }
+    #hasBuiltinFlag(argv, flagLong, flagShort, allOptions) {
+        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(allOptions);
+        const normalizedArgv = this.#normalizeArgv(argv, booleanOptions);
+        for (let i = 0; i < normalizedArgv.length; i++) {
+            const arg = normalizedArgv[i];
+            if (arg === '--') {
+                break;
+            }
+            if (arg === `--${flagLong}` || (flagShort && arg === `-${flagShort}`)) {
+                return true;
+            }
+            if (this.#optionConsumesNextValue(arg, optionByLong, optionByShort)) {
+                i += 1;
+            }
+        }
+        return false;
+    }
+    #optionConsumesNextValue(arg, optionByLong, optionByShort) {
+        if (arg.startsWith('--')) {
+            const eqIdx = arg.indexOf('=');
+            if (eqIdx !== -1) {
+                return false;
+            }
+            const optName = arg.slice(2);
+            const opt = optionByLong.get(optName);
+            if (!opt) {
+                return false;
+            }
+            const type = opt.type ?? 'string';
+            return type !== 'boolean';
+        }
+        if (arg.startsWith('-') && arg.length === 2) {
+            const opt = optionByShort.get(arg[1]);
+            if (!opt) {
+                return false;
+            }
+            const type = opt.type ?? 'string';
+            return type !== 'boolean';
+        }
+        return false;
+    }
+    #normalizeArgv(argv, booleanOptions) {
+        const result = [];
+        let seenDoubleDash = false;
+        for (const arg of argv) {
+            if (arg === '--') {
+                seenDoubleDash = true;
+                result.push(arg);
+                continue;
+            }
+            if (!seenDoubleDash && arg.startsWith('--no-')) {
+                const eqIdx = arg.indexOf('=');
+                if (eqIdx !== -1) {
+                    const optName = arg.slice(5, eqIdx);
+                    if (booleanOptions.has(optName)) {
+                        throw new CommanderError('InvalidBooleanValue', `"--no-${optName}" does not accept a value`, this.#getCommandPath());
+                    }
+                }
+                else {
+                    const optName = arg.slice(5);
+                    if (booleanOptions.has(optName)) {
+                        result.push(`--${optName}=false`);
+                        continue;
+                    }
+                }
+            }
+            result.push(arg);
+        }
+        return result;
+    }
+    #getCommandPath() {
+        const parts = [];
+        for (let node = this; node; node = node.#parent) {
+            parts.unshift(node.#name);
+        }
+        return parts.join(' ');
     }
 }
 
-function createMainCommandMounter(create, handle) {
-    return (program, opts) => {
-        const command = create(handle);
-        if (command.name().length <= 0) {
-            command.name('__main__');
-        }
-        program.addCommand(command, { ...opts, isDefault: true });
-    };
-}
-function createMainCommandExecutor(create, handle) {
-    return (args) => {
-        return new Promise(resolve => {
-            const wrappedHandler = async (options) => {
-                await handle(options);
-                resolve();
-            };
-            const command = create(wrappedHandler);
-            command.parse(args);
+class CompletionCommand extends Command {
+    constructor(root, config) {
+        const name = config.name ?? 'completion';
+        const paths = config.paths;
+        super({
+            name,
+            description: 'Generate shell completion script',
         });
-    };
-}
-
-class SubCommand {
-    mount(parentCommand, opts) {
-        const processor = this;
-        const command = this.command(processor);
-        parentCommand.addCommand(command, opts);
-    }
-    execute(parentCommand, rawArgs) {
-        return new Promise((resolve, reject) => {
-            const processor = {
-                process: async (args, options) => {
-                    try {
-                        await this.process(args, options);
-                        resolve();
-                    }
-                    catch (error) {
-                        reject(error);
-                    }
-                },
-            };
-            const command = this.command(processor);
-            parentCommand.addCommand(command);
-            parentCommand.parse(rawArgs);
+        this.option({
+            long: 'bash',
+            type: 'boolean',
+            description: 'Generate Bash completion script',
+        })
+            .option({
+            long: 'fish',
+            type: 'boolean',
+            description: 'Generate Fish completion script',
+        })
+            .option({
+            long: 'pwsh',
+            type: 'boolean',
+            description: 'Generate PowerShell completion script',
+        })
+            .option({
+            long: 'write',
+            short: 'w',
+            type: 'string',
+            description: 'Write to file (default path if no value given)',
+            resolver: argv => resolveOptionalStringOption(argv, 'write', 'w'),
+        })
+            .action(({ opts }) => {
+            const meta = root.getCompletionMeta();
+            const programName = root.name;
+            const selectedShells = [
+                opts['bash'] && 'bash',
+                opts['fish'] && 'fish',
+                opts['pwsh'] && 'pwsh',
+            ].filter(Boolean);
+            if (selectedShells.length === 0) {
+                console.error('Please specify a shell: --bash, --fish, or --pwsh');
+                process.exit(1);
+                return;
+            }
+            if (selectedShells.length > 1) {
+                console.error('Please specify only one shell option');
+                process.exit(1);
+                return;
+            }
+            const shell = selectedShells[0];
+            let script;
+            switch (shell) {
+                case 'bash':
+                    script = new BashCompletion(meta, programName).generate();
+                    break;
+                case 'fish':
+                    script = new FishCompletion(meta, programName).generate();
+                    break;
+                case 'pwsh':
+                    script = new PwshCompletion(meta, programName).generate();
+                    break;
+            }
+            const writeOpt = opts['write'];
+            if (writeOpt !== undefined) {
+                const filePath = typeof writeOpt === 'string' && writeOpt !== '' ? writeOpt : paths[shell];
+                const expandedPath = expandHome(filePath);
+                const dir = path.dirname(expandedPath);
+                if (!fs.existsSync(dir)) {
+                    fs.mkdirSync(dir, { recursive: true });
+                }
+                fs.writeFileSync(expandedPath, script, 'utf-8');
+                console.log(`Completion script written to: ${expandedPath}`);
+            }
+            else {
+                console.log(script);
+            }
         });
     }
-    async process(args, options) {
-        const processor = await this.resolveProcessor(args, options);
-        await processor.process(args, options);
+}
+function expandHome(filepath) {
+    if (filepath.startsWith('~/') || filepath === '~') {
+        const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
+        return filepath.replace(/^~/, home);
     }
+    return filepath;
 }
-
-function createTopCommand(commandName, version) {
-    const program = new Command();
-    program
-        .storeOptionsAsProperties(false)
-        .version(version)
-        .name(commandName)
-        .option('--log-encoding <encoding>', 'Encoding of log file.')
-        .option('--log-filepath <filepath>', 'Path which the log file is located.')
-        .option('--log-level <level>', 'Log level.')
-        .option('--log-name <name>', 'Logger name.')
-        .option('--log-mode <normal|loose>', 'Log format mode.')
-        .option('--log-flight <[[no-]<date|title|colorful|inline>]>', 'Enable / disable logger flights.', (val, acc) => acc.concat(val), [])
-        .option('-c, --config-path, --configPath <configPath>', 'config filepaths', (val, acc) => acc.concat(val), [])
-        .option('--parastic-config-path, --parasticConfigFilepath <parasticConfigFilepath>', 'parastic config filepath')
-        .option('--parastic-config-entry, --parasticConfigEntry <parasticConfigEntry>', 'parastic config filepath')
-        .option('--workspace <workspace>', 'The root dir to locate the config files and resolve relative paths');
-    return program;
+function resolveOptionalStringOption(argv, longName, shortName) {
+    const remaining = [];
+    let value;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith(`--${longName}=`)) {
+            value = arg.slice(`--${longName}=`.length);
+            continue;
+        }
+        if (arg === `--${longName}`) {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                value = next;
+                i += 1;
+            }
+            else {
+                value = '';
+            }
+            continue;
+        }
+        if (arg.startsWith(`-${shortName}=`)) {
+            value = arg.slice(`-${shortName}=`.length);
+            continue;
+        }
+        if (arg === `-${shortName}`) {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('-')) {
+                value = next;
+                i += 1;
+            }
+            else {
+                value = '';
+            }
+            continue;
+        }
+        remaining.push(arg);
+    }
+    return { value, remaining };
 }
-
-const hasGitInstalled = () => commandExistsSync('git');
-async function installDependencies(params) {
-    const { cwd, plopBypass, reporter } = params;
-    const hasYarnInstalled = commandExistsSync('yarn');
-    if (!hasYarnInstalled) {
-        const hasNpmInstalled = commandExistsSync('npm');
-        if (!hasNpmInstalled)
-            return;
-    }
-    let npmScript;
-    if (plopBypass.length > 0) {
-        npmScript = plopBypass.shift();
-    }
-    else {
-        npmScript = await select({
-            message: 'npm or yarn?',
-            choices: ['npm', 'yarn', 'skip'],
-            default: hasYarnInstalled ? 'yarn' : 'npm',
-        });
+class BashCompletion {
+    #meta;
+    #programName;
+    constructor(meta, programName) {
+        this.#meta = meta;
+        this.#programName = programName;
+    }
+    generate() {
+        const funcName = `_${this.#sanitizeName(this.#programName)}_completions`;
+        const lines = [
+            `# Bash completion for ${this.#programName}`,
+            '# Generated by @guanghechen/commander',
+            '',
+            `${funcName}() {`,
+            '  local cur prev words cword',
+            '  _init_completion || return',
+            '',
+            ...this.#generateCommandCase(this.#meta, 1),
+            '',
+            '  COMPREPLY=($(compgen -W "$opts" -- "$cur"))',
+            '}',
+            '',
+            `complete -F ${funcName} ${this.#programName}`,
+            '',
+        ];
+        return lines.join('\n');
+    }
+    #generateCommandCase(cmd, depth) {
+        const indent = '  '.repeat(depth);
+        const lines = [];
+        const optParts = [];
+        for (const opt of cmd.options) {
+            if (opt.short)
+                optParts.push(`-${opt.short}`);
+            optParts.push(`--${opt.long}`);
+            if (!opt.takesValue) {
+                optParts.push(`--no-${opt.long}`);
+            }
+        }
+        const subParts = cmd.subcommands.flatMap(sub => [sub.name, ...sub.aliases]);
+        const allOpts = [...optParts, ...subParts].join(' ');
+        if (cmd.subcommands.length > 0) {
+            lines.push(`${indent}case "\${words[${depth}]}" in`);
+            for (const sub of cmd.subcommands) {
+                const pattern = [sub.name, ...sub.aliases].join('|');
+                lines.push(`${indent}  ${pattern})`);
+                lines.push(...this.#generateCommandCase(sub, depth + 1));
+                lines.push(`${indent}    ;;`);
+            }
+            lines.push(`${indent}  *)`);
+            lines.push(`${indent}    opts="${allOpts}"`);
+            lines.push(`${indent}    ;;`);
+            lines.push(`${indent}esac`);
+        }
+        else {
+            lines.push(`${indent}opts="${allOpts}"`);
+        }
+        return lines;
+    }
+    #sanitizeName(name) {
+        return name.replace(/[^a-zA-Z0-9]/g, '_');
+    }
+}
+class FishCompletion {
+    #meta;
+    #programName;
+    constructor(meta, programName) {
+        this.#meta = meta;
+        this.#programName = programName;
+    }
+    generate() {
+        const lines = [
+            `# Fish completion for ${this.#programName}`,
+            '# Generated by @guanghechen/commander',
+            '',
+            ...this.#generateCommandCompletions(this.#meta, []),
+            '',
+        ];
+        return lines.join('\n');
+    }
+    #generateCommandCompletions(cmd, parentPath) {
+        const lines = [];
+        const isRoot = parentPath.length === 0;
+        const condition = this.#buildCondition(parentPath);
+        for (const opt of cmd.options) {
+            let line = `complete -c ${this.#programName}`;
+            if (condition)
+                line += ` -n '${condition}'`;
+            if (opt.short)
+                line += ` -s ${opt.short}`;
+            line += ` -l ${opt.long}`;
+            line += ` -d '${this.#escape(opt.description)}'`;
+            if (opt.choices && opt.choices.length > 0) {
+                line += ` -xa '${opt.choices.join(' ')}'`;
+            }
+            lines.push(line);
+            if (!opt.takesValue) {
+                let noLine = `complete -c ${this.#programName}`;
+                if (condition)
+                    noLine += ` -n '${condition}'`;
+                noLine += ` -l no-${opt.long}`;
+                noLine += ` -d '${this.#escape(opt.description)}'`;
+                lines.push(noLine);
+            }
+        }
+        for (const sub of cmd.subcommands) {
+            let line = `complete -c ${this.#programName}`;
+            if (isRoot) {
+                line += ' -n __fish_use_subcommand';
+            }
+            else if (condition) {
+                line += ` -n '${condition}; and not __fish_seen_subcommand_from ${this.#getSubcommandNames(cmd).join(' ')}'`;
+            }
+            line += ` -a ${sub.name}`;
+            line += ` -d '${this.#escape(sub.description)}'`;
+            lines.push(line);
+            for (const alias of sub.aliases) {
+                let aliasLine = `complete -c ${this.#programName}`;
+                if (isRoot) {
+                    aliasLine += ' -n __fish_use_subcommand';
+                }
+                else if (condition) {
+                    aliasLine += ` -n '${condition}; and not __fish_seen_subcommand_from ${this.#getSubcommandNames(cmd).join(' ')}'`;
+                }
+                aliasLine += ` -a ${alias}`;
+                aliasLine += ` -d 'Alias for ${sub.name}'`;
+                lines.push(aliasLine);
+            }
+            const newPath = [...parentPath, sub.name];
+            lines.push(...this.#generateCommandCompletions(sub, newPath));
+        }
+        return lines;
+    }
+    #buildCondition(path) {
+        if (path.length === 0)
+            return '';
+        return `__fish_seen_subcommand_from ${path[path.length - 1]}`;
+    }
+    #getSubcommandNames(cmd) {
+        return cmd.subcommands.flatMap(sub => [sub.name, ...sub.aliases]);
+    }
+    #escape(s) {
+        return s.replace(/'/g, "\\'");
+    }
+}
+class PwshCompletion {
+    #meta;
+    #programName;
+    constructor(meta, programName) {
+        this.#meta = meta;
+        this.#programName = programName;
+    }
+    generate() {
+        const lines = [
+            `# PowerShell completion for ${this.#programName}`,
+            '# Generated by @guanghechen/commander',
+            '',
+            `Register-ArgumentCompleter -Native -CommandName ${this.#programName} -ScriptBlock {`,
+            '  param($wordToComplete, $commandAst, $cursorPosition)',
+            '',
+            '  $commands = @{',
+            this.#generateCommandHash(this.#meta, '    '),
+            '  }',
+            '',
+            '  $words = $commandAst.CommandElements | ForEach-Object { $_.ToString() }',
+            '  $current = $wordToComplete',
+            '',
+            '  # Find current command context',
+            '  $cmd = $commands',
+            '  foreach ($word in $words[1..($words.Count - 1)]) {',
+            '    if ($word.StartsWith("-")) { continue }',
+            '    if ($cmd.subcommands -and $cmd.subcommands.ContainsKey($word)) {',
+            '      $cmd = $cmd.subcommands[$word]',
+            '    }',
+            '  }',
+            '',
+            '  # Generate completions',
+            '  $completions = @()',
+            '',
+            '  # Options',
+            '  if ($current.StartsWith("-")) {',
+            '    foreach ($opt in $cmd.options) {',
+            '      if ("--$($opt.long)" -like "$current*") {',
+            '        $completions += [System.Management.Automation.CompletionResult]::new(',
+            '          "--$($opt.long)",',
+            '          $opt.long,',
+            '          "ParameterName",',
+            '          $opt.description',
+            '        )',
+            '      }',
+            '      if ($opt.isBoolean -and "--no-$($opt.long)" -like "$current*") {',
+            '        $completions += [System.Management.Automation.CompletionResult]::new(',
+            '          "--no-$($opt.long)",',
+            '          "no-$($opt.long)",',
+            '          "ParameterName",',
+            '          $opt.description',
+            '        )',
+            '      }',
+            '      if ($opt.short -and "-$($opt.short)" -like "$current*") {',
+            '        $completions += [System.Management.Automation.CompletionResult]::new(',
+            '          "-$($opt.short)",',
+            '          $opt.short,',
+            '          "ParameterName",',
+            '          $opt.description',
+            '        )',
+            '      }',
+            '    }',
+            '  }',
+            '',
+            '  # Subcommands',
+            '  if ($cmd.subcommands) {',
+            '    foreach ($sub in $cmd.subcommands.Keys) {',
+            '      if ($sub -like "$current*") {',
+            '        $completions += [System.Management.Automation.CompletionResult]::new(',
+            '          $sub,',
+            '          $sub,',
+            '          "Command",',
+            '          $cmd.subcommands[$sub].description',
+            '        )',
+            '      }',
+            '    }',
+            '  }',
+            '',
+            '  return $completions',
+            '}',
+            '',
+        ];
+        return lines.join('\n');
+    }
+    #generateCommandHash(cmd, indent) {
+        const lines = [];
+        lines.push(`${indent}description = '${this.#escape(cmd.description)}'`);
+        lines.push(`${indent}options = @(`);
+        for (const opt of cmd.options) {
+            lines.push(`${indent}  @{`);
+            if (opt.short)
+                lines.push(`${indent}    short = '${opt.short}'`);
+            lines.push(`${indent}    long = '${opt.long}'`);
+            lines.push(`${indent}    description = '${this.#escape(opt.description)}'`);
+            lines.push(`${indent}    isBoolean = $${!opt.takesValue}`);
+            if (opt.choices) {
+                lines.push(`${indent}    choices = @('${opt.choices.join("', '")}')`);
+            }
+            lines.push(`${indent}  }`);
+        }
+        lines.push(`${indent})`);
+        if (cmd.subcommands.length > 0) {
+            lines.push(`${indent}subcommands = @{`);
+            for (const sub of cmd.subcommands) {
+                lines.push(`${indent}  '${sub.name}' = @{`);
+                lines.push(this.#generateCommandHash(sub, `${indent}    `));
+                lines.push(`${indent}  }`);
+                for (const alias of sub.aliases) {
+                    lines.push(`${indent}  '${alias}' = @{`);
+                    lines.push(this.#generateCommandHash(sub, `${indent}    `));
+                    lines.push(`${indent}  }`);
+                }
+            }
+            lines.push(`${indent}}`);
+        }
+        return lines.join('\n');
+    }
+    #escape(s) {
+        return s.replace(/'/g, "''");
     }
-    reporter?.debug?.('npmScript:', npmScript);
-    if (npmScript === 'skip')
-        return;
-    await safeExec({ from: 'installDependencies', cmd: npmScript, args: ['install'], cwd, reporter });
 }
 
-export { Command, SubCommand, createMainCommandExecutor, createMainCommandMounter, createTopCommand, hasGitInstalled, installDependencies };
+export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion };