@guanghechen/commander 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Change Log
 
+## 3.3.0
+
+### Minor Changes
+
+- Apply code review fixes:
+  - Fix `#getCommandPath` to return full command path (e.g., "cli sub" instead of just "sub")
+  - Remove unused `#parseLongOption` and `#parseShortOption` dead code
+  - Improve `--no-{option}` help description to "Negate --{option}"
+  - Document short option negative value limitation in spec
+
+## 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

package/README.md

@@ -124,7 +124,6 @@ const root = new Command({
 })
 
 const clone = new Command({
-  name: 'clone',
   description: 'Clone a repository',
 })
   .argument({ name: 'url', kind: 'required', description: 'Repository URL' })
@@ -134,8 +133,6 @@ const clone = new Command({
   })
 
 const commit = new Command({
-  name: 'commit',
-  aliases: ['ci'],
   description: 'Record changes to the repository',
 })
   .option({ long: 'message', short: 'm', type: 'string', required: true, description: 'Commit message' })
@@ -144,7 +141,7 @@ const commit = new Command({
     console.log(`Committing: ${opts['message']}`)
   })
 
-root.subcommand(clone).subcommand(commit)
+root.subcommand('clone', clone).subcommand('commit', commit).subcommand('ci', commit)
 
 root.run({ argv: process.argv.slice(2), envs: process.env })
 ```
@@ -161,7 +158,7 @@ const root = new Command({
 })
 
 // Add completion subcommand
-root.subcommand(new CompletionCommand(root))
+root.subcommand('completion', new CompletionCommand(root))
 
 // Generate completion scripts:
 // mycli completion --bash > ~/.local/share/bash-completion/completions/mycli

package/lib/cjs/index.cjs

@@ -68,6 +68,8 @@ class Command {
     #description;
     #version;
     #helpSubcommandEnabled;
+    #reporter;
+    #parent;
     #options = [];
     #arguments = [];
     #subcommands = [];
@@ -77,6 +79,7 @@ class Command {
         this.#description = config.description;
         this.#version = config.version;
         this.#helpSubcommandEnabled = config.help ?? false;
+        this.#reporter = config.reporter;
     }
     get name() {
         return this.#name;
@@ -87,6 +90,9 @@ class Command {
     get version() {
         return this.#version;
     }
+    get parent() {
+        return this.#parent;
+    }
     get options() {
         return [...this.#options];
     }
@@ -112,12 +118,16 @@ class Command {
         if (this.#helpSubcommandEnabled && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
+        if (cmd.#parent && cmd.#parent !== this) {
+            throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
+        }
         const existing = this.#subcommands.find(e => e.command === cmd);
         if (existing) {
             existing.aliases.push(name);
         }
         else {
             cmd.#name = name;
+            cmd.#parent = this;
             this.#subcommands.push({ name, aliases: [], command: cmd });
         }
         return this;
@@ -128,34 +138,35 @@ class Command {
             const processedArgv = this.#processHelpSubcommand(argv);
             const { chain, remaining } = this.#routeChain(processedArgv);
             const leafCommand = chain[chain.length - 1];
+            const rootCommand = chain[0];
+            const includeRootVersion = chain.length === 1;
+            this.#validateMergedShortOptions(chain, includeRootVersion);
             const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
-            const leafOptions = leafCommand.#getMergedOptions();
+            const leafOptions = leafCommand.#getMergedOptions(leafCommand === rootCommand);
             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 && leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
-                console.log(leafCommand.version ?? 'unknown');
-                return;
+            if (!hasUserVersion && leafCommand === rootCommand) {
+                if (leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
+                    console.log(leafCommand.version ?? 'unknown');
+                    return;
+                }
             }
-            const optsMap = this.#shiftChain(chain, optionTokens);
+            const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
             const ctx = {
                 cmd: leafCommand,
                 envs,
-                reporter: reporter ?? new DefaultReporter(),
+                reporter: reporter ?? this.#reporter ?? new DefaultReporter(),
                 argv,
             };
             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 };
+            const allArgs = [...positionalArgs, ...restArgs];
+            const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
             if (leafCommand.#action) {
                 try {
                     await leafCommand.#action(actionParams);
@@ -187,76 +198,23 @@ class Command {
         }
     }
     parse(argv) {
-        const allOptions = this.#getMergedOptions();
-        const opts = {};
-        const args = [];
-        for (const opt of allOptions) {
-            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 = [...argv];
-        const resolverOptions = allOptions.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(allOptions, true);
-        remaining = this.#normalizeArgv(remaining, booleanOptions);
-        let i = 0;
-        while (i < remaining.length) {
-            const token = remaining[i];
-            if (token === '--') {
-                args.push(...remaining.slice(i + 1));
-                break;
-            }
-            if (token.startsWith('--')) {
-                i = this.#parseLongOption(remaining, i, optionByLong, opts);
-                continue;
-            }
-            if (token.startsWith('-') && token.length > 1) {
-                i = this.#parseShortOption(remaining, i, optionByShort, opts);
-                continue;
-            }
-            args.push(token);
-            i += 1;
-        }
-        for (const opt of allOptions) {
-            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 allOptions) {
-            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());
-                    }
-                }
-            }
-        }
-        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());
-        }
-        return { opts, args };
+        const processedArgv = this.#processHelpSubcommand(argv);
+        const { chain, remaining } = this.#routeChain(processedArgv);
+        const leafCommand = chain[chain.length - 1];
+        const includeRootVersion = chain.length === 1;
+        this.#validateMergedShortOptions(chain, includeRootVersion);
+        const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
+        const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
+        const mergedOpts = this.#mergeOpts(chain, optsMap);
+        const allArgs = [...positionalArgs, ...restArgs];
+        const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
+        return { opts: mergedOpts, args, rawArgs };
     }
     shift(tokens) {
         return this.#shiftWithShadowed(tokens, new Set());
     }
-    #shiftWithShadowed(tokens, shadowed) {
-        const allDirectOptions = this.#getMergedOptions();
+    #shiftWithShadowed(tokens, shadowed, includeVersion = !this.#parent) {
+        const allDirectOptions = this.#getMergedOptions(includeVersion);
         const directOptions = allDirectOptions.filter(o => !shadowed.has(o.long));
         const opts = {};
         for (const opt of directOptions) {
@@ -373,7 +331,7 @@ class Command {
                 if (effectiveType === 'boolean') {
                     optLines.push({
                         sig: `    --no-${opt.long}`,
-                        desc: opt.description,
+                        desc: `Negate --${opt.long}`,
                     });
                 }
             }
@@ -436,11 +394,11 @@ class Command {
         };
     }
     #processHelpSubcommand(argv) {
-        if (!this.#helpSubcommandEnabled || this.#subcommands.length === 0)
+        if (!this.#helpSubcommandEnabled)
             return argv;
         if (argv.length < 1 || argv[0] !== 'help')
             return argv;
-        if (argv.length === 1) {
+        if (argv.length === 1 || this.#subcommands.length === 0) {
             return ['--help'];
         }
         const subName = argv[1];
@@ -477,30 +435,34 @@ class Command {
             restArgs: tokens.slice(ddIdx + 1),
         };
     }
-    #shiftChain(chain, tokens) {
+    #shiftChain(chain, tokens, includeRootVersion) {
         const optsMap = new Map();
         let remaining = [...tokens];
+        const rootCommand = chain[0];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const result = cmd.#shiftWithShadowed(remaining, shadowed);
+            const includeVersion = cmd === rootCommand && includeRootVersion;
+            const result = cmd.#shiftWithShadowed(remaining, shadowed, includeVersion);
             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());
+        const positionalArgs = [];
+        for (const token of remaining) {
+            if (token.startsWith('-')) {
+                const leafCommand = chain[chain.length - 1];
+                if (!token.startsWith('--') && token.length > 2) {
+                    const flag = token[1];
+                    throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+                }
+                throw new CommanderError('UnknownOption', `unknown option "${token}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
             }
