@guanghechen/commander 4.7.1 → 4.7.2

package/lib/esm/index.mjs

@@ -1,6 +1,85 @@
-import { Reporter, LOG_LEVELS, resolveLogLevel } from '@guanghechen/reporter';
-import * as fs from 'node:fs';
+import { parse } from '@guanghechen/env';
+import { Reporter } from '@guanghechen/reporter';
+import { stat, readFile } from 'node:fs/promises';
 import * as path from 'node:path';
+import path__default from 'node:path';
+import * as fs from 'node:fs';
+
+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 BUILTIN_LOG_LEVELS = ['debug', 'info', 'hint', 'warn', 'error'];
+function resolveReporterLogLevel(raw) {
+    const normalized = raw.trim().toLowerCase();
+    return BUILTIN_LOG_LEVELS.find(level => level === normalized);
+}
+function setReporterLevel(ctx, level) {
+    const reporter = ctx.reporter;
+    reporter?.setLevel?.(level);
+}
+function setReporterFlight(ctx, flight) {
+    const reporter = ctx.reporter;
+    reporter?.setFlight?.(flight);
+}
+const logLevelOption = {
+    long: 'logLevel',
+    type: 'string',
+    args: 'required',
+    desc: 'Set log level',
+    default: 'info',
+    choices: [...BUILTIN_LOG_LEVELS],
+    coerce: (raw) => {
+        const level = resolveReporterLogLevel(raw);
+        if (level === undefined) {
+            throw new Error(`Invalid log level: ${raw}`);
+        }
+        return level;
+    },
+    apply: (value, ctx) => {
+        setReporterLevel(ctx, value);
+    },
+};
+const logDateOption = {
+    long: 'logDate',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable log timestamp',
+    default: true,
+    apply: (value, ctx) => {
+        setReporterFlight(ctx, { date: Boolean(value) });
+    },
+};
+const logColorfulOption = {
+    long: 'logColorful',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colorful log output',
+    default: true,
+    apply: (value, ctx) => {
+        setReporterFlight(ctx, { color: Boolean(value) });
+    },
+};
+const silentOption = {
+    long: 'silent',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Suppress non-error output',
+    default: false,
+    apply: (value, ctx) => {
+        if (value) {
+            setReporterLevel(ctx, 'error');
+        }
+    },
+};
 
 class CommanderError extends Error {
     kind;
@@ -18,6 +97,11 @@ class CommanderError extends Error {
 
 const LONG_OPTION_REGEX = /^--[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const NEGATIVE_OPTION_REGEX = /^--no-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const PRESET_OPTS_FLAG = '--preset-opts';
+const PRESET_ENVS_FLAG = '--preset-envs';
+const PRESET_ROOT_FLAG = '--preset-root';
+const DEFAULT_PRESET_OPTS_FILENAME = '.opt.local';
+const DEFAULT_PRESET_ENVS_FILENAME = '.env.local';
 function kebabToCamelCase(str) {
     return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -105,27 +189,91 @@ function tokenize(argv, commandPath) {
 }
 const BUILTIN_HELP_OPTION = {
     long: 'help',
-    short: 'h',
     type: 'boolean',
     args: 'none',
     desc: 'Show help information',
 };
 const BUILTIN_VERSION_OPTION = {
     long: 'version',
-    short: 'V',
     type: 'boolean',
     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 {
+        version: enabled,
+        color: enabled,
+        logLevel: enabled,
+        silent: enabled,
+        logDate: enabled,
+        logColorful: enabled,
+    };
+}
+function isNoColorEnabled(envs) {
+    return envs['NO_COLOR'] !== undefined;
+}
+function normalizeBuiltinConfig(builtin) {
+    const resolved = {
+        option: createBuiltinOptionState(true),
+    };
+    if (builtin === undefined) {
+        return resolved;
+    }
+    if (builtin === true) {
+        return {
+            option: createBuiltinOptionState(true),
+        };
+    }
+    if (builtin === false) {
+        return {
+            option: createBuiltinOptionState(false),
+        };
+    }
+    if (builtin.option !== undefined) {
+        if (builtin.option === false) {
+            resolved.option = createBuiltinOptionState(false);
+        }
+        else if (builtin.option === true) {
+            resolved.option = createBuiltinOptionState(true);
+        }
+        else {
+            if (builtin.option.version !== undefined)
+                resolved.option.version = builtin.option.version;
+            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)
+                resolved.option.logDate = builtin.option.logDate;
+            if (builtin.option.logColorful !== undefined) {
+                resolved.option.logColorful = builtin.option.logColorful;
+            }
+        }
+    }
+    return resolved;
+}
 class Command {
     #name;
     #desc;
     #version;
-    #helpSubcommandEnabled;
+    #builtinConfig;
+    #builtin;
+    #presetConfig;
     #reporter;
     #parent;
     #options = [];
     #arguments = [];
+    #examples = [];
     #subcommandsList = [];
     #subcommandsMap = new Map();
     #action = undefined;
@@ -133,7 +281,9 @@ class Command {
         this.#name = config.name ?? '';
         this.#desc = config.desc;
         this.#version = config.version;
-        this.#helpSubcommandEnabled = config.help ?? false;
+        this.#builtinConfig = config.builtin;
+        this.#builtin = normalizeBuiltinConfig(config.builtin);
+        this.#presetConfig = config.preset;
         this.#reporter = config.reporter;
     }
     get name() {
@@ -145,6 +295,12 @@ class Command {
     get version() {
         return this.#version;
     }
+    get builtin() {
+        return this.#builtinConfig;
+    }
+    get preset() {
+        return this.#presetConfig === undefined ? undefined : { ...this.#presetConfig };
+    }
     get parent() {
         return this.#parent;
     }
@@ -154,6 +310,9 @@ class Command {
     get arguments() {
         return [...this.#arguments];
     }
+    get examples() {
+        return this.#examples.map(example => ({ ...example }));
+    }
     get subcommands() {
         return new Map(this.#subcommandsMap);
     }
@@ -172,15 +331,22 @@ 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.#helpSubcommandEnabled && name === 'help') {
-            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name when help subcommand is enabled', this.#getCommandPath());
+        if (name === 'help') {
+            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name', this.#getCommandPath());
         }
         if (cmd.#parent && cmd.#parent !== this) {
             throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
         }
         const existing = this.#subcommandsList.find(e => e.command === cmd);
         if (existing) {
+            if (existing.aliases.includes(name)) {
+                return this;
+            }
             existing.aliases.push(name);
             this.#subcommandsMap.set(name, cmd);
         }
@@ -195,33 +361,36 @@ class Command {
     async run(params) {
         const { argv, envs, reporter } = params;
         try {
-            const processedArgv = this.#processHelpSubcommand(argv);
-            const routeResult = this.#route(processedArgv);
-            const { chain, remaining } = routeResult;
+            const routeResult = this.#route(argv);
+            const { chain } = 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')) {
-                console.log(leafCommand.formatHelp());
+            const ctx = this.#createContext({
+                chain,
+                cmds: routeResult.cmds,
+                envs,
+                reporter,
+            });
+            const controlScanResult = this.#controlScan(routeResult.remaining, leafCommand);
+            ctx.controls = controlScanResult.controls;
+            ctx.sources.user.argv = [...controlScanResult.remaining];
+            if (ctx.controls.help) {
+                const helpCommand = this.#resolveHelpCommand(leafCommand, controlScanResult.helpTarget);
+                const helpColor = helpCommand.#resolveHelpColorFromTailArgv(controlScanResult.remaining, ctx.envs);
+                console.log(helpCommand.#formatHelpForDisplay({ color: helpColor }));
                 return;
             }
-            if (!hasUserVersion && leafCommand === rootCommand && leafCommand.#version) {
-                if (this.#hasFlag(optionTokens, 'version', 'V')) {
-                    console.log(leafCommand.#version);
-                    return;
-                }
+            if (ctx.controls.version) {
+                console.log(leafCommand.#version);
+                return;
             }
-            const resolveResult = this.#resolve(chain, optionTokens);
-            const ctx = {
-                cmd: leafCommand,
-                envs,
-                reporter: reporter ?? this.#reporter ?? new Reporter(),
-                argv,
-            };
-            const parseResult = this.#parse(chain, resolveResult, ctx, restArgs);
+            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+            const presetResult = await this.#preset(controlScanResult.remaining, ctx, optionPolicyMap);
+            ctx.sources = presetResult.sources;
+            ctx.envs = presetResult.envs;
+            const tokenizeResult = tokenize(presetResult.tailArgv, leafCommand.#getCommandPath());
+            const { optionTokens, restArgs } = tokenizeResult;
+            const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
+            const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
                 opts: parseResult.opts,
@@ -232,7 +401,8 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                console.log(leafCommand.formatHelp());
+                const helpColor = leafCommand.#resolveHelpColorFromTailArgv(presetResult.tailArgv, ctx.envs);
+                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
                 throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
@@ -247,28 +417,49 @@ class Command {
             throw err;
         }
     }
-    parse(params) {
+    async parse(params) {
         const { argv, envs, reporter } = params;
-        const processedArgv = this.#processHelpSubcommand(argv);
-        const routeResult = this.#route(processedArgv);
-        const { chain, remaining } = routeResult;
+        const routeResult = this.#route(argv);
+        const { chain } = routeResult;
         const leafCommand = chain[chain.length - 1];
-        const tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
-        const { optionTokens, restArgs } = tokenizeResult;
-        const resolveResult = this.#resolve(chain, optionTokens);
-        const ctx = {
-            cmd: leafCommand,
+        const ctx = this.#createContext({
+            chain,
+            cmds: routeResult.cmds,
             envs,
-            reporter: reporter ?? this.#reporter ?? new Reporter(),
-            argv,
-        };
-        return this.#parse(chain, resolveResult, ctx, restArgs);
+            reporter,
+        });
+        const controlScanResult = this.#controlScan(routeResult.remaining, leafCommand);
+        ctx.controls = controlScanResult.controls;
+        ctx.sources.user.argv = [...controlScanResult.remaining];
+        const optionPolicyMap = this.#buildOptionPolicyMap(chain);
+        const presetResult = await this.#preset(controlScanResult.remaining, ctx, optionPolicyMap);
+        ctx.sources = presetResult.sources;
+        ctx.envs = presetResult.envs;
+        const tokenizeResult = tokenize(presetResult.tailArgv, leafCommand.#getCommandPath());
+        const { optionTokens, restArgs } = tokenizeResult;
+        const resolveResult = this.#resolve(chain, optionTokens, optionPolicyMap);
+        return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
-        const lines = [];
-        const allOptions = this.#getMergedOptions();
-        lines.push(this.#desc);
-        lines.push('');
+        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 parseOptions = this.#resolveOptionPolicy().mergedOptions;
+        const allOptions = [...parseOptions, BUILTIN_HELP_OPTION];
+        if (this.#supportsBuiltinVersion()) {
+            allOptions.push(BUILTIN_VERSION_OPTION);
+        }
         const commandPath = this.#getCommandPath();
         let usage = `Usage: ${commandPath}`;
         if (allOptions.length > 0)
@@ -286,65 +477,128 @@ 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' &&
+                opt.long !== 'help' &&
+                opt.long !== 'version') {
+                options.push({
+                    sig: `    --no-${kebabLong}`,
+                    desc: `Negate --${kebabLong}`,
+                });
+            }
+        }
+        const commands = [];
+        if (this.#subcommandsList.length > 0) {
+            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.#helpSubcommandEnabled && 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() {
-        const allOptions = this.#getMergedOptions();
+        const allOptions = this.#resolveOptionPolicy().mergedOptions;
         const options = [];
         for (const opt of allOptions) {
             options.push({
@@ -370,46 +624,407 @@ class Command {
             }),
         };
     }
-    #processHelpSubcommand(argv) {
-        if (!this.#helpSubcommandEnabled)
-            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)];
-        }
-        return argv;
+    #findSubcommandEntry(token) {
+        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
     }
     #route(argv) {
         const chain = [this];
+        const cmds = [];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
             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;
+            cmds.push(token);
             chain.push(current);
             idx += 1;
         }
-        return { chain, remaining: argv.slice(idx) };
+        return { chain, remaining: argv.slice(idx), cmds };
+    }
+    #controlScan(tailArgv, leafCommand) {
+        const controls = { help: false, version: false };
+        const separatorIndex = tailArgv.indexOf('--');
+        const beforeSeparator = separatorIndex === -1 ? tailArgv : tailArgv.slice(0, separatorIndex);
+        const afterSeparator = separatorIndex === -1 ? [] : tailArgv.slice(separatorIndex + 1);
+        let helpTarget;
+        let scanStartIndex = 0;
+        if (beforeSeparator[0] === 'help') {
+            controls.help = true;
+            scanStartIndex = 1;
+            const candidate = beforeSeparator[1];
+            if (candidate !== undefined && !candidate.startsWith('-')) {
+                helpTarget = candidate;
+                scanStartIndex = 2;
+            }
+        }
+        const remainingBeforeSeparator = [];
+        for (let i = scanStartIndex; i < beforeSeparator.length; i += 1) {
+            const token = beforeSeparator[i];
+            if (token === '--help') {
+                controls.help = true;
+                continue;
+            }
+            if (token === '--version' && leafCommand.#supportsBuiltinVersion()) {
+                controls.version = true;
+                continue;
+            }
+            remainingBeforeSeparator.push(token);
+        }
+        const remaining = separatorIndex === -1
+            ? remainingBeforeSeparator
+            : [...remainingBeforeSeparator, '--', ...afterSeparator];
+        return {
+            controls,
+            remaining,
+            helpTarget,
+        };
+    }
+    #createContext(params) {
+        const { chain, cmds, envs, reporter } = params;
+        const leafCommand = chain[chain.length - 1];
+        const envSnapshot = { ...envs };
+        return {
+            cmd: leafCommand,
+            chain,
+            envs: envSnapshot,
+            controls: { help: false, version: false },
+            sources: {
+                preset: {
+                    argv: [],
+                    envs: {},
+                },
+                user: {
+                    cmds: [...cmds],
+                    argv: [],
+                    envs: envSnapshot,
+                },
+            },
+            reporter: reporter ?? this.#reporter ?? new Reporter(),
+        };
+    }
+    #resolveHelpCommand(leafCommand, helpTarget) {
+        if (helpTarget === undefined) {
+            return leafCommand;
+        }
+        const target = leafCommand.#findSubcommandEntry(helpTarget);
+        if (target === undefined) {
+            return leafCommand;
+        }
+        return target.command;
+    }
+    async #preset(controlTailArgv, ctx, optionPolicyMap) {
+        const commandPath = ctx.chain[ctx.chain.length - 1].#getCommandPath();
+        const separatorIndex = controlTailArgv.indexOf('--');
+        const beforeSeparator = separatorIndex === -1 ? controlTailArgv : controlTailArgv.slice(0, separatorIndex);
+        const afterSeparator = separatorIndex === -1 ? [] : controlTailArgv.slice(separatorIndex + 1);
+        const rootScanResult = this.#scanPresetRootDirectives(beforeSeparator, commandPath);
+        const commandPreset = this.#resolveCommandPresetFromChain(ctx.chain);
+        const presetRoot = await this.#resolveEffectivePresetRoot(rootScanResult.cliPresetRoots, commandPreset, commandPath);
+        const fileScanResult = this.#scanPresetFileDirectives(rootScanResult.cleanArgv, commandPath);
+        const cleanArgv = separatorIndex === -1
+            ? fileScanResult.cleanArgv
+            : [...fileScanResult.cleanArgv, '--', ...afterSeparator];
+        const presetOptsFiles = this.#resolvePresetFileSources({
+            cliFiles: fileScanResult.cliPresetOptsFiles,
+            commandPresetFile: this.#normalizeCommandPresetFile(commandPreset?.opt),
+            presetRoot,
+            defaultFilename: DEFAULT_PRESET_OPTS_FILENAME,
+        });
+        const presetEnvsFiles = this.#resolvePresetFileSources({
+            cliFiles: fileScanResult.cliPresetEnvsFiles,
+            commandPresetFile: this.#normalizeCommandPresetFile(commandPreset?.env),
+            presetRoot,
+            defaultFilename: DEFAULT_PRESET_ENVS_FILENAME,
+        });
+        const userSources = {
+            cmds: [...ctx.sources.user.cmds],
+            argv: [...cleanArgv],
+            envs: { ...ctx.sources.user.envs },
+        };
+        const presetArgv = [];
+        for (const file of presetOptsFiles) {
+            const content = await this.#readPresetFile(file, commandPath);
+            if (content === undefined) {
+                continue;
+            }
+            const tokens = this.#tokenizePresetOptions(content);
+            this.#validatePresetOptionTokens(tokens, file.displayPath, commandPath);
+            this.#assertPresetOptionFragments(tokens, file.displayPath, ctx.chain, optionPolicyMap);
+            presetArgv.push(...tokens);
+        }
+        const presetEnvs = {};
+        for (const file of presetEnvsFiles) {
+            const content = await this.#readPresetFile(file, commandPath);
+            if (content === undefined) {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = parse(content);
+            }
+            catch (error) {
+                throw new CommanderError('ConfigurationError', `failed to parse preset envs file "${file.displayPath}": ${error.message}`, commandPath);
+            }
+            Object.assign(presetEnvs, parsed);
+        }
+        const sources = {
+            user: userSources,
+            preset: {
+                argv: presetArgv,
+                envs: presetEnvs,
+            },
+        };
+        const envs = { ...sources.user.envs, ...sources.preset.envs };
+        const tailArgv = [...sources.preset.argv, ...sources.user.argv];
+        return { tailArgv, envs, sources };
+    }
+    #resolveCommandPresetFromChain(chain) {
+        for (let index = chain.length - 1; index >= 0; index -= 1) {
+            const preset = chain[index].#presetConfig;
+            if (preset?.root !== undefined) {
+                return preset;
+            }
+        }
+        return undefined;
     }
-    #resolve(chain, tokens) {
+    async #resolveEffectivePresetRoot(cliPresetRoots, commandPreset, commandPath) {
+        if (cliPresetRoots.length > 0) {
+            const root = cliPresetRoots[cliPresetRoots.length - 1];
+            return await this.#assertPresetRoot(root, PRESET_ROOT_FLAG, commandPath);
+        }
+        if (commandPreset?.root === undefined) {
+            return undefined;
+        }
+        return await this.#assertPresetRoot(commandPreset.root, 'command.preset.root', commandPath);
+    }
+    async #assertPresetRoot(root, sourceName, commandPath) {
+        if (!path__default.isAbsolute(root)) {
+            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" is not an absolute directory`, commandPath);
+        }
+        let stats;
+        try {
+            stats = await stat(root);
+        }
+        catch (error) {
+            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" cannot be accessed (${error.message})`, commandPath);
+        }
+        if (!stats.isDirectory()) {
+            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" is not a directory`, commandPath);
+        }
+        return root;
+    }
+    #normalizeCommandPresetFile(filepath) {
+        if (filepath === undefined) {
+            return undefined;
+        }
+        if (!this.#isValidPresetFileValue(filepath)) {
+            return undefined;
+        }
+        return filepath;
+    }
+    #resolvePresetFileSources(params) {
+        const { cliFiles, commandPresetFile, presetRoot, defaultFilename } = params;
+        if (cliFiles.length > 0) {
+            return cliFiles.map(filepath => ({
+                displayPath: filepath,
+                absolutePath: this.#resolvePresetFileAbsolutePath(filepath, presetRoot),
+                explicit: true,
+            }));
+        }
+        if (presetRoot === undefined) {
+            return [];
+        }
+        if (commandPresetFile !== undefined) {
+            return [
+                {
+                    displayPath: commandPresetFile,
+                    absolutePath: this.#resolvePresetFileAbsolutePath(commandPresetFile, presetRoot),
+                    explicit: true,
+                },
+            ];
+        }
+        const absolutePath = path__default.resolve(presetRoot, defaultFilename);
+        return [
+            {
+                displayPath: absolutePath,
+                absolutePath,
+                explicit: false,
+            },
+        ];
+    }
+    #resolvePresetFileAbsolutePath(filepath, presetRoot) {
+        if (path__default.isAbsolute(filepath)) {
+            return filepath;
+        }
+        if (presetRoot !== undefined) {
+            return path__default.resolve(presetRoot, filepath);
+        }
+        return path__default.resolve(process.cwd(), filepath);
+    }
+    #assertPresetOptionFragments(tokens, filepath, chain, optionPolicyMap) {
+        if (tokens.length === 0) {
+            return;
+        }
+        const commandPath = chain[chain.length - 1].#getCommandPath();
+        try {
+            const { optionTokens, restArgs } = tokenize(tokens, commandPath);
+            void restArgs;
+            const { argTokens } = this.#resolve(chain, optionTokens, optionPolicyMap);
+            if (argTokens.length > 0) {
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": token "${argTokens[0].original}" cannot be resolved as an option fragment`, commandPath);
+            }
+        }
+        catch (error) {
+            if (error instanceof CommanderError) {
+                if (error.kind === 'ConfigurationError') {
+                    throw error;
+                }
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": ${error.message}`, commandPath);
+            }
+            throw error;
+        }
+    }
+    #scanPresetRootDirectives(argv, commandPath) {
+        const cleanArgv = [];
+        const cliPresetRoots = [];
+        let index = 0;
+        while (index < argv.length) {
+            const token = argv[index];
+            if (token === PRESET_ROOT_FLAG) {
+                const value = argv[index + 1];
+                if (value === undefined || value.length === 0) {
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_ROOT_FLAG}"`, commandPath);
+                }
+                cliPresetRoots.push(value);
+                index += 2;
+                continue;
+            }
+            if (token.startsWith(`${PRESET_ROOT_FLAG}=`)) {
+                const value = token.slice(PRESET_ROOT_FLAG.length + 1);
+                if (value.length === 0) {
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_ROOT_FLAG}"`, commandPath);
+                }
+                cliPresetRoots.push(value);
+                index += 1;
+                continue;
+            }
+            cleanArgv.push(token);
+            index += 1;
+        }
+        return { cleanArgv, cliPresetRoots };
+    }
+    #scanPresetFileDirectives(argv, commandPath) {
+        const cleanArgv = [];
+        const cliPresetOptsFiles = [];
+        const cliPresetEnvsFiles = [];
+        const assertAndPush = (flag, value) => {
+            this.#assertPresetFileValue(value, flag, commandPath);
+            if (flag === PRESET_OPTS_FLAG) {
+                cliPresetOptsFiles.push(value);
+            }
+            else {
+                cliPresetEnvsFiles.push(value);
+            }
+        };
+        let index = 0;
+        while (index < argv.length) {
+            const token = argv[index];
+            if (token === PRESET_OPTS_FLAG || token === PRESET_ENVS_FLAG) {
+                const value = argv[index + 1];
+                if (value === undefined || value.length === 0) {
+                    throw new CommanderError('ConfigurationError', `missing value for "${token}"`, commandPath);
+                }
+                assertAndPush(token, value);
+                index += 2;
+                continue;
+            }
+            if (token.startsWith(`${PRESET_OPTS_FLAG}=`)) {
+                const value = token.slice(PRESET_OPTS_FLAG.length + 1);
+                if (value.length === 0) {
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_OPTS_FLAG}"`, commandPath);
+                }
+                assertAndPush(PRESET_OPTS_FLAG, value);
+                index += 1;
+                continue;
+            }
+            if (token.startsWith(`${PRESET_ENVS_FLAG}=`)) {
+                const value = token.slice(PRESET_ENVS_FLAG.length + 1);
+                if (value.length === 0) {
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_ENVS_FLAG}"`, commandPath);
+                }
+                assertAndPush(PRESET_ENVS_FLAG, value);
+                index += 1;
+                continue;
+            }
+            cleanArgv.push(token);
+            index += 1;
+        }
+        return { cleanArgv, cliPresetOptsFiles, cliPresetEnvsFiles };
+    }
+    #isValidPresetFileValue(filepath) {
+        return filepath.length > 0 && !filepath.startsWith('..');
+    }
+    #assertPresetFileValue(filepath, directive, commandPath) {
+        if (this.#isValidPresetFileValue(filepath)) {
+            return;
+        }
+        throw new CommanderError('ConfigurationError', `invalid value for "${directive}": "${filepath}" (must be non-empty and must not start with "..")`, commandPath);
+    }
+    async #readPresetFile(file, commandPath) {
+        try {
+            return await readFile(file.absolutePath, 'utf8');
+        }
+        catch (error) {
+            const ioError = error;
+            if (!file.explicit && ioError.code === 'ENOENT') {
+                return undefined;
+            }
+            throw new CommanderError('ConfigurationError', `failed to read preset file "${file.displayPath}": ${ioError.message}`, commandPath);
+        }
+    }
+    #tokenizePresetOptions(content) {
+        return content
+            .split(/\s+/)
+            .map(token => token.trim())
+            .filter(token => token.length > 0);
+    }
+    #validatePresetOptionTokens(tokens, filepath, commandPath) {
+        if (tokens.length === 0) {
+            return;
+        }
+        if (!tokens[0].startsWith('-')) {
+            throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": bare token "${tokens[0]}" cannot appear before any option token`, commandPath);
+        }
+        for (const token of tokens) {
+            if (token === '--') {
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": "--" is not allowed`, commandPath);
+            }
+            if (token === 'help' || token === '--help' || token === '--version') {
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": control token "${token}" is not allowed`, commandPath);
+            }
+            if (token === PRESET_ROOT_FLAG ||
+                token.startsWith(`${PRESET_ROOT_FLAG}=`) ||
+                token === PRESET_OPTS_FLAG ||
+                token.startsWith(`${PRESET_OPTS_FLAG}=`) ||
+                token === PRESET_ENVS_FLAG ||
+                token.startsWith(`${PRESET_ENVS_FLAG}=`)) {
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": preset directive "${token}" is not allowed`, commandPath);
+            }
+        }
+    }
+    #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) {
@@ -426,8 +1041,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();
@@ -495,34 +1109,40 @@ 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);
+            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);
                 }
             }
         }
