@guanghechen/commander 2.1.0 → 3.1.0

package/CHANGELOG.md

@@ -1,9 +1,24 @@
 # Change Log
 
+## 3.1.0
+
+### Minor Changes
+
+- Implement option bubbling with shift/apply flow
+  - Add `shift()` method for bottom-up option consumption (leaf → root)
+  - Refactor `run()` with new flow: route → split → shift → apply → action
+  - Add `UnexpectedArgument` error type for positional args before `--`
+
 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)
+## 3.0.0 (2026-02-08)
+
+### BREAKING CHANGES
+
+- Change subcommand registration API to `subcommand(name, cmd)`
+
+## 2.1.0 (2026-02-08)
 
 ### Features
 
@@ -30,4 +45,3 @@ All notable changes to this project will be documented in this file. See
 ### Features
 
 - Initial stable release: A minimal, type-safe command-line interface builder with fluent API
-

package/lib/cjs/index.cjs

@@ -67,34 +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];
@@ -117,46 +108,57 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        if (this.#helpSubcommandEnabled && (cmd.#name === 'help' || cmd.#aliases.includes('help'))) {
+    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());
         }
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+        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 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());
+            const { chain, remaining } = this.#routeChain(processedArgv);
+            const leafCommand = chain[chain.length - 1];
+            const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
+            const leafOptions = leafCommand.#getMergedOptions();
+            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
+            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
+            if (!hasUserHelp && leafCommand.#hasHelpFlag(optionTokens, leafOptions)) {
+                console.log(leafCommand.formatHelp());
                 return;
             }
