npm - @guanghechen/commander - Versions diffs - 3.0.0 → 3.2.0 - Mend

@guanghechen/commander 3.0.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,24 @@
 # Change Log
+## 3.2.0
+### Minor Changes
+- Change args from string[] to Record<string, unknown> with type/coerce/default support:
+  - `args` is now `Record<string, unknown>` keyed by argument name
+  - Add `rawArgs: string[]` for original argument strings before type conversion
+  - IArgument now supports `type`, `default`, and `coerce` properties
+  - Add `TooManyArguments` error kind for extra arguments validation
+## 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 CHANGED Viewed

@@ -126,34 +126,34 @@ 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);
-                }
-            }
-            const actionParams = { ctx, opts, args };
-            if (command.#action) {
+            this.#applyChain(chain, optsMap, ctx);
+            const mergedOpts = this.#mergeOpts(chain, optsMap);
+            const { args, rawArgs } = leafCommand.#parseArguments(restArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
+            if (leafCommand.#action) {
                 try {
-                    await command.#action(actionParams);
+                    await leafCommand.#action(actionParams);
                 }
                 catch (err) {
                     if (err instanceof Error) {
@@ -165,11 +165,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) {
@@ -184,7 +184,7 @@ class Command {
     parse(argv) {
         const allOptions = this.#getMergedOptions();
         const opts = {};
-        const args = [];
+        const rawArgs = [];
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -209,7 +209,7 @@ class Command {
         while (i < remaining.length) {
             const token = remaining[i];
             if (token === '--') {
-                args.push(...remaining.slice(i + 1));
+                rawArgs.push(...remaining.slice(i + 1));
                 break;
             }
             if (token.startsWith('--')) {
@@ -220,7 +220,7 @@ class Command {
                 i = this.#parseShortOption(remaining, i, optionByShort, opts);
                 continue;
             }
-            args.push(token);
+            rawArgs.push(token);
             i += 1;
         }
         for (const opt of allOptions) {
@@ -240,12 +240,84 @@ class Command {
                 }
             }
         }
-        const requiredArgs = this.#arguments.filter(a => a.kind === 'required');
-        if (args.length < requiredArgs.length) {
-            const missing = requiredArgs.slice(args.length).map(a => a.name);
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        const { args } = this.#parseArguments(rawArgs);
+        return { opts, args, rawArgs };
+    }
+    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());
+            }
         }
-        return { opts, args };
+        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 = [];
@@ -369,7 +441,8 @@ class Command {
         }
         return argv;
     }
-    #route(argv) {
+    #routeChain(argv) {
+        const chain = [this];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
@@ -380,9 +453,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];
@@ -527,6 +653,9 @@ class Command {
         }
     }
     #validateArgumentConfig(arg) {
+        if (arg.kind === 'required' && arg.default !== undefined) {
+            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot have a default value`, this.#getCommandPath());
+        }
         if (arg.kind === 'variadic') {
             if (this.#arguments.some(a => a.kind === 'variadic')) {
                 throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
@@ -545,8 +674,60 @@ class Command {
             }
         }
     }
-    #isBuiltinOption(opt) {
-        return opt === BUILTIN_HELP_OPTION || opt === BUILTIN_VERSION_OPTION;
+    #parseArguments(rawArgs) {
+        const argumentDefs = this.#arguments;
+        const args = {};
+        const requiredCount = argumentDefs.filter(a => a.kind === 'required').length;
+        if (rawArgs.length < requiredCount) {
+            const missing = argumentDefs
+                .filter(a => a.kind === 'required')
+                .slice(rawArgs.length)
+                .map(a => a.name);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        let index = 0;
+        for (const def of argumentDefs) {
+            if (def.kind === 'variadic') {
+                const rest = rawArgs.slice(index);
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
+            const raw = rawArgs[index];
+            if (raw === undefined) {
+                if (def.kind === 'optional') {
+                    args[def.name] = def.default ?? undefined;
+                    continue;
+                }
+            }
+            else {
+                args[def.name] = this.#convertArgument(def, raw);
+                index += 1;
+            }
+        }
+        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
+        if (!hasVariadic && index < rawArgs.length) {
+            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
+        }
+        return { args, rawArgs };
+    }
+    #convertArgument(def, raw) {
+        if (def.coerce) {
+            try {
+                return def.coerce(raw);
+            }
+            catch {
+                throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+        }
+        if (def.type === 'number') {
+            const n = Number(raw);
+            if (Number.isNaN(n)) {
+                throw new CommanderError('InvalidType', `invalid number "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+            return n;
+        }
+        return raw;
     }
     #buildOptionMaps(allOptions, excludeResolver = false) {
         const optionByLong = new Map();
@@ -644,6 +825,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 CHANGED Viewed