-        const mergedOpts = {};
-        for (const cmd of chain) {
-            Object.assign(mergedOpts, optsMap.get(cmd) ?? {});
+        const leafLocalOpts = {};
+        const leafParsedOpts = optsMap.get(leafCommand) ?? {};
+        for (const opt of leafCommand.#options) {
+            if (Object.prototype.hasOwnProperty.call(leafParsedOpts, opt.long)) {
+                leafLocalOpts[opt.long] = leafParsedOpts[opt.long];
+            }
         }
         const rawArgStrings = [...argTokens.map(t => t.original), ...restArgs];
         const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
-        return { ctx, opts: mergedOpts, args, rawArgs };
+        const parseCtx = {
+            ...ctx,
+            sources: this.#freezeInputSources(ctx.sources),
+        };
+        return { ctx: parseCtx, opts: leafLocalOpts, args, rawArgs };
     }
-    #parseOptions(tokens, includeVersion) {
-        const allOptions = this.#getMergedOptions(includeVersion);
+    #parseOptions(tokens, allOptions, envs) {
         const opts = {};
+        let sawColorToken = false;
         for (const opt of allOptions) {
             if (opt.default !== undefined) {
                 opts[opt.long] = opt.default;
@@ -550,6 +1170,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());
@@ -626,6 +1249,9 @@ class Command {
                 }
             }
         }
