@guanghechen/commander 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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.
 

package/lib/cjs/index.cjs

@@ -126,34 +126,39 @@ class Command {
         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) {
@@ -165,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) {
@@ -247,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();
@@ -369,7 +450,8 @@ class Command {
         }
         return argv;
     }
-    #route(argv) {
+    #routeChain(argv) {
+        const chain = [this];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
@@ -380,9 +462,62 @@ class Command {
             if (!entry)
                 break;
             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];
@@ -545,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();
@@ -644,6 +776,100 @@ class Command {
     #getCommandPath() {
         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 { consumed: false, nextIdx: idx + 1 };
+    }
 }
 
 class CompletionCommand extends Command {

package/lib/esm/index.mjs

@@ -104,34 +104,39 @@ class Command {
         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) {
@@ -143,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) {
@@ -225,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();
@@ -347,7 +428,8 @@ class Command {
         }
         return argv;
     }
-    #route(argv) {
+    #routeChain(argv) {
+        const chain = [this];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
@@ -358,9 +440,62 @@ class Command {
             if (!entry)
                 break;
             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];
@@ -523,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();
@@ -622,6 +754,100 @@ class Command {
     #getCommandPath() {
         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 { consumed: false, nextIdx: idx + 1 };
+    }
 }
 
 class CompletionCommand extends Command {

package/lib/types/index.d.ts

@@ -112,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;
@@ -177,6 +184,11 @@ declare class Command implements ICommand {
     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;
 }
@@ -227,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": "3.0.0",
+  "version": "3.1.0",
   "description": "A minimal, type-safe command-line interface builder with fluent API",
   "author": {
     "name": "guanghechen",