@guanghechen/commander 4.5.0 → 4.6.0

package/lib/esm/index.mjs

@@ -1,6 +1,9 @@
-import { LOG_LEVELS, resolveLogLevel, Reporter } 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',
@@ -14,22 +17,35 @@ 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: LOG_LEVELS,
+    choices: [...BUILTIN_LOG_LEVELS],
     coerce: (raw) => {
-        const level = resolveLogLevel(raw);
+        const level = resolveReporterLogLevel(raw);
         if (level === undefined) {
             throw new Error(`Invalid log level: ${raw}`);
         }
         return level;
     },
     apply: (value, ctx) => {
-        ctx.reporter.setLevel(value);
+        setReporterLevel(ctx, value);
     },
 };
 const logDateOption = {
@@ -39,7 +55,7 @@ const logDateOption = {
     desc: 'Enable log timestamp',
     default: true,
     apply: (value, ctx) => {
-        ctx.reporter.setFlight({ date: Boolean(value) });
+        setReporterFlight(ctx, { date: Boolean(value) });
     },
 };
 const logColorfulOption = {
@@ -49,7 +65,7 @@ const logColorfulOption = {
     desc: 'Enable colorful log output',
     default: true,
     apply: (value, ctx) => {
-        ctx.reporter.setFlight({ color: Boolean(value) });
+        setReporterFlight(ctx, { color: Boolean(value) });
     },
 };
 const silentOption = {
@@ -60,7 +76,7 @@ const silentOption = {
     default: false,
     apply: (value, ctx) => {
         if (value) {
-            ctx.reporter.setLevel('error');
+            setReporterLevel(ctx, 'error');
         }
     },
 };
@@ -81,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());
 }
@@ -168,14 +189,12 @@ 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',
@@ -189,6 +208,7 @@ const BUILTIN_COLOR_OPTION = {
 };
 function createBuiltinOptionState(enabled) {
     return {
+        version: enabled,
         color: enabled,
         logLevel: enabled,
         silent: enabled,
@@ -202,9 +222,6 @@ function isNoColorEnabled(envs) {
 function normalizeBuiltinConfig(builtin) {
     const resolved = {
         option: createBuiltinOptionState(true),
-        command: {
-            help: false,
-        },
     };
     if (builtin === undefined) {
         return resolved;
@@ -212,13 +229,11 @@ function normalizeBuiltinConfig(builtin) {
     if (builtin === true) {
         return {
             option: createBuiltinOptionState(true),
-            command: { help: true },
         };
     }
     if (builtin === false) {
         return {
             option: createBuiltinOptionState(false),
-            command: { help: false },
         };
     }
     if (builtin.option !== undefined) {
@@ -229,6 +244,8 @@ function normalizeBuiltinConfig(builtin) {
             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) {
@@ -243,24 +260,15 @@ function normalizeBuiltinConfig(builtin) {
             }
         }
     }
-    if (builtin.command !== undefined) {
-        if (builtin.command === false) {
-            resolved.command = { help: false };
-        }
-        else if (builtin.command === true) {
-            resolved.command = { help: true };
-        }
-        else if (builtin.command.help !== undefined) {
-            resolved.command.help = builtin.command.help;
-        }
-    }
     return resolved;
 }
 class Command {
     #name;
     #desc;
     #version;
+    #builtinConfig;
     #builtin;
+    #presetConfig;
     #reporter;
     #parent;
     #options = [];
@@ -273,7 +281,9 @@ class Command {
         this.#name = config.name ?? '';
         this.#desc = config.desc;
         this.#version = config.version;
+        this.#builtinConfig = config.builtin;
         this.#builtin = normalizeBuiltinConfig(config.builtin);
+        this.#presetConfig = config.preset;
         this.#reporter = config.reporter;
     }
     get name() {
@@ -285,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;
     }
@@ -320,14 +336,17 @@ class Command {
         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());
+        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);
         }
@@ -342,32 +361,35 @@ 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 tokenizeResult = tokenize(remaining, leafCommand.#getCommandPath());
-            const { optionTokens, restArgs } = tokenizeResult;
-            const optionPolicyMap = this.#buildOptionPolicyMap(chain);
-            const leafPolicy = this.#mustGetOptionPolicy(optionPolicyMap, leafCommand);
-            if (leafPolicy.enableBuiltinHelp && this.#hasFlag(optionTokens, 'help', 'h')) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
-                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
+            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 (leafPolicy.enableBuiltinVersion) {
-                if (this.#hasFlag(optionTokens, 'version', 'V')) {
-                    console.log(leafCommand.#version);
-                    return;
-                }
+            if (ctx.controls.version) {
+                console.log(leafCommand.#version);
+                return;
             }
+            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 ctx = {
-                cmd: leafCommand,
-                envs,
-                reporter: reporter ?? this.#reporter ?? new Reporter(),
-                argv,
-            };
             const parseResult = this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
             const actionParams = {
                 ctx: parseResult.ctx,
@@ -379,7 +401,7 @@ class Command {
                 await leafCommand.#runAction(actionParams);
             }
             else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorOption(optionTokens, envs, leafPolicy);
+                const helpColor = leafCommand.#resolveHelpColorFromTailArgv(presetResult.tailArgv, ctx.envs);
                 console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
             }
             else {
@@ -395,22 +417,27 @@ 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 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];
         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 ctx = {
-            cmd: leafCommand,
-            envs,
-            reporter: reporter ?? this.#reporter ?? new Reporter(),
-            argv,
-        };
         return this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
     }
     formatHelp() {
@@ -428,7 +455,11 @@ class Command {
         return color && process.stdout.isTTY === true;
     }
     #buildHelpData() {
-        const allOptions = this.#resolveOptionPolicy().mergedOptions;
+        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)
@@ -462,7 +493,10 @@ class Command {
                 desc += ` [choices: ${opt.choices.join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' && opt.args === 'none') {
+            if (opt.type === 'boolean' &&
+                opt.args === 'none' &&
+                opt.long !== 'help' &&
+                opt.long !== 'version') {
                 options.push({
                     sig: `    --no-${kebabLong}`,
                     desc: `Negate --${kebabLong}`,
@@ -470,8 +504,7 @@ class Command {
             }
         }
         const commands = [];
-        const showHelpSubcommand = this.#builtin.command.help && this.#subcommandsList.length > 0;
-        if (showHelpSubcommand) {
+        if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
         for (const entry of this.#subcommandsList) {
@@ -594,50 +627,9 @@ 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) {
-        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;
-    }
     #route(argv) {
         const chain = [this];
+        const cmds = [];
         let current = this;
         let idx = 0;
         while (idx < argv.length) {
@@ -648,10 +640,382 @@ class Command {
             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;
+    }
+    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();
@@ -761,13 +1125,20 @@ class Command {
                 }
             }
         }
-        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, allOptions, envs) {
         const opts = {};
@@ -954,29 +1325,19 @@ class Command {
     #hasUserOption(long) {
         return this.#options.some(option => option.long === long);
     }
-    #canUseBuiltinVersion() {
-        return this.#version !== undefined;
+    #supportsBuiltinVersion() {
+        return this.#parent === undefined && this.#version !== undefined && this.#builtin.option.version;
     }
     #resolveOptionPolicy() {
         const optionMap = new Map();
         const hasUserColor = this.#hasUserOption('color');
-        const hasUserHelp = this.#hasUserOption('help');
-        const hasUserVersion = this.#hasUserOption('version');
         const hasUserLogLevel = this.#hasUserOption('logLevel');
         const hasUserSilent = this.#hasUserOption('silent');
         const hasUserLogDate = this.#hasUserOption('logDate');
         const hasUserLogColorful = this.#hasUserOption('logColorful');
-        const enableBuiltinHelp = !hasUserHelp;
-        const enableBuiltinVersion = !hasUserVersion && this.#canUseBuiltinVersion();
         if (this.#builtin.option.color && !hasUserColor) {
             optionMap.set('color', BUILTIN_COLOR_OPTION);
         }
-        if (enableBuiltinHelp) {
-            optionMap.set('help', BUILTIN_HELP_OPTION);
-        }
-        if (enableBuiltinVersion) {
-            optionMap.set('version', BUILTIN_VERSION_OPTION);
-        }
         if (this.#builtin.option.logLevel && !hasUserLogLevel) {
             optionMap.set('logLevel', logLevelOption);
         }
@@ -994,8 +1355,6 @@ class Command {
         }
         return {
             mergedOptions: Array.from(optionMap.values()),
-            enableBuiltinHelp,
-            enableBuiltinVersion,
         };
     }
     #buildOptionPolicyMap(chain) {
@@ -1032,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());
         }
@@ -1112,22 +1474,27 @@ class Command {
             process.exit(1);
         }
     }
-    #resolveHelpColorOption(tokens, envs, policy = this.#resolveOptionPolicy()) {
+    #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;
         }
-        for (const token of tokens) {
-            if (token.type !== 'long' || token.name !== '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;
             }
-            const eqIdx = token.resolved.indexOf('=');
-            if (eqIdx === -1) {
-                color = true;
+            if (token === '--no-color') {
+                color = false;
+                continue;
+            }
+            if (!token.startsWith('--color=')) {
                 continue;
             }
-            const value = token.resolved.slice(eqIdx + 1);
+            const value = token.slice('--color='.length);
             if (value === 'true') {
                 color = true;
             }
@@ -1140,16 +1507,18 @@ class Command {
         }
         return color;
     }
-    #hasFlag(tokens, longName, shortName) {
-        for (const token of tokens) {
-            if (token.type === 'long' && token.name === longName) {
-                return true;
-            }
-            if (token.type === 'short' && token.name === shortName) {
-                return true;
-            }
-        }
-        return false;
+    #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 = [];
@@ -1164,6 +1533,96 @@ 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) {
@@ -1175,12 +1634,47 @@ class Coerce {
             return value;
         };
     }
-    static number(name, errorMessage) {
-        return this.create(name, 'a finite number', value => Number.isFinite(value), errorMessage);
+    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);
     }
@@ -1193,9 +1687,12 @@ 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',
@@ -1270,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'] || '';
@@ -1547,4 +2051,4 @@ class PwshCompletion {
     }
 }
 
-export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, logColorfulOption, logDateOption, logLevelOption, silentOption };
+export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, silentOption };