@guanghechen/commander 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## 4.4.0
+
+### Minor Changes
+
+- enforce per-node help subcommand semantics
+
+## 4.3.0
+
+### Minor Changes
+
+- feat: add fluent help examples and styled help renderer
+
 ## 4.2.0
 
 ### Minor Changes

package/README.md

@@ -202,6 +202,29 @@ new Command({ name: 'example', description: 'Option types demo' })
   })
 ```
 
+### Help Examples
+
+```typescript
+import { Command } from '@guanghechen/commander'
+
+const cli = new Command({ name: 'mycli', desc: 'My CLI tool' })
+
+cli
+  .example('Initialize Project', 'init my-app', 'Create project scaffold')
+  .example('Watch Build', 'build --watch', 'Rebuild on file changes')
+  .action(() => {})
+
+await cli.run({ argv: ['--help'], envs: process.env })
+```
+
+`usage` 是相对当前 command path 的片段，help 中会自动补齐前缀，例如 `mycli build --watch`。
+
+`--color` / `--no-color` 仅控制 help 文本的终端着色；
+`--log-colorful` / `--no-log-colorful` 控制 `Reporter` 的日志着色。
+
+当环境变量 `NO_COLOR` 存在时，help 渲染默认视为 `--no-color`；
+显式传入 `--color` 可以覆盖这个默认值。
+
 ## Reference
 
 - [homepage][homepage]

package/lib/cjs/index.cjs

@@ -24,6 +24,18 @@ function _interopNamespaceDefault(e) {
 var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
 var path__namespace = /*#__PURE__*/_interopNamespaceDefault(path);
 
+const TERMINAL_STYLE = {
+    bold: '\x1b[1m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+};
+function styleText(text, ...styles) {
+    return `${styles.join('')}${text}${TERMINAL_STYLE.reset}`;
+}
+
 const logLevelOption = {
     long: 'logLevel',
     type: 'string',
@@ -190,14 +202,28 @@ const BUILTIN_VERSION_OPTION = {
     args: 'none',
     desc: 'Show version number',
 };
+const BUILTIN_COLOR_OPTION = {
+    long: 'color',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colored help output',
+    default: true,
+};
+function createBuiltinOptionState(enabled) {
+    return {
+        color: enabled,
+        logLevel: enabled,
+        silent: enabled,
+        logDate: enabled,
+        logColorful: enabled,
+    };
+}
+function isNoColorEnabled(envs) {
+    return envs['NO_COLOR'] !== undefined;
+}
 function normalizeBuiltinConfig(builtin) {
     const resolved = {
-        option: {
-            logLevel: true,
-            silent: true,
-            logDate: true,
-            logColorful: true,
-        },
+        option: createBuiltinOptionState(true),
         command: {
             help: false,
         },
@@ -207,26 +233,29 @@ function normalizeBuiltinConfig(builtin) {
     }
     if (builtin === true) {
         return {
-            option: { logLevel: true, silent: true, logDate: true, logColorful: true },
+            option: createBuiltinOptionState(true),
             command: { help: true },
         };
     }
     if (builtin === false) {
         return {
-            option: { logLevel: false, silent: false, logDate: false, logColorful: false },
+            option: createBuiltinOptionState(false),
             command: { help: false },
         };
     }
     if (builtin.option !== undefined) {
         if (builtin.option === false) {
-            resolved.option = { logLevel: false, silent: false, logDate: false, logColorful: false };
+            resolved.option = createBuiltinOptionState(false);
         }
         else if (builtin.option === true) {
-            resolved.option = { logLevel: true, silent: true, logDate: true, logColorful: true };
+            resolved.option = createBuiltinOptionState(true);
         }
         else {
-            if (builtin.option.logLevel !== undefined)
+            if (builtin.option.color !== undefined)
+                resolved.option.color = builtin.option.color;
+            if (builtin.option.logLevel !== undefined) {
                 resolved.option.logLevel = builtin.option.logLevel;
+            }
             if (builtin.option.silent !== undefined)
                 resolved.option.silent = builtin.option.silent;
             if (builtin.option.logDate !== undefined)
@@ -258,6 +287,7 @@ class Command {
     #parent;
     #options = [];
     #arguments = [];
+    #examples = [];
     #subcommandsList = [];
     #subcommandsMap = new Map();
     #action = undefined;
@@ -286,6 +316,9 @@ class Command {
     get arguments() {
         return [...this.#arguments];
     }
+    get examples() {
+        return this.#examples.map(example => ({ ...example }));
+    }
     get subcommands() {
         return new Map(this.#subcommandsMap);
     }
@@ -304,6 +337,10 @@ class Command {
         this.#action = fn;
         return this;
     }
+    example(title, usage, desc) {
+        this.#examples.push(this.#normalizeExample({ title, usage, desc }));
+        return this;
+    }
     subcommand(name, cmd) {
         if (this.#builtin.command.help && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
@@ -337,7 +374,8 @@ class Command {
             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')) {
-                console.log(leafCommand.formatHelp());
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
             if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
@@ -364,7 +402,8 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                console.log(leafCommand.formatHelp());
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
                 throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
@@ -397,10 +436,21 @@ class Command {
         return this.#parse(chain, resolveResult, ctx, restArgs);
     }
     formatHelp() {
-        const lines = [];
+        return this.#renderHelpPlain(this.#buildHelpData());
+    }
+    #formatHelpForDisplay(params = {}) {
+        const { color = true } = params;
+        const helpData = this.#buildHelpData();
+        if (!this.#shouldRenderStyledHelp(color)) {
+            return this.#renderHelpPlain(helpData);
+        }
+        return this.#renderHelpTerminal(helpData);
+    }
+    #shouldRenderStyledHelp(color) {
+        return color && process.stdout.isTTY === true;
+    }
+    #buildHelpData() {
         const allOptions = this.#getMergedOptions();
-        lines.push(this.#desc);
-        lines.push('');
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -418,61 +468,122 @@ class Command {
                 usage += ` [${arg.name}...]`;
             }
         }
-        lines.push(usage);
+        const options = [];
+        for (const opt of allOptions) {
+            const kebabLong = camelToKebabCase$1(opt.long);
+            let sig = opt.short ? `-${opt.short}, ` : '    ';
+            sig += `--${kebabLong}`;
+            if (opt.args !== 'none') {
+                sig += ' <value>';
+            }
+            let desc = opt.desc;
+            if (opt.default !== undefined && opt.type !== 'boolean') {
+                desc += ` (default: ${JSON.stringify(opt.default)})`;
+            }
+            if (opt.choices) {
+                desc += ` [choices: ${opt.choices.join(', ')}]`;
+            }
+            options.push({ sig, desc });
+            if (opt.type === 'boolean' && opt.args === 'none') {
+                options.push({
+                    sig: `    --no-${kebabLong}`,
+                    desc: `Negate --${kebabLong}`,
+                });
+            }
+        }
+        const commands = [];
+        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
+        if (showHelpSubcommand) {
+            commands.push({ name: 'help', desc: 'Show help for a command' });
+        }
+        for (const entry of this.#subcommandsList) {
+            let name = entry.name;
+            if (entry.aliases.length > 0) {
+                name += `, ${entry.aliases.join(', ')}`;
+            }
+            commands.push({ name, desc: entry.command.#desc });
+        }
+        const examples = this.#examples.map(example => ({
+            title: example.title,
+            usage: commandPath ? `${commandPath} ${example.usage}` : example.usage,
+            desc: example.desc,
+        }));
+        return {
+            desc: this.#desc,
+            usage,
+            options,
+            commands,
+            examples,
+        };
+    }
+    #renderHelpPlain(helpData) {
+        const lines = [];
+        lines.push(helpData.desc);
+        lines.push('');
+        lines.push(helpData.usage);
         lines.push('');
-        if (allOptions.length > 0) {
+        if (helpData.options.length > 0) {
             lines.push('Options:');
-            const optLines = [];
-            for (const opt of allOptions) {
-                const kebabLong = camelToKebabCase$1(opt.long);
-                let sig = opt.short ? `-${opt.short}, ` : '    ';
-                sig += `--${kebabLong}`;
-                if (opt.args !== 'none') {
-                    sig += ' <value>';
-                }
-                let desc = opt.desc;
-                if (opt.default !== undefined && opt.type !== 'boolean') {
-                    desc += ` (default: ${JSON.stringify(opt.default)})`;
-                }
-                if (opt.choices) {
-                    desc += ` [choices: ${opt.choices.join(', ')}]`;
-                }
-                optLines.push({ sig, desc });
-                if (opt.type === 'boolean' && opt.args === 'none') {
-                    optLines.push({
-                        sig: `    --no-${kebabLong}`,
-                        desc: `Negate --${kebabLong}`,
-                    });
-                }
-            }
-            const maxSigLen = Math.max(...optLines.map(l => l.sig.length));
-            for (const { sig, desc } of optLines) {
+            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
+            for (const { sig, desc } of helpData.options) {
                 const padding = ' '.repeat(maxSigLen - sig.length + 2);
                 lines.push(`  ${sig}${padding}${desc}`);
             }
             lines.push('');
         }
-        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
-        if (this.#subcommandsList.length > 0) {
+        if (helpData.commands.length > 0) {
             lines.push('Commands:');
-            const cmdLines = [];
-            if (showHelpSubcommand) {
-                cmdLines.push({ name: 'help', desc: 'Show help for a command' });
-            }
-            for (const entry of this.#subcommandsList) {
-                let name = entry.name;
-                if (entry.aliases.length > 0) {
-                    name += `, ${entry.aliases.join(', ')}`;
-                }
-                cmdLines.push({ name, desc: entry.command.#desc });
-            }
-            const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
-            for (const { name, desc } of cmdLines) {
+            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
+            for (const { name, desc } of helpData.commands) {
                 const padding = ' '.repeat(maxNameLen - name.length + 2);
                 lines.push(`  ${name}${padding}${desc}`);
             }
             lines.push('');
         }
+        if (helpData.examples.length > 0) {
+            lines.push('Examples:');
+            for (const example of helpData.examples) {
+                lines.push(`  - ${example.title}`);
+                lines.push(`    ${example.usage}`);
+                lines.push(`    ${example.desc}`);
+                lines.push('');
+            }
+        }
+        return lines.join('\n');
+    }
+    #renderHelpTerminal(helpData) {
+        const lines = [];
+        lines.push(helpData.desc);
+        lines.push('');
+        lines.push(styleText(helpData.usage, TERMINAL_STYLE.bold));
+        lines.push('');
+        if (helpData.options.length > 0) {
+            lines.push(styleText('Options:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
+            for (const { sig, desc } of helpData.options) {
+                const padding = ' '.repeat(maxSigLen - sig.length + 2);
+                lines.push(`  ${styleText(sig, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+            }
+            lines.push('');
+        }
+        if (helpData.commands.length > 0) {
+            lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
+            for (const { name, desc } of helpData.commands) {
+                const padding = ' '.repeat(maxNameLen - name.length + 2);
+                lines.push(`  ${styleText(name, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+            }
+            lines.push('');
+        }
+        if (helpData.examples.length > 0) {
+            lines.push(styleText('Examples:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const example of helpData.examples) {
+                lines.push(`  - ${styleText(example.title, TERMINAL_STYLE.bold)}`);
+                lines.push(`    ${styleText(example.usage, TERMINAL_STYLE.cyan)}`);
+                lines.push(`    ${styleText(example.desc, TERMINAL_STYLE.italic, TERMINAL_STYLE.dim)}`);
+                lines.push('');
+            }
+        }
         return lines.join('\n');
     }
     getCompletionMeta() {
@@ -502,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;
     }
@@ -525,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;
@@ -636,7 +777,7 @@ class Command {
             const cmd = chain[i];
             const includeVersion = i === 0;
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion);
+            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
             optsMap.set(cmd, opts);
             for (const opt of cmd.#getMergedOptions(includeVersion)) {
                 if (opt.apply && opts[opt.long] !== undefined) {
@@ -652,9 +793,10 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion) {
+    #parseOptions(tokens, includeVersion, envs) {
         const allOptions = this.#getMergedOptions(includeVersion);
         const opts = {};
+        let sawColorToken = false;
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -682,6 +824,9 @@ class Command {
                 i += 1;
                 continue;
             }
+            if (opt.long === 'color') {
+                sawColorToken = true;
+            }
             const isNegativeToken = token.original.toLowerCase().startsWith('--no-');
             if (isNegativeToken && !(opt.type === 'boolean' && opt.args === 'none')) {
                 throw new CommanderError('NegativeOptionType', `"--no-${camelToKebabCase$1(opt.long)}" can only be used with boolean options`, this.#getCommandPath());
@@ -758,6 +903,9 @@ class Command {
                 }
             }
         }
+        if (isNoColorEnabled(envs) && !sawColorToken && opts['color'] === true) {
+            opts['color'] = false;
+        }
         return opts;
     }
     #convertValue(opt, rawValue) {
@@ -830,12 +978,16 @@ class Command {
     }
     #getMergedOptions(includeVersion = !this.#parent) {
         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');
+        if (this.#builtin.option.color && !hasUserColor) {
+            optionMap.set('color', BUILTIN_COLOR_OPTION);
+        }
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
@@ -929,6 +1081,21 @@ class Command {
             }
         }
     }
+    #normalizeExample(example) {
+        const title = example.title.trim();
+        const usage = example.usage.trim();
+        const desc = example.desc.trim();
+        if (!title) {
+            throw new CommanderError('ConfigurationError', 'example title cannot be empty', this.#getCommandPath());
+        }
+        if (!usage) {
+            throw new CommanderError('ConfigurationError', 'example usage cannot be empty', this.#getCommandPath());
+        }
+        if (!desc) {
+            throw new CommanderError('ConfigurationError', 'example description cannot be empty', this.#getCommandPath());
+        }
+        return { title, usage, desc };
+    }
     async #runAction(params) {
         if (!this.#action)
             return;
@@ -945,6 +1112,34 @@ class Command {
             process.exit(1);
         }
     }
+    #resolveHelpColorOption(tokens, envs) {
+        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+        let color = !isNoColorEnabled(envs);
+        if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
+            return color;
+        }
+        for (const token of tokens) {
+            if (token.type !== 'long' || token.name !== 'color') {
+                continue;
+            }
+            const eqIdx = token.resolved.indexOf('=');
+            if (eqIdx === -1) {
+                color = true;
+                continue;
+            }
+            const value = token.resolved.slice(eqIdx + 1);
+            if (value === 'true') {
+                color = true;
+            }
+            else if (value === 'false') {
+                color = false;
+            }
+            else {
+                throw new CommanderError('InvalidBooleanValue', `invalid value "${value}" for boolean option "--color". Use "true" or "false"`, this.#getCommandPath());
+            }
+        }
+        return color;
+    }
     #hasFlag(tokens, longName, shortName) {
         for (const token of tokens) {
             if (token.type === 'long' && token.name === longName) {

package/lib/esm/index.mjs

@@ -2,6 +2,18 @@ import { LOG_LEVELS, resolveLogLevel, Reporter } from '@guanghechen/reporter';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+const TERMINAL_STYLE = {
+    bold: '\x1b[1m',
+    italic: '\x1b[3m',
+    underline: '\x1b[4m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+};
+function styleText(text, ...styles) {
+    return `${styles.join('')}${text}${TERMINAL_STYLE.reset}`;
+}
+
 const logLevelOption = {
     long: 'logLevel',
     type: 'string',
@@ -168,14 +180,28 @@ const BUILTIN_VERSION_OPTION = {
     args: 'none',
     desc: 'Show version number',
 };
+const BUILTIN_COLOR_OPTION = {
+    long: 'color',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colored help output',
+    default: true,
+};
+function createBuiltinOptionState(enabled) {
+    return {
+        color: enabled,
+        logLevel: enabled,
+        silent: enabled,
+        logDate: enabled,
+        logColorful: enabled,
+    };
+}
+function isNoColorEnabled(envs) {
+    return envs['NO_COLOR'] !== undefined;
+}
 function normalizeBuiltinConfig(builtin) {
     const resolved = {
-        option: {
-            logLevel: true,
-            silent: true,
-            logDate: true,
-            logColorful: true,
-        },
+        option: createBuiltinOptionState(true),
         command: {
             help: false,
         },
@@ -185,26 +211,29 @@ function normalizeBuiltinConfig(builtin) {
     }
     if (builtin === true) {
         return {
-            option: { logLevel: true, silent: true, logDate: true, logColorful: true },
+            option: createBuiltinOptionState(true),
             command: { help: true },
         };
     }
     if (builtin === false) {
         return {
-            option: { logLevel: false, silent: false, logDate: false, logColorful: false },
+            option: createBuiltinOptionState(false),
             command: { help: false },
         };
     }
     if (builtin.option !== undefined) {
         if (builtin.option === false) {
-            resolved.option = { logLevel: false, silent: false, logDate: false, logColorful: false };
+            resolved.option = createBuiltinOptionState(false);
         }
         else if (builtin.option === true) {
-            resolved.option = { logLevel: true, silent: true, logDate: true, logColorful: true };
+            resolved.option = createBuiltinOptionState(true);
         }
         else {
-            if (builtin.option.logLevel !== undefined)
+            if (builtin.option.color !== undefined)
+                resolved.option.color = builtin.option.color;
+            if (builtin.option.logLevel !== undefined) {
                 resolved.option.logLevel = builtin.option.logLevel;
+            }
             if (builtin.option.silent !== undefined)
                 resolved.option.silent = builtin.option.silent;
             if (builtin.option.logDate !== undefined)
@@ -236,6 +265,7 @@ class Command {
     #parent;
     #options = [];
     #arguments = [];
+    #examples = [];
     #subcommandsList = [];
     #subcommandsMap = new Map();
     #action = undefined;
@@ -264,6 +294,9 @@ class Command {
     get arguments() {
         return [...this.#arguments];
     }
+    get examples() {
+        return this.#examples.map(example => ({ ...example }));
+    }
     get subcommands() {
         return new Map(this.#subcommandsMap);
     }
@@ -282,6 +315,10 @@ class Command {
         this.#action = fn;
         return this;
     }
+    example(title, usage, desc) {
+        this.#examples.push(this.#normalizeExample({ title, usage, desc }));
+        return this;
+    }
     subcommand(name, cmd) {
         if (this.#builtin.command.help && name === 'help') {
             throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
@@ -315,7 +352,8 @@ class Command {
             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')) {
-                console.log(leafCommand.formatHelp());
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
             if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
@@ -342,7 +380,8 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                console.log(leafCommand.formatHelp());
+                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs);
+                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
                 throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
@@ -375,10 +414,21 @@ class Command {
         return this.#parse(chain, resolveResult, ctx, restArgs);
     }
     formatHelp() {
-        const lines = [];
+        return this.#renderHelpPlain(this.#buildHelpData());
+    }
+    #formatHelpForDisplay(params = {}) {
+        const { color = true } = params;
+        const helpData = this.#buildHelpData();
+        if (!this.#shouldRenderStyledHelp(color)) {
+            return this.#renderHelpPlain(helpData);
+        }
+        return this.#renderHelpTerminal(helpData);
+    }
+    #shouldRenderStyledHelp(color) {
+        return color && process.stdout.isTTY === true;
+    }
+    #buildHelpData() {
         const allOptions = this.#getMergedOptions();
-        lines.push(this.#desc);
-        lines.push('');
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -396,61 +446,122 @@ class Command {
                 usage += ` [${arg.name}...]`;
             }
         }
-        lines.push(usage);
+        const options = [];
+        for (const opt of allOptions) {
+            const kebabLong = camelToKebabCase$1(opt.long);
+            let sig = opt.short ? `-${opt.short}, ` : '    ';
+            sig += `--${kebabLong}`;
+            if (opt.args !== 'none') {
+                sig += ' <value>';
+            }
+            let desc = opt.desc;
+            if (opt.default !== undefined && opt.type !== 'boolean') {
+                desc += ` (default: ${JSON.stringify(opt.default)})`;
+            }
+            if (opt.choices) {
+                desc += ` [choices: ${opt.choices.join(', ')}]`;
+            }
+            options.push({ sig, desc });
+            if (opt.type === 'boolean' && opt.args === 'none') {
+                options.push({
+                    sig: `    --no-${kebabLong}`,
+                    desc: `Negate --${kebabLong}`,
+                });
+            }
+        }
+        const commands = [];
+        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
+        if (showHelpSubcommand) {
+            commands.push({ name: 'help', desc: 'Show help for a command' });
+        }
+        for (const entry of this.#subcommandsList) {
+            let name = entry.name;
+            if (entry.aliases.length > 0) {
+                name += `, ${entry.aliases.join(', ')}`;
+            }
+            commands.push({ name, desc: entry.command.#desc });
+        }
+        const examples = this.#examples.map(example => ({
+            title: example.title,
+            usage: commandPath ? `${commandPath} ${example.usage}` : example.usage,
+            desc: example.desc,
+        }));
+        return {
+            desc: this.#desc,
+            usage,
+            options,
+            commands,
+            examples,
+        };
+    }
+    #renderHelpPlain(helpData) {
+        const lines = [];
+        lines.push(helpData.desc);
         lines.push('');
-        if (allOptions.length > 0) {
+        lines.push(helpData.usage);
+        lines.push('');
+        if (helpData.options.length > 0) {
             lines.push('Options:');
-            const optLines = [];
-            for (const opt of allOptions) {
-                const kebabLong = camelToKebabCase$1(opt.long);
-                let sig = opt.short ? `-${opt.short}, ` : '    ';
-                sig += `--${kebabLong}`;
-                if (opt.args !== 'none') {
-                    sig += ' <value>';
-                }
-                let desc = opt.desc;
-                if (opt.default !== undefined && opt.type !== 'boolean') {
-                    desc += ` (default: ${JSON.stringify(opt.default)})`;
-                }
-                if (opt.choices) {
-                    desc += ` [choices: ${opt.choices.join(', ')}]`;
-                }
-                optLines.push({ sig, desc });
-                if (opt.type === 'boolean' && opt.args === 'none') {
-                    optLines.push({
-                        sig: `    --no-${kebabLong}`,
-                        desc: `Negate --${kebabLong}`,
-                    });
-                }
-            }
-            const maxSigLen = Math.max(...optLines.map(l => l.sig.length));
-            for (const { sig, desc } of optLines) {
+            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
+            for (const { sig, desc } of helpData.options) {
                 const padding = ' '.repeat(maxSigLen - sig.length + 2);
                 lines.push(`  ${sig}${padding}${desc}`);
             }
             lines.push('');
         }
-        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
-        if (this.#subcommandsList.length > 0) {
+        if (helpData.commands.length > 0) {
             lines.push('Commands:');
-            const cmdLines = [];
-            if (showHelpSubcommand) {
-                cmdLines.push({ name: 'help', desc: 'Show help for a command' });
-            }
-            for (const entry of this.#subcommandsList) {
-                let name = entry.name;
-                if (entry.aliases.length > 0) {
-                    name += `, ${entry.aliases.join(', ')}`;
-                }
-                cmdLines.push({ name, desc: entry.command.#desc });
-            }
-            const maxNameLen = Math.max(...cmdLines.map(l => l.name.length));
-            for (const { name, desc } of cmdLines) {
+            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
+            for (const { name, desc } of helpData.commands) {
                 const padding = ' '.repeat(maxNameLen - name.length + 2);
                 lines.push(`  ${name}${padding}${desc}`);
             }
             lines.push('');
         }
+        if (helpData.examples.length > 0) {
+            lines.push('Examples:');
+            for (const example of helpData.examples) {
+                lines.push(`  - ${example.title}`);
+                lines.push(`    ${example.usage}`);
+                lines.push(`    ${example.desc}`);
+                lines.push('');
+            }
+        }
+        return lines.join('\n');
+    }
+    #renderHelpTerminal(helpData) {
+        const lines = [];
+        lines.push(helpData.desc);
+        lines.push('');
+        lines.push(styleText(helpData.usage, TERMINAL_STYLE.bold));
+        lines.push('');
+        if (helpData.options.length > 0) {
+            lines.push(styleText('Options:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            const maxSigLen = Math.max(...helpData.options.map(line => line.sig.length));
+            for (const { sig, desc } of helpData.options) {
+                const padding = ' '.repeat(maxSigLen - sig.length + 2);
+                lines.push(`  ${styleText(sig, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+            }
+            lines.push('');
+        }
+        if (helpData.commands.length > 0) {
+            lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            const maxNameLen = Math.max(...helpData.commands.map(line => line.name.length));
+            for (const { name, desc } of helpData.commands) {
+                const padding = ' '.repeat(maxNameLen - name.length + 2);
+                lines.push(`  ${styleText(name, TERMINAL_STYLE.cyan)}${padding}${desc}`);
+            }
+            lines.push('');
+        }
+        if (helpData.examples.length > 0) {
+            lines.push(styleText('Examples:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const example of helpData.examples) {
+                lines.push(`  - ${styleText(example.title, TERMINAL_STYLE.bold)}`);
+                lines.push(`    ${styleText(example.usage, TERMINAL_STYLE.cyan)}`);
+                lines.push(`    ${styleText(example.desc, TERMINAL_STYLE.italic, TERMINAL_STYLE.dim)}`);
+                lines.push('');
+            }
+        }
         return lines.join('\n');
     }
     getCompletionMeta() {
@@ -480,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;
     }
@@ -503,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;
@@ -614,7 +755,7 @@ class Command {
             const cmd = chain[i];
             const includeVersion = i === 0;
             const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, includeVersion);
+            const opts = cmd.#parseOptions(tokens, includeVersion, ctx.envs);
             optsMap.set(cmd, opts);
             for (const opt of cmd.#getMergedOptions(includeVersion)) {
                 if (opt.apply && opts[opt.long] !== undefined) {
@@ -630,9 +771,10 @@ class Command {
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
         return { ctx, opts: mergedOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion) {
+    #parseOptions(tokens, includeVersion, envs) {
         const allOptions = this.#getMergedOptions(includeVersion);
         const opts = {};
+        let sawColorToken = false;
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -660,6 +802,9 @@ class Command {
                 i += 1;
                 continue;
             }
+            if (opt.long === 'color') {
+                sawColorToken = true;
+            }
             const isNegativeToken = token.original.toLowerCase().startsWith('--no-');
             if (isNegativeToken && !(opt.type === 'boolean' && opt.args === 'none')) {
                 throw new CommanderError('NegativeOptionType', `"--no-${camelToKebabCase$1(opt.long)}" can only be used with boolean options`, this.#getCommandPath());
@@ -736,6 +881,9 @@ class Command {
                 }
             }
         }
+        if (isNoColorEnabled(envs) && !sawColorToken && opts['color'] === true) {
+            opts['color'] = false;
+        }
         return opts;
     }
     #convertValue(opt, rawValue) {
@@ -808,12 +956,16 @@ class Command {
     }
     #getMergedOptions(includeVersion = !this.#parent) {
         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');
+        if (this.#builtin.option.color && !hasUserColor) {
+            optionMap.set('color', BUILTIN_COLOR_OPTION);
+        }
         if (!hasUserHelp) {
             optionMap.set('help', BUILTIN_HELP_OPTION);
         }
@@ -907,6 +1059,21 @@ class Command {
             }
         }
     }
+    #normalizeExample(example) {
+        const title = example.title.trim();
+        const usage = example.usage.trim();
+        const desc = example.desc.trim();
+        if (!title) {
+            throw new CommanderError('ConfigurationError', 'example title cannot be empty', this.#getCommandPath());
+        }
+        if (!usage) {
+            throw new CommanderError('ConfigurationError', 'example usage cannot be empty', this.#getCommandPath());
+        }
+        if (!desc) {
+            throw new CommanderError('ConfigurationError', 'example description cannot be empty', this.#getCommandPath());
+        }
+        return { title, usage, desc };
+    }
     async #runAction(params) {
         if (!this.#action)
             return;
@@ -923,6 +1090,34 @@ class Command {
             process.exit(1);
         }
     }
+    #resolveHelpColorOption(tokens, envs) {
+        const colorOption = this.#getMergedOptions().find(opt => opt.long === 'color');
+        let color = !isNoColorEnabled(envs);
+        if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
+            return color;
+        }
+        for (const token of tokens) {
+            if (token.type !== 'long' || token.name !== 'color') {
+                continue;
+            }
+            const eqIdx = token.resolved.indexOf('=');
+            if (eqIdx === -1) {
+                color = true;
+                continue;
+            }
+            const value = token.resolved.slice(eqIdx + 1);
+            if (value === 'true') {
+                color = true;
+            }
+            else if (value === 'false') {
+                color = false;
+            }
+            else {
+                throw new CommanderError('InvalidBooleanValue', `invalid value "${value}" for boolean option "--color". Use "true" or "false"`, this.#getCommandPath());
+            }
+        }
+        return color;
+    }
     #hasFlag(tokens, longName, shortName) {
         for (const token of tokens) {
             if (token.type === 'long' && token.name === longName) {

package/lib/types/index.d.ts

@@ -93,6 +93,8 @@ interface ICommandArgumentConfig<T = unknown> {
     coerce?: (rawValue: string) => T;
 }
 interface ICommandBuiltinOptionConfig {
+    /** Enable built-in --color/--no-color option for help rendering (defaults respect NO_COLOR) */
+    color?: boolean;
     /** Enable built-in --log-level option */
     logLevel?: boolean;
     /** Enable built-in --silent option */
@@ -112,6 +114,15 @@ interface ICommandBuiltinConfig {
     /** Built-in command configuration */
     command?: boolean | ICommandBuiltinCommandConfig;
 }
+/** Command example configuration */
+interface ICommandExample {
+    /** Example title */
+    title: string;
+    /** Usage fragment relative to command path */
+    usage: string;
+    /** Example description */
+    desc: string;
+}
 /** Command configuration */
 interface ICommandConfig {
     /** Command name (only for root command) */
@@ -133,6 +144,7 @@ interface ICommand {
     readonly parent: ICommand | undefined;
     readonly options: ICommandOptionConfig[];
     readonly arguments: ICommandArgumentConfig[];
+    readonly examples: ICommandExample[];
     readonly subcommands: Map<string, ICommand>;
 }
 /** Execution context */
@@ -212,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;
@@ -283,10 +295,12 @@ declare class Command implements ICommand {
     get parent(): Command | undefined;
     get options(): ICommandOptionConfig[];
     get arguments(): ICommandArgumentConfig[];
+    get examples(): ICommandExample[];
     get subcommands(): Map<string, ICommand>;
     option<T>(opt: ICommandOptionConfig<T>): this;
     argument<T>(arg: ICommandArgumentConfig<T>): this;
     action(fn: ICommandAction): this;
+    example(title: string, usage: string, desc: string): this;
     subcommand(name: string, cmd: Command): this;
     run(params: ICommandRunParams): Promise<void>;
     parse(params: ICommandRunParams): ICommandParseResult;
@@ -423,4 +437,4 @@ declare const logColorfulOption: ICommandOptionConfig<boolean>;
 declare const silentOption: ICommandOptionConfig<boolean>;
 
 export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandConfig, ICommandContext, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandBuiltinCommandConfig, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandConfig, ICommandContext, ICommandExample, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandShiftResult, ICommandToken, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType };

package/package.json

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