-            if (!hasUserVersion && command.#hasVersionFlag(remaining, allOptions)) {
-                console.log(command.version ?? 'unknown');
+            if (!hasUserVersion && leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
+                console.log(leafCommand.version ?? 'unknown');
                 return;
             }
-            const { opts, args } = command.parse(remaining);
+            const optsMap = this.#shiftChain(chain, optionTokens);
             const ctx = {
-                cmd: command,
+                cmd: leafCommand,
                 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) {
+            this.#applyChain(chain, optsMap, ctx);
+            const mergedOpts = this.#mergeOpts(chain, optsMap);
+            const args = restArgs;
+            const requiredArgs = leafCommand.#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(', ')}`, leafCommand.#getCommandPath());
+            }
+            const actionParams = { ctx, opts: mergedOpts, args };
+            if (leafCommand.#action) {
                 try {
-                    await command.#action(actionParams);
+                    await leafCommand.#action(actionParams);
                 }
                 catch (err) {
                     if (err instanceof Error) {
@@ -168,11 +170,11 @@ class Command {
                     process.exit(1);
                 }
             }
-            else if (command.#subcommands.length > 0) {
-                console.log(command.formatHelp());
+            else if (leafCommand.#subcommands.length > 0) {
+                console.log(leafCommand.formatHelp());
             }
             else {
-                throw new CommanderError('ConfigurationError', `no action defined for command "${command.#getCommandPath()}"`, command.#getCommandPath());
+                throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
             }
         }
         catch (err) {
@@ -250,6 +252,82 @@ class Command {
         }
         return { opts, args };
     }
+    shift(tokens) {
+        return this.#shiftWithShadowed(tokens, new Set());
+    }
+    #shiftWithShadowed(tokens, shadowed) {
+        const allDirectOptions = this.#getMergedOptions();
+        const directOptions = allDirectOptions.filter(o => !shadowed.has(o.long));
+        const opts = {};
+        for (const opt of directOptions) {
+            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 = [...tokens];
+        const resolverOptions = directOptions.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(directOptions, true);
+        const normalizedTokens = this.#normalizeArgv(remaining, booleanOptions);
+        const finalRemaining = [];
+        let i = 0;
+        while (i < normalizedTokens.length) {
+            const token = normalizedTokens[i];
+            if (token.startsWith('--')) {
+                const consumed = this.#tryConsumeLongOption(normalizedTokens, i, optionByLong, opts);
+                if (consumed > 0) {
+                    i += consumed;
+                    continue;
+                }
+                finalRemaining.push(token);
+                i += 1;
+                continue;
+            }
+            if (token.startsWith('-') && token.length > 1) {
+                const result = this.#tryConsumeShortOption(normalizedTokens, i, optionByShort, opts);
+                if (result.consumed) {
+                    i = result.nextIdx;
+                    if (result.remainingToken) {
+                        finalRemaining.push(result.remainingToken);
+                    }
+                    continue;
+                }
+                finalRemaining.push(token);
+                i += 1;
+                continue;
+            }
+            finalRemaining.push(token);
+            i += 1;
+        }
+        for (const opt of directOptions) {
+            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 directOptions) {
+            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());
+                    }
+                }
+            }
+        }
+        return { opts, remaining: finalRemaining };
+    }
     formatHelp() {
         const lines = [];
         const allOptions = this.#getMergedOptions();
@@ -313,12 +391,12 @@ class Command {
             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(', ')}`;
+            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) {
@@ -345,9 +423,16 @@ 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) {
@@ -359,26 +444,80 @@ class Command {
             return ['--help'];
         }
         const subName = argv[1];
-        const sub = this.#subcommands.find(c => c.#name === subName || c.#aliases.includes(subName));
-        if (sub) {
+        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) {
+    #routeChain(argv) {
+        const chain = [this];
         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)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
+            chain.push(current);
             idx += 1;
         }
-        return { command: current, remaining: argv.slice(idx) };
+        return { chain, remaining: argv.slice(idx) };
+    }
+    #splitAtDoubleDash(tokens) {
+        const ddIdx = tokens.indexOf('--');
+        if (ddIdx === -1) {
+            return { optionTokens: tokens, restArgs: [] };
+        }
+        return {
+            optionTokens: tokens.slice(0, ddIdx),
+            restArgs: tokens.slice(ddIdx + 1),
+        };
+    }
+    #shiftChain(chain, tokens) {
+        const optsMap = new Map();
+        let remaining = [...tokens];
+        const shadowed = new Set();
+        for (let i = chain.length - 1; i >= 0; i--) {
+            const cmd = chain[i];
+            const result = cmd.#shiftWithShadowed(remaining, shadowed);
+            optsMap.set(cmd, result.opts);
+            remaining = result.remaining;
+            for (const opt of cmd.#options) {
+                shadowed.add(opt.long);
+            }
+        }
+        if (remaining.length > 0) {
+            const leafCommand = chain[chain.length - 1];
+            const firstToken = remaining[0];
+            if (firstToken.startsWith('-')) {
+                throw new CommanderError('UnknownOption', `unknown option "${firstToken}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+            }
+            else {
+                throw new CommanderError('UnexpectedArgument', `unexpected argument "${firstToken}". Positional arguments must come after "--"`, leafCommand.#getCommandPath());
+            }
+        }
+        return optsMap;
+    }
+    #applyChain(chain, optsMap, ctx) {
+        for (const cmd of chain) {
+            const opts = optsMap.get(cmd) ?? {};
+            for (const opt of cmd.#getMergedOptions()) {
+                if (opt.apply && opts[opt.long] !== undefined) {
+                    opt.apply(opts[opt.long], ctx);
+                }
+            }
+        }
+    }
+    #mergeOpts(chain, optsMap) {
+        const merged = {};
+        for (const cmd of chain) {
+            Object.assign(merged, optsMap.get(cmd) ?? {});
+        }
+        return merged;
     }
     #parseLongOption(argv, idx, optionByLong, opts) {
         const token = argv[idx];
@@ -489,33 +628,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());
     }