+            positionalArgs.push(token);
         }
-        return optsMap;
+        return { optsMap, positionalArgs };
     }
     #applyChain(chain, optsMap, ctx) {
         for (const cmd of chain) {
@@ -519,82 +481,6 @@ class Command {
         }
         return merged;
     }
-    #parseLongOption(argv, idx, optionByLong, opts) {
-        const token = argv[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) {
-            throw new CommanderError('UnknownOption', `unknown option "--${optName}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
-        }
-        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 idx + 1;
-        }
-        let value;
-        let nextIdx = idx;
-        if (inlineValue !== undefined) {
-            value = inlineValue;
-        }
-        else if (idx + 1 < argv.length) {
-            value = argv[idx + 1];
-            nextIdx += 1;
-        }
-        else {
-            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
-        }
-        this.#applyValue(opt, value, opts);
-        return nextIdx + 1;
-    }
-    #parseShortOption(argv, idx, optionByShort, opts) {
-        const token = argv[idx];
-        if (token.includes('=')) {
-            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
-        }
-        const flags = token.slice(1);
-        for (let j = 0; j < flags.length; j++) {
-            const flag = flags[j];
-            const opt = optionByShort.get(flag);
-            if (!opt) {
-                throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
-            }
-            if (opt.type === 'boolean') {
-                opts[opt.long] = true;
-                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 < argv.length && !argv[idx + 1].startsWith('-')) {
-                const value = argv[idx + 1];
-                this.#applyValue(opt, value, opts);
-                return idx + 2;
-            }
-            throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
-        }
-        return idx + 1;
-    }
     #applyValue(opt, rawValue, opts) {
         const type = opt.type ?? 'string';
         let parsedValue = rawValue;
@@ -627,14 +513,14 @@ class Command {
             opts[opt.long] = parsedValue;
         }
     }
-    #getMergedOptions() {
+    #getMergedOptions(includeVersion = !this.#parent) {
         const optionMap = new Map();
         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) {
+        if (!hasUserVersion && includeVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         for (const opt of this.#options) {
@@ -642,6 +528,26 @@ class Command {
         }
         return Array.from(optionMap.values());
     }
+    #validateMergedShortOptions(chain, includeRootVersion) {
+        const mergedByLong = new Map();
+        const rootCommand = chain[0];
+        for (const cmd of chain) {
+            const includeVersion = cmd === rootCommand && includeRootVersion;
+            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+                mergedByLong.set(opt.long, opt);
+            }
+        }
+        const shortMap = new Map();
+        for (const opt of mergedByLong.values()) {
+            if (!opt.short)
+                continue;
+            const existingLong = shortMap.get(opt.short);
+            if (existingLong && existingLong !== opt.long) {
+                throw new CommanderError('OptionConflict', `short option "-${opt.short}" conflicts with "--${existingLong}"`, this.#getCommandPath());
+            }
+            shortMap.set(opt.short, opt.long);
+        }
+    }
     #validateOptionConfig(opt) {
         if (opt.long.startsWith('no-')) {
             throw new CommanderError('ConfigurationError', `option long name cannot start with "no-": "${opt.long}"`, this.#getCommandPath());
@@ -662,6 +568,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());
@@ -680,6 +589,61 @@ class Command {
             }
         }
     }
+    #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();
         const optionByShort = new Map();
@@ -774,7 +738,15 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        return this.#name;
+        const parts = [];
+        let current = this;
+        while (current) {
+            if (current.#name) {
+                parts.unshift(current.#name);
+            }
+            current = current.#parent;
+        }
+        return parts.join(' ') || this.#name;
     }
     #tryConsumeLongOption(tokens, idx, optionByLong, opts) {
         const token = tokens[idx];

package/lib/esm/index.mjs

@@ -46,6 +46,8 @@ class Command {
     #description;
     #version;
     #helpSubcommandEnabled;
+    #reporter;
+    #parent;
     #options = [];
     #arguments = [];
     #subcommands = [];
@@ -55,6 +57,7 @@ class Command {
         this.#description = config.description;
         this.#version = config.version;
         this.#helpSubcommandEnabled = config.help ?? false;
+        this.#reporter = config.reporter;
     }
     get name() {
         return this.#name;
@@ -65,6 +68,9 @@ class Command {
     get version() {
         return this.#version;
     }
+    get parent() {
+        return this.#parent;
+    }
     get options() {
         return [...this.#options];
     }
@@ -90,12 +96,16 @@ class Command {
         if (this.#helpSubcommandEnabled && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
         }
+        if (cmd.#parent && cmd.#parent !== this) {
+            throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
+        }
         const existing = this.#subcommands.find(e => e.command === cmd);
         if (existing) {
             existing.aliases.push(name);
         }
         else {
             cmd.#name = name;
+            cmd.#parent = this;
             this.#subcommands.push({ name, aliases: [], command: cmd });
         }
         return this;
@@ -106,34 +116,35 @@ class Command {
             const processedArgv = this.#processHelpSubcommand(argv);
             const { chain, remaining } = this.#routeChain(processedArgv);
             const leafCommand = chain[chain.length - 1];
+            const rootCommand = chain[0];
+            const includeRootVersion = chain.length === 1;
+            this.#validateMergedShortOptions(chain, includeRootVersion);
             const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
-            const leafOptions = leafCommand.#getMergedOptions();
+            const leafOptions = leafCommand.#getMergedOptions(leafCommand === rootCommand);
             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 && leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
-                console.log(leafCommand.version ?? 'unknown');
-                return;
+            if (!hasUserVersion && leafCommand === rootCommand) {
+                if (leafCommand.#hasVersionFlag(optionTokens, leafOptions)) {
+                    console.log(leafCommand.version ?? 'unknown');
+                    return;
+                }
             }
-            const optsMap = this.#shiftChain(chain, optionTokens);
+            const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
             const ctx = {
                 cmd: leafCommand,
                 envs,
-                reporter: reporter ?? new DefaultReporter(),
+                reporter: reporter ?? this.#reporter ?? new DefaultReporter(),
                 argv,
             };
             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 };
+            const allArgs = [...positionalArgs, ...restArgs];
+            const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
+            const actionParams = { ctx, opts: mergedOpts, args, rawArgs };
             if (leafCommand.#action) {
                 try {
                     await leafCommand.#action(actionParams);
@@ -165,76 +176,23 @@ class Command {
         }
     }
     parse(argv) {
-        const allOptions = this.#getMergedOptions();
-        const opts = {};
-        const args = [];
-        for (const opt of allOptions) {
-            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 = [...argv];
-        const resolverOptions = allOptions.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(allOptions, true);
-        remaining = this.#normalizeArgv(remaining, booleanOptions);
-        let i = 0;
-        while (i < remaining.length) {
-            const token = remaining[i];
-            if (token === '--') {
-                args.push(...remaining.slice(i + 1));
-                break;
-            }
-            if (token.startsWith('--')) {
-                i = this.#parseLongOption(remaining, i, optionByLong, opts);
-                continue;
-            }
-            if (token.startsWith('-') && token.length > 1) {
-                i = this.#parseShortOption(remaining, i, optionByShort, opts);
-                continue;
-            }
-            args.push(token);
-            i += 1;
-        }
-        for (const opt of allOptions) {
-            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 allOptions) {
-            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());
-                    }
-                }
-            }
-        }
-        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());
-        }
-        return { opts, args };
+        const processedArgv = this.#processHelpSubcommand(argv);
+        const { chain, remaining } = this.#routeChain(processedArgv);
+        const leafCommand = chain[chain.length - 1];
+        const includeRootVersion = chain.length === 1;
+        this.#validateMergedShortOptions(chain, includeRootVersion);
+        const { optionTokens, restArgs } = this.#splitAtDoubleDash(remaining);
+        const { optsMap, positionalArgs } = this.#shiftChain(chain, optionTokens, includeRootVersion);
+        const mergedOpts = this.#mergeOpts(chain, optsMap);
+        const allArgs = [...positionalArgs, ...restArgs];
+        const { args, rawArgs } = leafCommand.#parseArguments(allArgs);
+        return { opts: mergedOpts, args, rawArgs };
     }
     shift(tokens) {
         return this.#shiftWithShadowed(tokens, new Set());
     }
-    #shiftWithShadowed(tokens, shadowed) {
-        const allDirectOptions = this.#getMergedOptions();
+    #shiftWithShadowed(tokens, shadowed, includeVersion = !this.#parent) {
+        const allDirectOptions = this.#getMergedOptions(includeVersion);
         const directOptions = allDirectOptions.filter(o => !shadowed.has(o.long));
         const opts = {};
         for (const opt of directOptions) {
@@ -351,7 +309,7 @@ class Command {
                 if (effectiveType === 'boolean') {
                     optLines.push({
                         sig: `    --no-${opt.long}`,
-                        desc: opt.description,
+                        desc: `Negate --${opt.long}`,
                     });
                 }
             }
@@ -414,11 +372,11 @@ class Command {
         };
     }
     #processHelpSubcommand(argv) {
-        if (!this.#helpSubcommandEnabled || this.#subcommands.length === 0)
+        if (!this.#helpSubcommandEnabled)
             return argv;
         if (argv.length < 1 || argv[0] !== 'help')
             return argv;
-        if (argv.length === 1) {
+        if (argv.length === 1 || this.#subcommands.length === 0) {
             return ['--help'];
         }
         const subName = argv[1];
@@ -455,30 +413,34 @@ class Command {
             restArgs: tokens.slice(ddIdx + 1),
         };
     }
-    #shiftChain(chain, tokens) {
+    #shiftChain(chain, tokens, includeRootVersion) {
         const optsMap = new Map();
         let remaining = [...tokens];
+        const rootCommand = chain[0];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const result = cmd.#shiftWithShadowed(remaining, shadowed);
+            const includeVersion = cmd === rootCommand && includeRootVersion;
+            const result = cmd.#shiftWithShadowed(remaining, shadowed, includeVersion);
             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());
+        const positionalArgs = [];
+        for (const token of remaining) {
+            if (token.startsWith('-')) {
+                const leafCommand = chain[chain.length - 1];
+                if (!token.startsWith('--') && token.length > 2) {
+                    const flag = token[1];
+                    throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+                }
+                throw new CommanderError('UnknownOption', `unknown option "${token}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
             }
+            positionalArgs.push(token);
         }
