@guanghechen/commander 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. See
+[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 2.1.0 (2025-02-08)
+
+### Features
+
+- Add `--write` option to `CompletionCommand` for direct file output
+- Add `help` subcommand support for commands with subcommands
+- Detect `--help`/`--version` before parsing to avoid required argument errors
+- Add `#normalizeArgv()` preprocessing to simplify `--no-*` option handling
+- Add `implements ICommand` for explicit interface implementation
+
+## 2.0.1 (2025-02-07)
+
+### Documentation
+
+- Update README.md
+
+### Miscellaneous
+
+- Add LICENSE file
+- Clean up build configs and standardize package exports
+- Migrate from lerna to changesets
+
+## 2.0.0 (2025-01-15)
+
+### Features
+
+- Initial stable release: A minimal, type-safe command-line interface builder with fluent API
+

package/lib/cjs/index.cjs

@@ -1,5 +1,28 @@
 'use strict';
 
+var fs = require('node:fs');
+var path = require('node:path');
+
+function _interopNamespaceDefault(e) {
+    var n = Object.create(null);
+    if (e) {
+        Object.keys(e).forEach(function (k) {
+            if (k !== 'default') {
+                var d = Object.getOwnPropertyDescriptor(e, k);
+                Object.defineProperty(n, k, d.get ? d : {
+                    enumerable: true,
+                    get: function () { return e[k]; }
+                });
+            }
+        });
+    }
+    n.default = e;
+    return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
+
 class CommanderError extends Error {
     kind;
     commandPath;
@@ -45,6 +68,7 @@ class Command {
     #description;
     #version;
     #aliases;
+    #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
@@ -55,6 +79,7 @@ class Command {
         this.#description = config.description;
         this.#version = config.version;
         this.#aliases = config.aliases ?? [];
+        this.#helpSubcommandEnabled = config.help ?? false;
     }
     get name() {
         return this.#name;
@@ -93,6 +118,9 @@ class Command {
         return this;
     }
     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;
@@ -100,25 +128,26 @@ class Command {
     async run(params) {
         const { argv, envs, reporter } = params;
         try {
-            const { command, remaining } = this.#route(argv);
-            const { opts, args } = command.parse(remaining);
-            const ctx = {
-                cmd: command,
-                envs,
-                reporter: reporter ?? new DefaultReporter(),
-                argv,
-            };
+            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 && opts['help'] === true) {
+            if (!hasUserHelp && command.#hasHelpFlag(remaining, allOptions)) {
                 console.log(command.formatHelp());
                 return;
             }
-            if (!hasUserVersion && opts['version'] === true) {
+            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);
@@ -177,16 +206,8 @@ class Command {
             opts[opt.long] = result.value;
             remaining = result.remaining;
         }
-        const optionByLong = new Map();
-        const optionByShort = new Map();
-        for (const opt of allOptions) {
-            if (!opt.resolver) {
-                optionByLong.set(opt.long, opt);
-                if (opt.short) {
-                    optionByShort.set(opt.short, opt);
-                }
-            }
-        }
+        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(allOptions, true);
+        remaining = this.#normalizeArgv(remaining, booleanOptions);
         let i = 0;
         while (i < remaining.length) {
             const token = remaining[i];
@@ -285,9 +306,13 @@ class Command {
             }
             lines.push('');
         }
+        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) {
@@ -325,6 +350,21 @@ class Command {
             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;
@@ -352,17 +392,6 @@ class Command {
         else {
             optName = token.slice(2);
         }
-        if (optName.startsWith('no-')) {
-            const actualName = optName.slice(3);
-            const opt = optionByLong.get(actualName);
-            if (opt && opt.type === 'boolean') {
-                if (inlineValue !== undefined) {
-                    throw new CommanderError('InvalidBooleanValue', `"--no-${actualName}" does not accept a value`, this.#getCommandPath());
-                }
-                opts[actualName] = false;
-                return idx + 1;
-            }
-        }
         const opt = optionByLong.get(optName);
         if (!opt) {
             throw new CommanderError('UnknownOption', `unknown option "--${optName}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
@@ -429,7 +458,7 @@ class Command {
     }
     #applyValue(opt, rawValue, opts) {
         const type = opt.type ?? 'string';
-        let parsedValue;
+        let parsedValue = rawValue;
         if (opt.coerce) {
             parsedValue = opt.coerce(rawValue);
         }
@@ -448,8 +477,6 @@ class Command {
                     parsedValue = num;
                     break;
                 }
-                default:
-                    parsedValue = rawValue;
             }
         }
         if (type === 'string[]' || type === 'number[]') {
@@ -533,6 +560,99 @@ class Command {
     #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) {
@@ -544,7 +664,8 @@ class Command {
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config?.name ?? 'completion';
+        const name = config.name ?? 'completion';
+        const paths = config.paths;
         super({
             name,
             description: 'Generate shell completion script',
@@ -563,6 +684,13 @@ class CompletionCommand extends Command {
             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();
@@ -575,25 +703,89 @@ class CompletionCommand extends Command {
             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;
             }
-            switch (selectedShells[0]) {
+            const shell = selectedShells[0];
+            let script;
+            switch (shell) {
                 case 'bash':
-                    console.log(new BashCompletion(meta, programName).generate());
+                    script = new BashCompletion(meta, programName).generate();
                     break;
                 case 'fish':
-                    console.log(new FishCompletion(meta, programName).generate());
+                    script = new FishCompletion(meta, programName).generate();
                     break;
                 case 'pwsh':
-                    console.log(new PwshCompletion(meta, programName).generate());
+                    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__namespace.dirname(expandedPath);
+                if (!fs__namespace.existsSync(dir)) {
+                    fs__namespace.mkdirSync(dir, { recursive: true });
+                }
+                fs__namespace.writeFileSync(expandedPath, script, 'utf-8');
+                console.log(`Completion script written to: ${expandedPath}`);
+            }
+            else {
+                console.log(script);
+            }
         });
     }
 }
+function expandHome(filepath) {
+    if (filepath.startsWith('~/') || filepath === '~') {
+        const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
+        return filepath.replace(/^~/, home);
+    }
+    return filepath;
+}
+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 };
+}
 class BashCompletion {
     #meta;
     #programName;

package/lib/esm/index.mjs

@@ -1,3 +1,6 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
 class CommanderError extends Error {
     kind;
     commandPath;
@@ -43,6 +46,7 @@ class Command {
     #description;
     #version;
     #aliases;
+    #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
@@ -53,6 +57,7 @@ class Command {
         this.#description = config.description;
         this.#version = config.version;
         this.#aliases = config.aliases ?? [];
+        this.#helpSubcommandEnabled = config.help ?? false;
     }
     get name() {
         return this.#name;
@@ -91,6 +96,9 @@ class Command {
         return this;
     }
     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;
@@ -98,25 +106,26 @@ class Command {
     async run(params) {
         const { argv, envs, reporter } = params;
         try {
-            const { command, remaining } = this.#route(argv);
-            const { opts, args } = command.parse(remaining);
-            const ctx = {
-                cmd: command,
-                envs,
-                reporter: reporter ?? new DefaultReporter(),
-                argv,
-            };
+            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 && opts['help'] === true) {
+            if (!hasUserHelp && command.#hasHelpFlag(remaining, allOptions)) {
                 console.log(command.formatHelp());
                 return;
             }
-            if (!hasUserVersion && opts['version'] === true) {
+            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);
@@ -175,16 +184,8 @@ class Command {
             opts[opt.long] = result.value;
             remaining = result.remaining;
         }
-        const optionByLong = new Map();
-        const optionByShort = new Map();
-        for (const opt of allOptions) {
-            if (!opt.resolver) {
-                optionByLong.set(opt.long, opt);
-                if (opt.short) {
-                    optionByShort.set(opt.short, opt);
-                }
-            }
-        }
+        const { optionByLong, optionByShort, booleanOptions } = this.#buildOptionMaps(allOptions, true);
+        remaining = this.#normalizeArgv(remaining, booleanOptions);
         let i = 0;
         while (i < remaining.length) {
             const token = remaining[i];
@@ -283,9 +284,13 @@ class Command {
             }
             lines.push('');
         }
+        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) {
@@ -323,6 +328,21 @@ class Command {
             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;
@@ -350,17 +370,6 @@ class Command {
         else {
             optName = token.slice(2);
         }
-        if (optName.startsWith('no-')) {
-            const actualName = optName.slice(3);
-            const opt = optionByLong.get(actualName);
-            if (opt && opt.type === 'boolean') {
-                if (inlineValue !== undefined) {
-                    throw new CommanderError('InvalidBooleanValue', `"--no-${actualName}" does not accept a value`, this.#getCommandPath());
-                }
-                opts[actualName] = false;
-                return idx + 1;
-            }
-        }
         const opt = optionByLong.get(optName);
         if (!opt) {
             throw new CommanderError('UnknownOption', `unknown option "--${optName}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
@@ -427,7 +436,7 @@ class Command {
     }
     #applyValue(opt, rawValue, opts) {
         const type = opt.type ?? 'string';
-        let parsedValue;
+        let parsedValue = rawValue;
         if (opt.coerce) {
             parsedValue = opt.coerce(rawValue);
         }
@@ -446,8 +455,6 @@ class Command {
                     parsedValue = num;
                     break;
                 }
-                default:
-                    parsedValue = rawValue;
             }
         }
         if (type === 'string[]' || type === 'number[]') {
@@ -531,6 +538,99 @@ class Command {
     #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) {
@@ -542,7 +642,8 @@ class Command {
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config?.name ?? 'completion';
+        const name = config.name ?? 'completion';
+        const paths = config.paths;
         super({
             name,
             description: 'Generate shell completion script',
@@ -561,6 +662,13 @@ class CompletionCommand extends Command {
             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();
@@ -573,25 +681,89 @@ class CompletionCommand extends Command {
             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;
             }
-            switch (selectedShells[0]) {
+            const shell = selectedShells[0];
+            let script;
+            switch (shell) {
                 case 'bash':
-                    console.log(new BashCompletion(meta, programName).generate());
+                    script = new BashCompletion(meta, programName).generate();
                     break;
                 case 'fish':
-                    console.log(new FishCompletion(meta, programName).generate());
+                    script = new FishCompletion(meta, programName).generate();
                     break;
                 case 'pwsh':
-                    console.log(new PwshCompletion(meta, programName).generate());
+                    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);
+            }
         });
     }
 }
+function expandHome(filepath) {
+    if (filepath.startsWith('~/') || filepath === '~') {
+        const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
+        return filepath.replace(/^~/, home);
+    }
+    return filepath;
+}
+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 };
+}
 class BashCompletion {
     #meta;
     #programName;

package/lib/types/index.d.ts

@@ -65,6 +65,8 @@ interface ICommandConfig {
     description: string;
     /** Version (only effective for root command) */
     version?: string;
+    /** Enable built-in "help" subcommand (only effective when command has subcommands) */
+    help?: boolean;
 }
 /** Forward declaration for Command class */
 interface ICommand {
@@ -142,10 +144,21 @@ interface ICompletionMeta {
     options: ICompletionOptionMeta[];
     subcommands: ICompletionMeta[];
 }
+/** Shell completion paths configuration */
+interface ICompletionPaths {
+    /** Bash completion file path (e.g., ~/.local/share/bash-completion/completions/{name}) */
+    bash: string;
+    /** Fish completion file path (e.g., ~/.config/fish/completions/{name}.fish) */
+    fish: string;
+    /** PowerShell completion file path (only ~ expansion supported, not $PROFILE) */
+    pwsh: string;
+}
 /** CompletionCommand configuration */
 interface ICompletionCommandConfig {
     /** Subcommand name, defaults to 'completion' */
     name?: string;
+    /** Default completion file paths for each shell (required for --write support) */
+    paths: ICompletionPaths;
 }
 
 /**
@@ -154,7 +167,7 @@ interface ICompletionCommandConfig {
  * @module @guanghechen/commander
  */
 
-declare class Command {
+declare class Command implements ICommand {
     #private;
     constructor(config: ICommandConfig);
     get name(): string;
@@ -186,16 +199,22 @@ declare class Command {
  * @example
  * ```typescript
  * const root = new Command({ name: 'mycli', description: 'My CLI' })
- * root.subcommand(new CompletionCommand(root))
+ * root.subcommand(new CompletionCommand(root, {
+ *   paths: {
+ *     bash: `~/.local/share/bash-completion/completions/mycli`,
+ *     fish: `~/.config/fish/completions/mycli.fish`,
+ *     pwsh: `~/.config/powershell/Microsoft.PowerShell_profile.ps1`,
+ *   }
+ * }))
  *
  * // Usage:
  * // mycli completion --bash > ~/.local/share/bash-completion/completions/mycli
- * // mycli completion --fish > ~/.config/fish/completions/mycli.fish
- * // mycli completion --pwsh >> $PROFILE
+ * // mycli completion --fish --write  (writes to default path)
+ * // mycli completion --fish --write /custom/path.fish
  * ```
  */
 declare class CompletionCommand extends Command {
-    constructor(root: Command, config?: ICompletionCommandConfig);
+    constructor(root: Command, config: ICompletionCommandConfig);
 }
 declare class BashCompletion {
     #private;
@@ -214,4 +233,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion };
-export type { IAction, IActionParams, IArgument, IArgumentKind, ICommand, ICommandConfig, ICommandContext, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, IOption, IOptionType, IParseResult, IReporter, IRunParams, IShellType };
+export type { IAction, IActionParams, IArgument, IArgumentKind, ICommand, ICommandConfig, ICommandContext, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, IOption, IOptionType, IParseResult, IReporter, IRunParams, IShellType };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanghechen/commander",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",