@@ -557,9 +680,6 @@ 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();
@@ -654,20 +774,109 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
+        return this.#name;
+    }
+    #tryConsumeLongOption(tokens, idx, optionByLong, opts) {
+        const token = tokens[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) {
+            return 0;
+        }
+        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 {
+                opts[optName] = true;
+            }
+            return 1;
+        }
+        let value;
+        let consumed = 1;
+        if (inlineValue !== undefined) {
+            value = inlineValue;
+        }
+        else if (idx + 1 < tokens.length) {
+            value = tokens[idx + 1];
+            consumed = 2;
+        }
+        else {
+            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
+        }
+        this.#applyValue(opt, value, opts);
+        return consumed;
+    }
+    #tryConsumeShortOption(tokens, idx, optionByShort, opts) {
+        const token = tokens[idx];
+        if (token.includes('=')) {
+            const firstFlag = token[1];
+            if (!optionByShort.has(firstFlag)) {
+                return { consumed: false, nextIdx: idx + 1 };
+            }
+            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
+        }
+        const flags = token.slice(1);
+        let j = 0;
+        const consumedFlags = [];
+        const unconsumedFlags = [];
+        let nextIdx = idx + 1;
+        while (j < flags.length) {
+            const flag = flags[j];
+            const opt = optionByShort.get(flag);
+            if (!opt) {
+                unconsumedFlags.push(...flags.slice(j).split(''));
+                break;
+            }
+            consumedFlags.push(flag);
+            if (opt.type === 'boolean') {
+                opts[opt.long] = true;
+                j += 1;
+                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 < tokens.length && !tokens[idx + 1].startsWith('-')) {
+                const value = tokens[idx + 1];
+                this.#applyValue(opt, value, opts);
+                nextIdx = idx + 2;
+            }
+            else {
+                throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
+            }
+            j += 1;
+        }
+        if (consumedFlags.length > 0) {
+            const remainingToken = unconsumedFlags.length > 0 ? `-${unconsumedFlags.join('')}` : undefined;
+            return { consumed: true, nextIdx, remainingToken };
         }