+        if (isNoColorEnabled(envs) && !sawColorToken && opts['color'] === true) {
+            opts['color'] = false;
+        }
         return opts;
     }
     #convertValue(opt, rawValue) {
@@ -696,27 +1322,60 @@ class Command {
         }
         return raw;
     }
-    #getMergedOptions(includeVersion = !this.#parent) {
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #supportsBuiltinVersion() {
+        return this.#parent === undefined && this.#version !== undefined && this.#builtin.option.version;
+    }
+    #resolveOptionPolicy() {
         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);
+        const hasUserColor = this.#hasUserOption('color');
+        const hasUserLogLevel = this.#hasUserOption('logLevel');
+        const hasUserSilent = this.#hasUserOption('silent');
+        const hasUserLogDate = this.#hasUserOption('logDate');
+        const hasUserLogColorful = this.#hasUserOption('logColorful');
+        if (this.#builtin.option.color && !hasUserColor) {
+            optionMap.set('color', BUILTIN_COLOR_OPTION);
+        }
+        if (this.#builtin.option.logLevel && !hasUserLogLevel) {
+            optionMap.set('logLevel', logLevelOption);
         }
-        if (!hasUserVersion && includeVersion) {
-            optionMap.set('version', BUILTIN_VERSION_OPTION);
+        if (this.#builtin.option.silent && !hasUserSilent) {
+            optionMap.set('silent', silentOption);
+        }
+        if (this.#builtin.option.logDate && !hasUserLogDate) {
+            optionMap.set('logDate', logDateOption);
+        }
+        if (this.#builtin.option.logColorful && !hasUserLogColorful) {
+            optionMap.set('logColorful', logColorfulOption);
         }
         for (const opt of this.#options) {
             optionMap.set(opt.long, opt);
         }
-        return Array.from(optionMap.values());
+        return {
+            mergedOptions: Array.from(optionMap.values()),
+        };
+    }
+    #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) {
+    #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);
             }
         }
