@guanghechen/commander 4.3.0 → 4.4.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Change Log
 
+## 4.4.1
+
+### Patch Changes
+
+- fix(commander): centralize option policy and enforce version flag semantics — subcommands with
+  their own `version` now correctly expose `--version`; commands without `version` reject
+  `--version` instead of treating it as a boolean option.
+
+## 4.4.0
+
+### Minor Changes
+
+- enforce per-node help subcommand semantics
+
 ## 4.3.0
 
 ### Minor Changes

package/lib/cjs/index.cjs

@@ -368,30 +368,29 @@ class Command {
             const routeResult = this.#route(processedArgv);
             const { chain, remaining } = routeResult;
             const leafCommand = chain[chain.length - 1];
-            const rootCommand = chain[0];
             const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
             const { optionTokens, restArgs } = tokenizeResult;
-            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
-            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
-            if (!hasUserHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+            const leafPolicy = this.#mustGetOptionPolicy(optionPolicyMap, leafCommand);
+            if (leafPolicy.enableBuiltinHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
+            if (leafPolicy.enableBuiltinVersion) {
                 if (this.#hasFlag(optionTokens, 'version', 'V')) {
                     console.log(leafCommand.#version);
                     return;
                 }
             }
-            const resolveResult = this.#resolve(chain, optionTokens);
+            const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
             const ctx = {
                 cmd: leafCommand,
                 envs,
                 reporter: reporter$1 ?? this.#reporter ?? new reporter.Reporter(),
                 argv,
             };
-            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
                 opts: parseResult.opts,
@@ -402,7 +401,7 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
@@ -426,14 +425,15 @@ class Command {
         const leafCommand = chain[chain.length - 1];
         const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
         const { optionTokens, restArgs } = tokenizeResult;
-        const resolveResult = this.#resolve(chain, optionTokens);
+        const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+        const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
         const ctx = {
             cmd: leafCommand,
             envs,
             reporter: reporter$1 ?? this.#reporter ?? new reporter.Reporter(),
             argv,
         };
-        return this.#parse(chain, resolveResult, ctx, restArgs);
+        return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
         return this.#renderHelpPlain(this.#buildHelpData());
@@ -450,7 +450,7 @@ class Command {
         return color && process.stdout.isTTY === true;
     }
     #buildHelpData() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -587,7 +587,7 @@ class Command {
         return lines.join('\n');
     }
     getCompletionMeta() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
         for (const opt of allOptions) {
             options.push({
@@ -613,18 +613,48 @@ class Command {
             }),
         };
     }
+    #findSubcommandEntry(token) {
+        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+    }
+    #createUnknownSubcommandError(subcommand) {
+        const commandPath = this.#getCommandPath();
+        return new CommanderError('UnknownSubcommand', `unknown subcommand "${subcommand}" for command "${commandPath}"`, commandPath);
+    }
     #processHelpSubcommand(argv) {
-        if (!this.#builtin.command.help)
-            return argv;
-        if (argv.length < 1 || argv[0] !== 'help')
-            return argv;
-        if (argv.length === 1 || this.#subcommandsList.length === 0) {
-            return ['--help'];
-        }
-        const subName = argv[1];
-        const entry = this.#subcommandsList.find(e => e.name === subName || e.aliases.includes(subName));
-        if (entry) {
-            return [subName, '--help', ...argv.slice(2)];
+        let current = this;
+        for (let i = 0; i < argv.length; ++i) {
+            const token = argv[i];
+            if (token.startsWith('-')) {
+                return argv;
+            }
+            if (token === 'help') {
+                if (!current.#builtin.command.help) {
+                    if (current.#subcommandsList.length > 0) {
+                        throw current.#createUnknownSubcommandError('help');
+                    }
+                    return argv;
+                }
+                if (current.#subcommandsList.length === 0) {
+                    return argv;
+                }
+                const target = argv[i + 1];
+                if (target === undefined) {
+                    return [...argv.slice(0, i), '--help'];
+                }
+                const targetEntry = current.#findSubcommandEntry(target);
+                if (targetEntry === undefined) {
+                    throw current.#createUnknownSubcommandError(target);
+                }
+                if (argv[i + 2] !== undefined) {
+                    throw new CommanderError('UnexpectedArgument', 'help subcommand accepts at most one subcommand argument', current.#getCommandPath());
+                }
+                return [...argv.slice(0, i), target, '--help'];
+            }
+            const entry = current.#findSubcommandEntry(token);
+            if (entry === undefined) {
+                return argv;
+            }
+            current = entry.command;
         }
         return argv;
     }
@@ -636,7 +666,7 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const entry = current.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+            const entry = current.#findSubcommandEntry(token);
             if (!entry)
                 break;
             current = entry.command;
@@ -645,14 +675,14 @@ class Command {
         }
         return { chain, remaining: argv.slice(idx) };
     }
-    #resolve(chain, tokens) {
+    #resolve(chain, tokens, optionPolicyMap) {
         const consumedTokens = new Map();
         let remaining = [...tokens];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const includeVersion = i === 0;
-            const result = cmd.#shift(remaining, shadowed, includeVersion);
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            const result = cmd.#shift(remaining, shadowed, policy.mergedOptions);
             consumedTokens.set(cmd, result.consumed);
             remaining = result.remaining;
             for (const opt of cmd.#options) {
@@ -669,8 +699,7 @@ class Command {
         }
         return { consumedTokens, argTokens };
     }
-    #shift(tokens, shadowed, includeVersion) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #shift(tokens, shadowed, allOptions) {
         const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
         const optionByLong = new Map();
         const optionByShort = new Map();
@@ -738,18 +767,17 @@ class Command {
         }
         return { consumed, remaining };
     }
-    #parse(chain, resolveResult, ctx, restArgs) {
+    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
         const { consumedTokens, argTokens } = resolveResult;
         const leafCommand = chain[chain.length - 1];
-        this.#validateMergedShortOptions(chain);
+        this.#validateMergedShortOptions(chain, optionPolicyMap);
         const optsMap = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
+            const opts = cmd.#parseOptions(tokens, policy.mergedOptions, ctx.envs);
             optsMap.set(cmd, opts);
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+            for (const opt of policy.mergedOptions) {
                 if (opt.apply && opts[opt.long] !== undefined) {
                     opt.apply(opts[opt.long], ctx);
                 }
@@ -763,8 +791,7 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion, envs) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #parseOptions(tokens, allOptions, envs) {
         const opts = {};
         let sawColorToken = false;
         for (const opt of allOptions) {
@@ -946,22 +973,30 @@ class Command {
         }
         return raw;
     }
-    #getMergedOptions(includeVersion = !this.#parent) {
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #canUseBuiltinVersion() {
+        return this.#version !== undefined;
+    }
+    #resolveOptionPolicy() {
         const optionMap = new Map();
-        const hasUserColor = this.#options.some(o => o.long === 'color');
-        const hasUserHelp = this.#options.some(o => o.long === 'help');
-        const hasUserVersion = this.#options.some(o => o.long === 'version');
-        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
-        const hasUserSilent = this.#options.some(o => o.long === 'silent');
-        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
-        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
+        const hasUserColor = this.#hasUserOption('color');
+        const hasUserHelp = this.#hasUserOption('help');
+        const hasUserVersion = this.#hasUserOption('version');
+        const hasUserLogLevel = this.#hasUserOption('logLevel');
+        const hasUserSilent = this.#hasUserOption('silent');
+        const hasUserLogDate = this.#hasUserOption('logDate');
+        const hasUserLogColorful = this.#hasUserOption('logColorful');
+        const enableBuiltinHelp = !hasUserHelp;
+        const enableBuiltinVersion = !hasUserVersion && this.#canUseBuiltinVersion();
         if (this.#builtin.option.color && !hasUserColor) {
             optionMap.set('color', BUILTIN_COLOR_OPTION);
         }
-        if (!hasUserHelp) {
+        if (enableBuiltinHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
-        if (!hasUserVersion && includeVersion) {
+        if (enableBuiltinVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         if (this.#builtin.option.logLevel && !hasUserLogLevel) {
@@ -979,14 +1014,31 @@ class Command {
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
-        return Array.from(optionMap.values());
+        return {
+            mergedOptions: Array.from(optionMap.values()),
+            enableBuiltinHelp,
+            enableBuiltinVersion,
+        };
     }
-    #validateMergedShortOptions(chain) {
+    #buildOptionPolicyMap(chain) {
+        const optionPolicyMap = new Map();
+        for (const cmd of chain) {
+            optionPolicyMap.set(cmd, cmd.#resolveOptionPolicy());
+        }
+        return optionPolicyMap;
+    }
+    #mustGetOptionPolicy(optionPolicyMap, cmd) {
+        const policy = optionPolicyMap.get(cmd);
+        if (policy !== undefined) {
+            return policy;
+        }
+        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
+    }
+    #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            for (const opt of policy.mergedOptions) {
                 mergedByLong.set(opt.long, opt);
             }
         }
@@ -1082,8 +1134,8 @@ class Command {
             process.exit(1);
         }
     }
-    #resolveHelpColorOption(tokens, envs) {
-        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+    #resolveHelpColorOption(tokens, envs, policy = this.#resolveOptionPolicy()) {
+        const colorOption = policy.mergedOptions.find(opt => opt.long === 'color');
         let color = !isNoColorEnabled(envs);
         if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
             return color;

package/lib/esm/index.mjs

@@ -346,30 +346,29 @@ class Command {
             const routeResult = this.#route(processedArgv);
             const { chain, remaining } = routeResult;
             const leafCommand = chain[chain.length - 1];
-            const rootCommand = chain[0];
             const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
             const { optionTokens, restArgs } = tokenizeResult;
-            const hasUserHelp = leafCommand.#options.some(o => o.long === 'help');
-            const hasUserVersion = leafCommand.#options.some(o => o.long === 'version');
-            if (!hasUserHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+            const leafPolicy = this.#mustGetOptionPolicy(optionPolicyMap, leafCommand);
+            if (leafPolicy.enableBuiltinHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
+            if (leafPolicy.enableBuiltinVersion) {
                 if (this.#hasFlag(optionTokens, 'version', 'V')) {
                     console.log(leafCommand.#version);
                     return;
                 }
             }
-            const resolveResult = this.#resolve(chain, optionTokens);
+            const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
             const ctx = {
                 cmd: leafCommand,
                 envs,
                 reporter: reporter ?? this.#reporter ?? new Reporter(),
                 argv,
             };
-            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
                 opts: parseResult.opts,
@@ -380,7 +379,7 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
@@ -404,14 +403,15 @@ class Command {
         const leafCommand = chain[chain.length - 1];
         const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
         const { optionTokens, restArgs } = tokenizeResult;
-        const resolveResult = this.#resolve(chain, optionTokens);
+        const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+        const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
         const ctx = {
             cmd: leafCommand,
             envs,
             reporter: reporter ?? this.#reporter ?? new Reporter(),
             argv,
         };
-        return this.#parse(chain, resolveResult, ctx, restArgs);
+        return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
         return this.#renderHelpPlain(this.#buildHelpData());
@@ -428,7 +428,7 @@ class Command {
         return color && process.stdout.isTTY === true;
     }
     #buildHelpData() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -565,7 +565,7 @@ class Command {
         return lines.join('\n');
     }
     getCompletionMeta() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
         for (const opt of allOptions) {
             options.push({
@@ -591,18 +591,48 @@ class Command {
             }),
         };
     }
+    #findSubcommandEntry(token) {
+        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+    }
+    #createUnknownSubcommandError(subcommand) {
+        const commandPath = this.#getCommandPath();
+        return new CommanderError('UnknownSubcommand', `unknown subcommand "${subcommand}" for command "${commandPath}"`, commandPath);
+    }
     #processHelpSubcommand(argv) {
-        if (!this.#builtin.command.help)
-            return argv;
-        if (argv.length < 1 || argv[0] !== 'help')
-            return argv;
-        if (argv.length === 1 || this.#subcommandsList.length === 0) {
-            return ['--help'];
-        }
-        const subName = argv[1];
-        const entry = this.#subcommandsList.find(e => e.name === subName || e.aliases.includes(subName));
-        if (entry) {
-            return [subName, '--help', ...argv.slice(2)];
+        let current = this;
+        for (let i = 0; i < argv.length; ++i) {
+            const token = argv[i];
+            if (token.startsWith('-')) {
+                return argv;
+            }
+            if (token === 'help') {
+                if (!current.#builtin.command.help) {
+                    if (current.#subcommandsList.length > 0) {
+                        throw current.#createUnknownSubcommandError('help');
+                    }
+                    return argv;
+                }
+                if (current.#subcommandsList.length === 0) {
+                    return argv;
+                }
+                const target = argv[i + 1];
+                if (target === undefined) {
+                    return [...argv.slice(0, i), '--help'];
+                }
+                const targetEntry = current.#findSubcommandEntry(target);
+                if (targetEntry === undefined) {
+                    throw current.#createUnknownSubcommandError(target);
+                }
+                if (argv[i + 2] !== undefined) {
+                    throw new CommanderError('UnexpectedArgument', 'help subcommand accepts at most one subcommand argument', current.#getCommandPath());
+                }
+                return [...argv.slice(0, i), target, '--help'];
+            }
+            const entry = current.#findSubcommandEntry(token);
+            if (entry === undefined) {
+                return argv;
+            }
+            current = entry.command;
         }
         return argv;
     }
@@ -614,7 +644,7 @@ class Command {
             const token = argv[idx];
             if (token.startsWith('-'))
                 break;
-            const entry = current.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+            const entry = current.#findSubcommandEntry(token);
             if (!entry)
                 break;
             current = entry.command;
@@ -623,14 +653,14 @@ class Command {
         }
         return { chain, remaining: argv.slice(idx) };
     }
-    #resolve(chain, tokens) {
+    #resolve(chain, tokens, optionPolicyMap) {
         const consumedTokens = new Map();
         let remaining = [...tokens];
         const shadowed = new Set();
         for (let i = chain.length - 1; i >= 0; i--) {
             const cmd = chain[i];
-            const includeVersion = i === 0;
-            const result = cmd.#shift(remaining, shadowed, includeVersion);
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            const result = cmd.#shift(remaining, shadowed, policy.mergedOptions);
             consumedTokens.set(cmd, result.consumed);
             remaining = result.remaining;
             for (const opt of cmd.#options) {
@@ -647,8 +677,7 @@ class Command {
         }
         return { consumedTokens, argTokens };
     }
-    #shift(tokens, shadowed, includeVersion) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #shift(tokens, shadowed, allOptions) {
         const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
         const optionByLong = new Map();
         const optionByShort = new Map();
@@ -716,18 +745,17 @@ class Command {
         }
         return { consumed, remaining };
     }
-    #parse(chain, resolveResult, ctx, restArgs) {
+    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
         const { consumedTokens, argTokens } = resolveResult;
         const leafCommand = chain[chain.length - 1];
-        this.#validateMergedShortOptions(chain);
+        this.#validateMergedShortOptions(chain, optionPolicyMap);
         const optsMap = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
+            const opts = cmd.#parseOptions(tokens, policy.mergedOptions, ctx.envs);
             optsMap.set(cmd, opts);
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+            for (const opt of policy.mergedOptions) {
                 if (opt.apply && opts[opt.long] !== undefined) {
                     opt.apply(opts[opt.long], ctx);
                 }
@@ -741,8 +769,7 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion, envs) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #parseOptions(tokens, allOptions, envs) {
         const opts = {};
         let sawColorToken = false;
         for (const opt of allOptions) {
@@ -924,22 +951,30 @@ class Command {
         }
         return raw;
     }
-    #getMergedOptions(includeVersion = !this.#parent) {
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #canUseBuiltinVersion() {
+        return this.#version !== undefined;
+    }
+    #resolveOptionPolicy() {
         const optionMap = new Map();
-        const hasUserColor = this.#options.some(o => o.long === 'color');
-        const hasUserHelp = this.#options.some(o => o.long === 'help');
-        const hasUserVersion = this.#options.some(o => o.long === 'version');
-        const hasUserLogLevel = this.#options.some(o => o.long === 'logLevel');
-        const hasUserSilent = this.#options.some(o => o.long === 'silent');
-        const hasUserLogDate = this.#options.some(o => o.long === 'logDate');
-        const hasUserLogColorful = this.#options.some(o => o.long === 'logColorful');
+        const hasUserColor = this.#hasUserOption('color');
+        const hasUserHelp = this.#hasUserOption('help');
+        const hasUserVersion = this.#hasUserOption('version');
+        const hasUserLogLevel = this.#hasUserOption('logLevel');
+        const hasUserSilent = this.#hasUserOption('silent');
+        const hasUserLogDate = this.#hasUserOption('logDate');
+        const hasUserLogColorful = this.#hasUserOption('logColorful');
+        const enableBuiltinHelp = !hasUserHelp;
+        const enableBuiltinVersion = !hasUserVersion && this.#canUseBuiltinVersion();
         if (this.#builtin.option.color && !hasUserColor) {
             optionMap.set('color', BUILTIN_COLOR_OPTION);
         }
-        if (!hasUserHelp) {
+        if (enableBuiltinHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
-        if (!hasUserVersion && includeVersion) {
+        if (enableBuiltinVersion) {
             optionMap.set('version', BUILTIN_VERSION_OPTION);
         }
         if (this.#builtin.option.logLevel && !hasUserLogLevel) {
@@ -957,14 +992,31 @@ class Command {
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
-        return Array.from(optionMap.values());
+        return {
+            mergedOptions: Array.from(optionMap.values()),
+            enableBuiltinHelp,
+            enableBuiltinVersion,
+        };
     }
-    #validateMergedShortOptions(chain) {
+    #buildOptionPolicyMap(chain) {
+        const optionPolicyMap = new Map();
+        for (const cmd of chain) {
+            optionPolicyMap.set(cmd, cmd.#resolveOptionPolicy());
+        }
+        return optionPolicyMap;
+    }
+    #mustGetOptionPolicy(optionPolicyMap, cmd) {
+        const policy = optionPolicyMap.get(cmd);
+        if (policy !== undefined) {
+            return policy;
+        }
+        throw new CommanderError('ConfigurationError', `missing option policy for command "${cmd.#getCommandPath()}"`, this.#getCommandPath());
+    }
+    #validateMergedShortOptions(chain, optionPolicyMap) {
         const mergedByLong = new Map();
-        for (let i = 0; i < chain.length; i++) {
-            const cmd = chain[i];
-            const includeVersion = i === 0;
-            for (const opt of cmd.#getMergedOptions(includeVersion)) {
+        for (const cmd of chain) {
+            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
+            for (const opt of policy.mergedOptions) {
                 mergedByLong.set(opt.long, opt);
             }
         }
@@ -1060,8 +1112,8 @@ class Command {
             process.exit(1);
         }
     }
-    #resolveHelpColorOption(tokens, envs) {
-        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+    #resolveHelpColorOption(tokens, envs, policy = this.#resolveOptionPolicy()) {
+        const colorOption = policy.mergedOptions.find(opt => opt.long === 'color');
         let color = !isNoColorEnabled(envs);
         if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
             return color;

package/lib/types/index.d.ts

@@ -129,7 +129,7 @@ interface ICommandConfig {
     name?: string;
     /** Command description */
     desc: string;
-    /** Version (for root --version) */
+    /** Version (for built-in --version on this command) */
     version?: string;
     /** Built-in features configuration */
     builtin?: boolean | ICommandBuiltinConfig;
@@ -224,7 +224,7 @@ interface ICommandParseResult {
     rawArgs: string[];
 }
 /** Error kinds for command parsing */
-type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
+type ICommanderErrorKind = 'InvalidOptionFormat' | 'InvalidNegativeOption' | 'NegativeOptionWithValue' | 'NegativeOptionType' | 'UnknownOption' | 'UnknownSubcommand' | 'UnexpectedArgument' | 'MissingValue' | 'InvalidType' | 'UnsupportedShortSyntax' | 'OptionConflict' | 'MissingRequired' | 'InvalidChoice' | 'InvalidBooleanValue' | 'MissingRequiredArgument' | 'TooManyArguments' | 'ConfigurationError';
 /** Commander error with structured information */
 declare class CommanderError extends Error {
     readonly kind: ICommanderErrorKind;

package/package.json

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