-        return parts.join(' ');
+        return { consumed: false, nextIdx: idx + 1 };
     }
 }
 
 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({
@@ -694,7 +903,6 @@ class CompletionCommand extends Command {
         })
             .action(({ opts }) => {
             const meta = root.getCompletionMeta();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',

package/lib/esm/index.mjs

@@ -45,34 +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];
@@ -95,46 +86,57 @@ class Command {
         this.#action = fn;
         return this;
     }
-    subcommand(cmd) {
-        if (this.#helpSubcommandEnabled && (cmd.#name === 'help' || cmd.#aliases.includes('help'))) {
+    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());
         }
-        cmd.#parent = this;
-        this.#subcommands.push(cmd);
+        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 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());
+            const { chain, remaining } = this.#routeChain(processedArgv);
+            const leafCommand = chain[chain.length - 1];
+            const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
+            const leafOptions = leafCommand.#getMergedOptions();
+            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
+            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
+            if (!hasUserHelp && leafCommand.#hasHelpFlag(optionTokens, leafOptions)) {
+                console.log(leafCommand.formatHelp());
                 return;
             }
-            if (!hasUserVersion && command.#hasVersionFlag(remaining, allOptions)) {
-                console.log(command.version ?? 'unknown');
+            if (!hasUserVersion && leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
+                console.log(leafCommand.version ?? 'unknown');
                 return;
             }
-            const { opts, args } = command.parse(remaining);
+            const optsMap = this.#shiftChain(chain, optionTokens);
             const ctx = {
-                cmd: command,
+                cmd: leafCommand,
                 envs,
                 reporter: reporter ?? new DefaultReporter(),
                 argv,
             };
-            for (const opt of allOptions) {
-                if (opt.apply && opts[opt.long] !== undefined) {
-                    opt.apply(opts[opt.long], ctx);
-                }
+            this.#applyChain(chain, optsMap, ctx);
+            const mergedOpts = this.#mergeOpts(chain, optsMap);
+            const args = restArgs;
+            const requiredArgs = leafCommand.#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(', ')}`, leafCommand.#getCommandPath());
             }
-            const actionParams = { ctx, opts, args };
-            if (command.#action) {
+            const actionParams = { ctx, opts: mergedOpts, args };
+            if (leafCommand.#action) {
                 try {
-                    await command.#action(actionParams);
+                    await leafCommand.#action(actionParams);
                 }
                 catch (err) {
                     if (err instanceof Error) {
@@ -146,11 +148,11 @@ class Command {
                     process.exit(1);
                 }
             }
-            else if (command.#subcommands.length > 0) {
-                console.log(command.formatHelp());
+            else if (leafCommand.#subcommands.length > 0) {
+                console.log(leafCommand.formatHelp());
             }
             else {
-                throw new CommanderError('ConfigurationError', `no action defined for command "${command.#getCommandPath()}"`, command.#getCommandPath());
+                throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
             }
         }
         catch (err) {
@@ -228,6 +230,82 @@ class Command {
         }
         return { opts, args };
     }
+    shift(tokens) {
+        return this.#shiftWithShadowed(tokens, new Set());
+    }
+    #shiftWithShadowed(tokens, shadowed) {
+        const allDirectOptions = this.#getMergedOptions();
+        const directOptions = allDirectOptions.filter(o => !shadowed.has(o.long));
+        const opts = {};
+        for (const opt of directOptions) {
+            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 = [...tokens];
+        const resolverOptions = directOptions.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(directOptions, true);
+        const normalizedTokens = this.#normalizeArgv(remaining, booleanOptions);
+        const finalRemaining = [];
+        let i = 0;
+        while (i < normalizedTokens.length) {
+            const token = normalizedTokens[i];
+            if (token.startsWith('--')) {
+                const consumed = this.#tryConsumeLongOption(normalizedTokens, i, optionByLong, opts);
+                if (consumed > 0) {
+                    i += consumed;
+                    continue;
+                }
+                finalRemaining.push(token);
+                i += 1;
+                continue;
+            }
+            if (token.startsWith('-') && token.length > 1) {
+                const result = this.#tryConsumeShortOption(normalizedTokens, i, optionByShort, opts);
+                if (result.consumed) {
+                    i = result.nextIdx;
+                    if (result.remainingToken) {
+                        finalRemaining.push(result.remainingToken);
+                    }
+                    continue;
+                }
+                finalRemaining.push(token);
+                i += 1;
+                continue;
+            }
+            finalRemaining.push(token);
+            i += 1;
+        }
+        for (const opt of directOptions) {
+            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 directOptions) {
+            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());
+                    }
+                }
+            }
+        }
+        return { opts, remaining: finalRemaining };
+    }
     formatHelp() {
         const lines = [];
         const allOptions = this.#getMergedOptions();
@@ -291,12 +369,12 @@ class Command {
             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(', ')}`;
+            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) {
@@ -323,9 +401,16 @@ 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) {
@@ -337,26 +422,80 @@ class Command {
             return ['--help'];
         }
         const subName = argv[1];
-        const sub = this.#subcommands.find(c => c.#name === subName || c.#aliases.includes(subName));
-        if (sub) {
+        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) {
+    #routeChain(argv) {
+        const chain = [this];
         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)
+            const entry = current.#subcommands.find(e => e.name === token || e.aliases.includes(token));
+            if (!entry)
                 break;
-            current = sub;
+            current = entry.command;
+            chain.push(current);
             idx += 1;
         }
-        return { command: current, remaining: argv.slice(idx) };
+        return { chain, remaining: argv.slice(idx) };
+    }
+    #splitAtDoubleDash(tokens) {
+        const ddIdx = tokens.indexOf('--');
+        if (ddIdx === -1) {
+            return { optionTokens: tokens, restArgs: [] };
+        }
+        return {
+            optionTokens: tokens.slice(0, ddIdx),
+            restArgs: tokens.slice(ddIdx + 1),
+        };
+    }
+    #shiftChain(chain, tokens) {
+        const optsMap = new Map();
+        let remaining = [...tokens];
+        const shadowed = new Set();
+        for (let i = chain.length - 1; i >= 0; i--) {
+            const cmd = chain[i];
+            const result = cmd.#shiftWithShadowed(remaining, shadowed);
+            optsMap.set(cmd, result.opts);
+            remaining = result.remaining;
+            for (const opt of cmd.#options) {
+                shadowed.add(opt.long);
+            }
+        }
+        if (remaining.length > 0) {
+            const leafCommand = chain[chain.length - 1];
+            const firstToken = remaining[0];
+            if (firstToken.startsWith('-')) {
+                throw new CommanderError('UnknownOption', `unknown option "${firstToken}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+            }
+            else {
+                throw new CommanderError('UnexpectedArgument', `unexpected argument "${firstToken}". Positional arguments must come after "--"`, leafCommand.#getCommandPath());
+            }
+        }
+        return optsMap;
+    }
+    #applyChain(chain, optsMap, ctx) {
+        for (const cmd of chain) {
+            const opts = optsMap.get(cmd) ?? {};
+            for (const opt of cmd.#getMergedOptions()) {
+                if (opt.apply && opts[opt.long] !== undefined) {
+                    opt.apply(opts[opt.long], ctx);
+                }
+            }
+        }
+    }
+    #mergeOpts(chain, optsMap) {
+        const merged = {};
+        for (const cmd of chain) {
+            Object.assign(merged, optsMap.get(cmd) ?? {});
+        }
+        return merged;
     }
     #parseLongOption(argv, idx, optionByLong, opts) {
         const token = argv[idx];