@@ -732,6 +1391,9 @@ class Command {
         }
     }
     #validateOptionConfig(opt) {
+        if (opt.long === 'help' || opt.long === 'version') {
+            throw new CommanderError('ConfigurationError', `option long name "${opt.long}" is reserved`, this.#getCommandPath());
+        }
         if (opt.type === 'boolean' && opt.args !== 'none') {
             throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" must have args: 'none'`, this.#getCommandPath());
         }
@@ -781,6 +1443,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;
@@ -797,16 +1474,51 @@ class Command {
             process.exit(1);
         }
     }
-    #hasFlag(tokens, longName, shortName) {
-        for (const token of tokens) {
-            if (token.type === 'long' && token.name === longName) {
-                return true;
+    #resolveHelpColorFromTailArgv(tailArgv, 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;
+        }
+        const separatorIndex = tailArgv.indexOf('--');
+        const scanTokens = separatorIndex === -1 ? tailArgv : tailArgv.slice(0, separatorIndex);
+        for (const token of scanTokens) {
+            if (token === '--color') {
+                color = true;
+                continue;
+            }
+            if (token === '--no-color') {
+                color = false;
+                continue;
             }
-            if (token.type === 'short' && token.name === shortName) {
-                return true;
+            if (!token.startsWith('--color=')) {
+                continue;
+            }
+            const value = token.slice('--color='.length);
+            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 false;
+        return color;
+    }
+    #freezeInputSources(sources) {
+        return Object.freeze({
+            preset: Object.freeze({
+                argv: Object.freeze([...sources.preset.argv]),
+                envs: Object.freeze({ ...sources.preset.envs }),
+            }),
+            user: Object.freeze({
+                cmds: Object.freeze([...sources.user.cmds]),
+                argv: Object.freeze([...sources.user.argv]),
+                envs: Object.freeze({ ...sources.user.envs }),
+            }),
+        });
     }
     #getCommandPath() {
         const parts = [];
@@ -821,13 +1533,166 @@ class Command {
     }
 }
 