-        return optsMap;
+        return { optsMap, positionalArgs };
     }
     #applyChain(chain, optsMap, ctx) {
         for (const cmd of chain) {
@@ -497,82 +459,6 @@ class Command {
         }
         return merged;
     }
-    #parseLongOption(argv, idx, optionByLong, opts) {
-        const token = argv[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) {
-            throw new CommanderError('UnknownOption', `unknown option "--${optName}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
-        }
-        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 idx + 1;
-        }
-        let value;
-        let nextIdx = idx;
-        if (inlineValue !== undefined) {
-            value = inlineValue;
-        }
-        else if (idx + 1 < argv.length) {
-            value = argv[idx + 1];
-            nextIdx += 1;
-        }
-        else {
-            throw new CommanderError('MissingValue', `option "--${optName}" requires a value`, this.#getCommandPath());
-        }
-        this.#applyValue(opt, value, opts);
-        return nextIdx + 1;
-    }
-    #parseShortOption(argv, idx, optionByShort, opts) {
-        const token = argv[idx];
-        if (token.includes('=')) {
-            throw new CommanderError('UnsupportedShortSyntax', `"-${token.slice(1)}" is not supported. Use "-${token[1]} ${token.slice(3)}" instead`, this.#getCommandPath());
-        }
-        const flags = token.slice(1);
-        for (let j = 0; j < flags.length; j++) {
-            const flag = flags[j];
-            const opt = optionByShort.get(flag);
-            if (!opt) {
-                throw new CommanderError('UnknownOption', `unknown option "-${flag}" for command "${this.#getCommandPath()}"`, this.#getCommandPath());
-            }
-            if (opt.type === 'boolean') {
-                opts[opt.long] = true;
-                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 < argv.length && !argv[idx + 1].startsWith('-')) {
-                const value = argv[idx + 1];
-                this.#applyValue(opt, value, opts);
-                return idx + 2;
-            }
-            throw new CommanderError('MissingValue', `option "-${flag}" requires a value`, this.#getCommandPath());
-        }
-        return idx + 1;
-    }
     #applyValue(opt, rawValue, opts) {
         const type = opt.type ?? 'string';
         let parsedValue = rawValue;
@@ -605,14 +491,14 @@ class Command {
             opts[opt.long] = parsedValue;
         }
     }
-    #getMergedOptions() {
+    #getMergedOptions(includeVersion = !this.#parent) {
         const optionMap = new Map();
         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) {
+        if (!hasUserVersion && includeVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         for (const opt of this.#options) {
@@ -620,6 +506,26 @@ class Command {
         }
         return Array.from(optionMap.values());
     }
+    #validateMergedShortOptions(chain, includeRootVersion) {
+        const mergedByLong = new Map();
+        const rootCommand = chain[0];
+        for (const cmd of chain) {
+            const includeVersion = cmd === rootCommand && includeRootVersion;
+            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+                mergedByLong.set(opt.long, opt);
+            }
+        }
+        const shortMap = new Map();
+        for (const opt of mergedByLong.values()) {
+            if (!opt.short)
+                continue;
+            const existingLong = shortMap.get(opt.short);
+            if (existingLong && existingLong !== opt.long) {
+                throw new CommanderError('OptionConflict', `short option "-${opt.short}" conflicts with "--${existingLong}"`, this.#getCommandPath());
+            }
+            shortMap.set(opt.short, opt.long);
+        }
+    }
     #validateOptionConfig(opt) {
         if (opt.long.startsWith('no-')) {
             throw new CommanderError('ConfigurationError', `option long name cannot start with "no-": "${opt.long}"`, this.#getCommandPath());
@@ -640,6 +546,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());
@@ -658,6 +567,61 @@ class Command {
             }
         }
     }
+    #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();
         const optionByShort = new Map();
@@ -752,7 +716,15 @@ class Command {
         return result;
     }
     #getCommandPath() {
-        return this.#name;
+        const parts = [];
+        let current = this;
+        while (current) {
+            if (current.#name) {
+                parts.unshift(current.#name);
+            }
+            current = current.#parent;
+        }
+        return parts.join(' ') || this.#name;
     }
     #tryConsumeLongOption(tokens, idx, optionByLong, opts) {
         const token = tokens[idx];

package/lib/types/index.d.ts

@@ -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 {
@@ -61,16 +72,19 @@ interface ICommandConfig {
     name?: string;
     /** Command description */
     description: string;
-    /** Version (only effective for root command) */
+    /** Version (only effective for built-in root --version) */
     version?: string;
     /** Enable built-in "help" subcommand (only effective when command has subcommands) */
     help?: boolean;
+    /** Default reporter for this command (can be overridden by run params) */
+    reporter?: IReporter;
 }
 /** Forward declaration for Command class */
 interface ICommand {
     readonly name: string;
     readonly description: string;
     readonly version: string | undefined;
+    readonly parent?: ICommand;
     readonly options: IOption[];
     readonly arguments: IArgument[];
 }
@@ -91,8 +105,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>;
@@ -102,15 +118,17 @@ interface IRunParams {
     argv: string[];
     /** Environment variables (usually process.env) */
     envs: Record<string, string | undefined>;
-    /** Optional reporter for logging (defaults to console reporter) */
+    /** Optional reporter override (defaults to command's reporter or console reporter) */
     reporter?: IReporter;
 }
 /** parse() method result */
 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 {
@@ -120,7 +138,7 @@ interface IShiftResult {
     remaining: string[];
 }
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'UnknownOption' | 'UnexpectedArgument' | '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;
@@ -176,6 +194,7 @@ declare class Command implements ICommand {
     get name(): string;
     get description(): string;
     get version(): string | undefined;
+    get parent(): Command | undefined;
     get options(): IOption[];
     get arguments(): IArgument[];
     option(opt: IOption): this;

package/package.json

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