@@ -467,33 +606,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());
     }
@@ -535,9 +658,6 @@ 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();
@@ -632,20 +752,109 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        const parts = [];
-        for (let node = this; node; node = node.#parent) {
-            parts.unshift(node.#name);
+        return this.#name;
+    }
+    #tryConsumeLongOption(tokens, idx, optionByLong, opts) {
+        const token = tokens[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) {
+            return 0;
+        }
+        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 {
+                opts[optName] = true;
+            }
+            return 1;
+        }
+        let value;
+        let consumed = 1;
+        if (inlineValue !== undefined) {
+            value = inlineValue;
+        }
+        else if (idx + 1 < tokens.length) {
+            value = tokens[idx + 1];
+            consumed = 2;
+        }
+        else {
+            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
+        }
+        this.#applyValue(opt, value, opts);
+        return consumed;
+    }
+    #tryConsumeShortOption(tokens, idx, optionByShort, opts) {
+        const token = tokens[idx];
+        if (token.includes('=')) {
+            const firstFlag = token[1];
+            if (!optionByShort.has(firstFlag)) {
+                return { consumed: false, nextIdx: idx + 1 };
+            }
+            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
+        }
+        const flags = token.slice(1);
+        let j = 0;
+        const consumedFlags = [];
+        const unconsumedFlags = [];
+        let nextIdx = idx + 1;
+        while (j < flags.length) {
+            const flag = flags[j];
+            const opt = optionByShort.get(flag);
+            if (!opt) {
+                unconsumedFlags.push(...flags.slice(j).split(''));
+                break;
+            }
+            consumedFlags.push(flag);
+            if (opt.type === 'boolean') {
+                opts[opt.long] = true;
+                j += 1;
+                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 < tokens.length && !tokens[idx + 1].startsWith('-')) {
+                const value = tokens[idx + 1];
+                this.#applyValue(opt, value, opts);
+                nextIdx = idx + 2;
+            }
+            else {
+                throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
+            }
+            j += 1;
+        }
+        if (consumedFlags.length > 0) {
+            const remainingToken = unconsumedFlags.length > 0 ? `-${unconsumedFlags.join('')}` : undefined;
+            return { consumed: true, nextIdx, remainingToken };
         }
-        return parts.join(' ');
+        return { consumed: false, nextIdx: idx + 1 };
     }
 }
 
 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({
@@ -672,7 +881,6 @@ class CompletionCommand extends Command {
         })
             .action(({ opts }) => {
             const meta = root.getCompletionMeta();
-            const programName = root.name;
             const selectedShells = [
                 opts['bash'] && 'bash',
                 opts['fish'] && 'fish',

package/lib/types/index.d.ts

@@ -57,10 +57,8 @@ 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) */
@@ -71,10 +69,8 @@ interface ICommandConfig {
 /** 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[];
 }
@@ -116,8 +112,15 @@ interface IParseResult {
     /** Parsed positional arguments */
     args: string[];
 }
+/** shift() method result */
+interface IShiftResult {
+    /** Options consumed by this command */
+    opts: Record<string, unknown>;
+    /** Tokens not consumed, to be passed to parent */
+    remaining: string[];
+}
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'UnknownOption' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'ConfigurationError';
+type ICommanderErrorKind = 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'ConfigurationError';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;
@@ -155,8 +158,8 @@ interface ICompletionPaths {
 }
 /** 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;
 }
@@ -171,18 +174,21 @@ 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;
+    /**
+     * Shift options from tokens that this command recognizes.
+     * Unrecognized tokens are returned in `remaining` for parent commands.
+     */
+    shift(tokens: string[]): IShiftResult;
     formatHelp(): string;
     getCompletionMeta(): ICompletionMeta;
 }
@@ -199,7 +205,7 @@ declare class Command implements ICommand {
  * @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`,
@@ -233,4 +239,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion };
-export type { IAction, IActionParams, IArgument, IArgumentKind, ICommand, ICommandConfig, ICommandContext, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, 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, IShiftResult };

package/package.json

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