+function isIpv4(rawValue) {
+    const parts = rawValue.split('.');
+    if (parts.length !== 4) {
+        return false;
+    }
+    for (const part of parts) {
+        if (part.length < 1 || !/^\d+$/.test(part)) {
+            return false;
+        }
+        if (part.length > 1 && part.startsWith('0')) {
+            return false;
+        }
+        const value = Number(part);
+        if (!Number.isInteger(value) || value < 0 || value > 255) {
+            return false;
+        }
+    }
+    return true;
+}
+function countIpv6Segments(part, allowIpv4Tail) {
+    if (!part) {
+        return { count: 0, hasIpv4Tail: false };
+    }
+    const segments = part.split(':');
+    let count = 0;
+    let hasIpv4Tail = false;
+    for (let i = 0; i < segments.length; ++i) {
+        const segment = segments[i];
+        const isLastSegment = i === segments.length - 1;
+        if (!segment) {
+            return null;
+        }
+        if (segment.includes('.')) {
+            if (!allowIpv4Tail || !isLastSegment || hasIpv4Tail || !isIpv4(segment)) {
+                return null;
+            }
+            hasIpv4Tail = true;
+            count += 2;
+            continue;
+        }
+        if (!/^[0-9A-Fa-f]{1,4}$/.test(segment)) {
+            return null;
+        }
+        count += 1;
+    }
+    return { count, hasIpv4Tail };
+}
+function isIpv6(rawValue) {
+    if (!rawValue || !/^[0-9A-Fa-f:.]+$/.test(rawValue)) {
+        return false;
+    }
+    const doubleColonCount = rawValue.split('::').length - 1;
+    if (doubleColonCount > 1) {
+        return false;
+    }
+    if (doubleColonCount === 0) {
+        const full = countIpv6Segments(rawValue, true);
+        return full !== null && full.count === 8;
+    }
+    const [left, right] = rawValue.split('::');
+    const leftPart = countIpv6Segments(left, right.length === 0);
+    const rightPart = countIpv6Segments(right, true);
+    if (!leftPart || !rightPart) {
+        return false;
+    }
+    const totalSegments = leftPart.count + rightPart.count;
+    return totalSegments < 8;
+}
+function isIp(rawValue) {
+    return isIpv4(rawValue) || isIpv6(rawValue);
+}
+function isDomain(rawValue) {
+    if (rawValue.length < 1 || rawValue.length > 253 || rawValue.endsWith('.')) {
+        return false;
+    }
+    const labels = rawValue.split('.');
+    if (labels.length < 2) {
+        return false;
+    }
+    if (labels.some(label => label.length < 1 || label.length > 63)) {
+        return false;
+    }
+    const labelPattern = /^[A-Za-z0-9-]+$/;
+    if (labels.some(label => !labelPattern.test(label) || label.startsWith('-') || label.endsWith('-'))) {
+        return false;
+    }
+    const topLevelLabel = labels[labels.length - 1];
+    return /[A-Za-z]/.test(topLevelLabel);
+}
+
+class Coerce {
+    constructor() { }
+    static create(name, expectedType, validator, errorMessage) {
+        return (rawValue) => {
+            const value = Number(rawValue);
+            if (!validator(value)) {
+                throw new Error(errorMessage ?? `${name} is expected as ${expectedType}, but got ${rawValue}`);
+            }
+            return value;
+        };
+    }
+    static choice(name, values, errorMessage) {
+        return (rawValue) => {
+            if (values.includes(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as one of [${values.join(', ')}], but got ${rawValue}`);
+        };
+    }
+    static domain(name, errorMessage) {
+        return (rawValue) => {
+            if (isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid domain, but got ${rawValue}`);
+        };
+    }
+    static host(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue) || isDomain(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid host (IP or domain), but got ${rawValue}`);
+        };
+    }
+    static integer(name, errorMessage) {
+        return this.create(name, 'an integer', value => Number.isInteger(value), errorMessage);
+    }
+    static ip(name, errorMessage) {
+        return (rawValue) => {
+            if (isIp(rawValue)) {
+                return rawValue;
+            }
+            throw new Error(errorMessage ?? `${name} is expected as a valid IP address, but got ${rawValue}`);
+        };
+    }
+    static number(name, errorMessage) {
+        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    }
+    static port(name, errorMessage) {
+        return this.create(name, 'a valid port number (0-65535)', value => Number.isInteger(value) && value >= 0 && value <= 65535, errorMessage);
+    }
+    static positiveInteger(name, errorMessage) {
+        return this.create(name, 'a positive integer', value => Number.isInteger(value) && value > 0, errorMessage);
+    }
+    static positiveNumber(name, errorMessage) {
+        return this.create(name, 'a positive number', value => Number.isFinite(value) && value > 0, errorMessage);
+    }
+}
+
 function camelToKebabCase(str) {
     return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
 }
 class CompletionCommand extends Command {
-    constructor(root, config) {
-        const paths = config.paths;
+    constructor(root, config = {}) {
         const programName = config.programName ?? root.name ?? 'program';
+        const paths = {
+            ...createDefaultCompletionPaths(programName),
+            ...config.paths,
+        };
         super({ desc: 'Generate shell completion script' });
         this.option({
             long: 'bash',
@@ -902,6 +1767,13 @@ class CompletionCommand extends Command {
         });
     }
 }
+function createDefaultCompletionPaths(programName) {
+    return {
+        bash: `~/.local/share/bash-completion/completions/${programName}`,
+        fish: `~/.config/fish/completions/${programName}.fish`,
+        pwsh: '~/.config/powershell/Microsoft.PowerShell_profile.ps1',
+    };
+}
 function expandHome(filepath) {
     if (filepath.startsWith('~/') || filepath === '~') {
         const home = process.env['HOME'] || process.env['USERPROFILE'] || '';
@@ -1179,30 +2051,4 @@ class PwshCompletion {
     }
 }
 
-const logLevelOption = {
-    long: 'logLevel',
-    type: 'string',
-    args: 'required',
-    desc: 'Set log level',
-    default: 'info',
-    choices: LOG_LEVELS,
-    coerce: (raw) => {
-        const level = resolveLogLevel(raw);
-        if (level === undefined) {
-            throw new Error(`Invalid log level: ${raw}`);
-        }
-        return level;
-    },
-    apply: (value, ctx) => {
-        ctx.reporter.setLevel(value);
-    },
-};
-const silentOption = {
-    long: 'silent',
-    type: 'boolean',
-    args: 'none',
-    desc: 'Suppress non-error output',
-    default: false,
-};
-
-export { BashCompletion, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logLevelOption, silentOption };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };