@guanghechen/commander 2.0.1 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. See
+[Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+## 3.0.0 (2026-02-08)
+
+### BREAKING CHANGES
+
+- Change subcommand registration API to `subcommand(name, cmd)`
+
+## 2.1.0 (2026-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;
@@ -44,32 +67,25 @@ class Command {
     #name;
     #description;
     #version;
-    #aliases;
+    #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
     #action;
-    #parent;
     constructor(config) {
-        this.#name = config.name;
+        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;
+        return this.#version;
     }
     get options() {
         return [...this.#options];
@@ -92,33 +108,43 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+    subcommand(name, cmd) {
+        if (this.#helpSubcommandEnabled && name === 'help') {
+            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
+        }
+        const existing = this.#subcommands.find(e => e.command === cmd);
+        if (existing) {
+            existing.aliases.push(name);
+        }
+        else {
+            cmd.#name = name;
+            this.#subcommands.push({ name, aliases: [], command: cmd });
+        }
         return this;
     }
     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 +203,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,15 +303,19 @@ class Command {
             }
             lines.push('');
         }
+        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommands.length > 0;
         if (this.#subcommands.length > 0) {
             lines.push('Commands:');
             const cmdLines = [];
-            for (const sub of this.#subcommands) {
-                let name = sub.#name;
-                if (sub.#aliases.length > 0) {
-                    name += `, ${sub.#aliases.join(', ')}`;
+            if (showHelpSubcommand) {
+                cmdLines.push({ name: 'help', desc: 'Show help for a command' });
+            }
+            for (const entry of this.#subcommands) {
+                let name = entry.name;
+                if (entry.aliases.length > 0) {
+                    name += `, ${entry.aliases.join(', ')}`;
                 }
-                cmdLines.push({ name, desc: sub.#description });
+                cmdLines.push({ name, desc: entry.command.#description });
             }
             const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
             for (const { name, desc } of cmdLines) {
@@ -320,11 +342,33 @@ class Command {
         return {
             name: this.#name,
             description: this.#description,
-            aliases: this.#aliases,
+            aliases: [],
             options,
-            subcommands: this.#subcommands.map(sub => sub.getCompletionMeta()),
+            subcommands: this.#subcommands.map(entry => {
+                const subMeta = entry.command.getCompletionMeta();
+                return {
+                    ...subMeta,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                };
+            }),
         };
     }
+    #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 entry = this.#subcommands.find(e => e.name === subName || e.aliases.includes(subName));
+        if (entry) {
+            return [subName, '--help', ...argv.slice(2)];
+        }
+        return argv;
+    }
     #route(argv) {
         let current = this;
         let idx = 0;
@@ -332,10 +376,10 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const sub = current.#subcommands.find(c => c.#name === token || c.#aliases.includes(token));
-            if (!sub)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
             idx += 1;
         }
         return { command: current, remaining: argv.slice(idx) };
@@ -352,17 +396,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 +462,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 +481,6 @@ class Command {
                     parsedValue = num;
                     break;
                 }
-                default:
-                    parsedValue = rawValue;
             }
         }
         if (type === 'string[]' || type === 'number[]') {
@@ -462,33 +493,17 @@ class Command {
         }
     }
     #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'));
+        const hasUserHelp = this.#options.some(o => o.long === 'help');
+        const hasUserVersion = this.#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);
-            }
+        for (const opt of this.#options) {
+            optionMap.set(opt.long, opt);
         }
         return Array.from(optionMap.values());
     }
@@ -533,20 +548,109 @@ class Command {
     #isBuiltinOption(opt) {
         return opt === BUILTIN_HELP_OPTION || opt === BUILTIN_VERSION_OPTION;
     }
-    #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
+    #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 parts.join(' ');
+        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() {
+        return this.#name;
     }
 }
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config?.name ?? 'completion';
+        const paths = config.paths;
+        const programName = config.programName ?? root.name;
         super({
-            name,
             description: 'Generate shell completion script',
         });
         this.option({
@@ -563,10 +667,16 @@ 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();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',
@@ -575,25 +685,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;
@@ -42,32 +45,25 @@ class Command {
     #name;
     #description;
     #version;
-    #aliases;
+    #helpSubcommandEnabled;
     #options = [];
     #arguments = [];
     #subcommands = [];
     #action;
-    #parent;
     constructor(config) {
-        this.#name = config.name;
+        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;
+        return this.#version;
     }
     get options() {
         return [...this.#options];
@@ -90,33 +86,43 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+    subcommand(name, cmd) {
+        if (this.#helpSubcommandEnabled && name === 'help') {
+            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
+        }
+        const existing = this.#subcommands.find(e => e.command === cmd);
+        if (existing) {
+            existing.aliases.push(name);
+        }
+        else {
+            cmd.#name = name;
+            this.#subcommands.push({ name, aliases: [], command: cmd });
+        }
         return this;
     }
     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 +181,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,15 +281,19 @@ class Command {
             }
             lines.push('');
         }
+        const showHelpSubcommand = this.#helpSubcommandEnabled && this.#subcommands.length > 0;
         if (this.#subcommands.length > 0) {
             lines.push('Commands:');
             const cmdLines = [];
-            for (const sub of this.#subcommands) {
-                let name = sub.#name;
-                if (sub.#aliases.length > 0) {
-                    name += `, ${sub.#aliases.join(', ')}`;
+            if (showHelpSubcommand) {
+                cmdLines.push({ name: 'help', desc: 'Show help for a command' });
+            }
+            for (const entry of this.#subcommands) {
+                let name = entry.name;
+                if (entry.aliases.length > 0) {
+                    name += `, ${entry.aliases.join(', ')}`;
                 }
-                cmdLines.push({ name, desc: sub.#description });
+                cmdLines.push({ name, desc: entry.command.#description });
             }
             const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
             for (const { name, desc } of cmdLines) {
@@ -318,11 +320,33 @@ class Command {
         return {
             name: this.#name,
             description: this.#description,
-            aliases: this.#aliases,
+            aliases: [],
             options,
-            subcommands: this.#subcommands.map(sub => sub.getCompletionMeta()),
+            subcommands: this.#subcommands.map(entry => {
+                const subMeta = entry.command.getCompletionMeta();
+                return {
+                    ...subMeta,
+                    name: entry.name,
+                    aliases: entry.aliases,
+                };
+            }),
         };
     }
+    #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 entry = this.#subcommands.find(e => e.name === subName || e.aliases.includes(subName));
+        if (entry) {
+            return [subName, '--help', ...argv.slice(2)];
+        }
+        return argv;
+    }
     #route(argv) {
         let current = this;
         let idx = 0;
@@ -330,10 +354,10 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const sub = current.#subcommands.find(c => c.#name === token || c.#aliases.includes(token));
-            if (!sub)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
             idx += 1;
         }
         return { command: current, remaining: argv.slice(idx) };
@@ -350,17 +374,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 +440,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 +459,6 @@ class Command {
                     parsedValue = num;
                     break;
                 }
-                default:
-                    parsedValue = rawValue;
             }
         }
         if (type === 'string[]' || type === 'number[]') {
@@ -460,33 +471,17 @@ class Command {
         }
     }
     #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'));
+        const hasUserHelp = this.#options.some(o => o.long === 'help');
+        const hasUserVersion = this.#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);
-            }
+        for (const opt of this.#options) {
+            optionMap.set(opt.long, opt);
         }
         return Array.from(optionMap.values());
     }
@@ -531,20 +526,109 @@ class Command {
     #isBuiltinOption(opt) {
         return opt === BUILTIN_HELP_OPTION || opt === BUILTIN_VERSION_OPTION;
     }
-    #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
+    #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 parts.join(' ');
+        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() {
+        return this.#name;
     }
 }
 
 class CompletionCommand extends Command {
     constructor(root, config) {
-        const name = config?.name ?? 'completion';
+        const paths = config.paths;
+        const programName = config.programName ?? root.name;
         super({
-            name,
             description: 'Generate shell completion script',
         });
         this.option({
@@ -561,10 +645,16 @@ 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();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',
@@ -573,25 +663,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

@@ -57,22 +57,20 @@ interface IArgument {
 }
 /** Command configuration */
 interface ICommandConfig {
-    /** Command name (used for routing) */
-    name: string;
-    /** Command aliases */
-    aliases?: string[];
+    /** Command name (only effective for root command) */
+    name?: string;
     /** Command description */
     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 {
     readonly name: string;
-    readonly aliases: string[];
     readonly description: string;
     readonly version: string | undefined;
-    readonly parent: ICommand | undefined;
     readonly options: IOption[];
     readonly arguments: IArgument[];
 }
@@ -142,10 +140,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;
+    /** Program name for completion scripts (defaults to root.name) */
+    programName?: string;
+    /** Default completion file paths for each shell (required for --write support) */
+    paths: ICompletionPaths;
 }
 
 /**
@@ -154,20 +163,18 @@ interface ICompletionCommandConfig {
  * @module @guanghechen/commander
  */
 
-declare class Command {
+declare class Command implements ICommand {
     #private;
     constructor(config: ICommandConfig);
     get name(): string;
-    get aliases(): string[];
     get description(): string;
     get version(): string | undefined;
-    get parent(): Command | undefined;
     get options(): IOption[];
     get arguments(): IArgument[];
     option(opt: IOption): this;
     argument(arg: IArgument): this;
     action(fn: IAction): this;
-    subcommand(cmd: Command): this;
+    subcommand(name: string, cmd: Command): this;
     run(params: IRunParams): Promise<void>;
     parse(argv: string[]): IParseResult;
     formatHelp(): string;
@@ -186,16 +193,22 @@ declare class Command {
  * @example
  * ```typescript
  * const root = new Command({ name: 'mycli', description: 'My CLI' })
- * root.subcommand(new CompletionCommand(root))
+ * root.subcommand('completion', 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 +227,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": "3.0.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",