@@ -104,34 +104,34 @@ 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);
-                }
-            }
-            const actionParams = { ctx, opts, args };
-            if (command.#action) {
+            this.#applyChain(chain, optsMap, ctx);
+            const mergedOpts = this.#mergeOpts(chain, optsMap);
+            const { args, rawArgs } = leafCommand.#parseArguments(restArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
+            if (leafCommand.#action) {
                 try {
-                    await command.#action(actionParams);
+                    await leafCommand.#action(actionParams);
                 }
                 catch (err) {
                     if (err instanceof Error) {
@@ -143,11 +143,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) {
@@ -162,7 +162,7 @@ class Command {
     parse(argv) {
         const allOptions = this.#getMergedOptions();
         const opts = {};
-        const args = [];
+        const rawArgs = [];
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -187,7 +187,7 @@ class Command {
         while (i < remaining.length) {
             const token = remaining[i];
             if (token === '--') {
-                args.push(...remaining.slice(i + 1));
+                rawArgs.push(...remaining.slice(i + 1));
                 break;
             }
             if (token.startsWith('--')) {
@@ -198,7 +198,7 @@ class Command {
                 i = this.#parseShortOption(remaining, i, optionByShort, opts);
                 continue;
             }
-            args.push(token);
+            rawArgs.push(token);
             i += 1;
         }
         for (const opt of allOptions) {
@@ -218,12 +218,84 @@ class Command {
                 }
             }
         }
-        const requiredArgs = this.#arguments.filter(a => a.kind === 'required');
-        if (args.length < requiredArgs.length) {
-            const missing = requiredArgs.slice(args.length).map(a => a.name);
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        const { args } = this.#parseArguments(rawArgs);
+        return { opts, args, rawArgs };
+    }
+    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());
+            }
         }
-        return { opts, args };
+        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 = [];
@@ -347,7 +419,8 @@ class Command {
         }
         return argv;
     }
-    #route(argv) {
+    #routeChain(argv) {
+        const chain = [this];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
@@ -358,9 +431,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];
@@ -505,6 +631,9 @@ class Command {
         }
     }
     #validateArgumentConfig(arg) {
+        if (arg.kind === 'required' && arg.default !== undefined) {
+            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot have a default value`, this.#getCommandPath());
+        }
         if (arg.kind === 'variadic') {
             if (this.#arguments.some(a => a.kind === 'variadic')) {
                 throw new CommanderError('ConfigurationError', 'only one variadic argument is allowed', this.#getCommandPath());
@@ -523,8 +652,60 @@ class Command {
             }
         }
     }
-    #isBuiltinOption(opt) {
-        return opt === BUILTIN_HELP_OPTION || opt === BUILTIN_VERSION_OPTION;
+    #parseArguments(rawArgs) {
+        const argumentDefs = this.#arguments;
+        const args = {};
+        const requiredCount = argumentDefs.filter(a => a.kind === 'required').length;
+        if (rawArgs.length < requiredCount) {
+            const missing = argumentDefs
+                .filter(a => a.kind === 'required')
+                .slice(rawArgs.length)
+                .map(a => a.name);
+            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
+        }
+        let index = 0;
+        for (const def of argumentDefs) {
+            if (def.kind === 'variadic') {
+                const rest = rawArgs.slice(index);
+                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
+                index = rawArgs.length;
+                break;
+            }
+            const raw = rawArgs[index];
+            if (raw === undefined) {
+                if (def.kind === 'optional') {
+                    args[def.name] = def.default ?? undefined;
+                    continue;
+                }
+            }
+            else {
+                args[def.name] = this.#convertArgument(def, raw);
+                index += 1;
+            }
+        }
+        const hasVariadic = argumentDefs.some(a => a.kind === 'variadic');
+        if (!hasVariadic && index < rawArgs.length) {
+            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
+        }
+        return { args, rawArgs };
+    }
+    #convertArgument(def, raw) {
+        if (def.coerce) {
+            try {
+                return def.coerce(raw);
+            }
+            catch {
+                throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+        }
+        if (def.type === 'number') {
+            const n = Number(raw);
+            if (Number.isNaN(n)) {
+                throw new CommanderError('InvalidType', `invalid number "${raw}" for argument "${def.name}"`, this.#getCommandPath());
+            }
+            return n;
+        }
+        return raw;
     }
     #buildOptionMaps(allOptions, excludeResolver = false) {
         const optionByLong = new Map();
@@ -622,6 +803,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 CHANGED Viewed

@@ -46,14 +46,25 @@ interface IOption<T = unknown> {
 }
 /** Argument kind */
 type IArgumentKind = 'required' | 'optional' | 'variadic';
-/** Positional argument definition */
-interface IArgument {
+/** Argument value type */
+type IArgumentType = 'string' | 'number';
+/**
+ * Positional argument definition.
+ * @template T - The type of the argument value
+ */
+interface IArgument<T = unknown> {
     /** Argument name */
     name: string;
     /** Argument description */
     description: string;
     /** Argument kind: required / optional / variadic */
     kind: IArgumentKind;
+    /** Value type, defaults to 'string' */
+    type?: IArgumentType;
+    /** Default value when not provided (only effective for optional arguments) */
+    default?: T;
+    /** Custom value transformation (takes precedence over type conversion) */
+    coerce?: (rawValue: string) => T;
 }
 /** Command configuration */
 interface ICommandConfig {
@@ -91,8 +102,10 @@ interface IActionParams {
     ctx: ICommandContext;
     /** Parsed options */
     opts: Record<string, unknown>;
-    /** Parsed positional arguments */
-    args: string[];
+    /** Parsed positional arguments (keyed by argument name) */
+    args: Record<string, unknown>;
+    /** Raw positional argument strings (before type conversion) */
+    rawArgs: string[];
 }
 /** Action handler function */
 type IAction = (params: IActionParams) => void | Promise<void>;
@@ -109,11 +122,20 @@ interface IRunParams {
 interface IParseResult {
     /** Parsed options */
     opts: Record<string, unknown>;
-    /** Parsed positional arguments */
-    args: string[];
+    /** Parsed positional arguments (keyed by argument name) */
+    args: Record<string, unknown>;
+    /** Raw positional argument strings (before type conversion) */
+    rawArgs: 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' | 'TooManyArguments' | 'ConfigurationError';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;
@@ -177,6 +199,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 +254,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 CHANGED Viewed

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