@guanghechen/commander 4.7.7 → 4.7.9

package/lib/esm/browser.mjs

@@ -1,5 +1,5 @@
-import { parse } from '@guanghechen/env';
 import { Reporter } from '@guanghechen/reporter';
+import { parse } from '@guanghechen/env';
 
 const WINDOWS_DRIVE_ABSOLUTE_REGEX = /^[a-zA-Z]:[\\/]/;
 function isAbsolutePath(filepath) {
@@ -79,608 +79,1164 @@ function setDefaultCommandRuntime(runtime) {
     defaultRuntime = runtime;
 }
 
-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;
     commandPath;
-    constructor(kind, message, commandPath) {
+    meta;
+    constructor(kind, message, commandPath, meta) {
         super(message);
         this.name = 'CommanderError';
         this.kind = kind;
         this.commandPath = commandPath;
+        this.meta = meta;
+    }
+    withIssue(issue) {
+        return this.withIssues([issue]);
+    }
+    withIssues(issues) {
+        if (issues.length === 0) {
+            return this;
+        }
+        const nextMeta = {
+            commandPath: this.meta?.commandPath ?? this.commandPath,
+            token: this.meta?.token,
+            option: this.meta?.option,
+            argument: this.meta?.argument,
+            issues: [...(this.meta?.issues ?? []), ...issues],
+        };
+        return new CommanderError(this.kind, this.message, this.commandPath, nextMeta);
     }
     format() {
+        const issues = this.meta?.issues ?? [];
+        if (issues.length > 0) {
+            const primary = issues.find(issue => issue.kind === 'error') ?? issues[0];
+            const lines = [`Error: ${primary.reason.message}`];
+            for (const issue of issues) {
+                if (issue.kind !== 'hint')
+                    continue;
+                const message = issue.reason.message.startsWith('Hint:')
+                    ? issue.reason.message
+                    : `Hint: ${issue.reason.message}`;
+                lines.push(message);
+            }
+            lines.push(`Run "${this.commandPath} --help" for usage.`);
+            return lines.join('\n');
+        }
         return `Error: ${this.message}\nRun "${this.commandPath} --help" for usage.`;
     }
 }
 
-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_FILE_FLAG = '--preset-file';
-const PRESET_PROFILE_FLAG = '--preset-profile';
-const PRESET_SELECTOR_DELIMITER = ':';
-function kebabToCamelCase(str) {
-    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
-}
-function camelToKebabCase(str) {
-    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
-}
-const ANSI_ESCAPE_REGEX = new RegExp(String.raw `\\x1B\\[[0-?]*[ -/]*[@-~]`, 'g');
-const DECIMAL_INTEGER_REGEX = /^\d(?:_?\d)*$/;
-const DECIMAL_FRACTION_REGEX = /^\d(?:_?\d)*$/;
-const DECIMAL_EXPONENT_REGEX = /^[eE][+-]?\d(?:_?\d)*$/;
-const BINARY_LITERAL_REGEX = /^0[bB][01](?:_?[01])*$/;
-const OCTAL_LITERAL_REGEX = /^0[oO][0-7](?:_?[0-7])*$/;
-const HEX_LITERAL_REGEX = /^0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*$/;
-const PRESET_PROFILE_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const PRESET_VARIANT_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-function stripAnsi(value) {
-    return value.replace(ANSI_ESCAPE_REGEX, '');
-}
-function isCombiningMark(codePoint) {
-    return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
-        (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
-        (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
-        (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
-        (codePoint >= 0xfe20 && codePoint <= 0xfe2f));
-}
-function isWideCodePoint(codePoint) {
-    if (codePoint < 0x1100) {
-        return false;
+async function runCommandAction(params) {
+    const { action, actionParams, commandPath } = params;
+    if (action === undefined) {
+        return;
     }
-    return (codePoint <= 0x115f ||
-        codePoint === 0x2329 ||
-        codePoint === 0x232a ||
-        (codePoint >= 0x2e80 && codePoint <= 0x3247 && codePoint !== 0x303f) ||
-        (codePoint >= 0x3250 && codePoint <= 0x4dbf) ||
-        (codePoint >= 0x4e00 && codePoint <= 0xa4c6) ||
-        (codePoint >= 0xa960 && codePoint <= 0xa97c) ||
-        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
-        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
-        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
-        (codePoint >= 0xfe30 && codePoint <= 0xfe6b) ||
-        (codePoint >= 0xff01 && codePoint <= 0xff60) ||
-        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
-        (codePoint >= 0x1b000 && codePoint <= 0x1b001) ||
-        (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
-        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
-}
-function getDisplayWidth(value) {
-    const normalized = stripAnsi(value).normalize('NFC');
-    let width = 0;
-    for (const char of normalized) {
-        const codePoint = char.codePointAt(0);
-        if (codePoint === undefined || isCombiningMark(codePoint)) {
-            continue;
+    try {
+        await action(actionParams);
+    }
+    catch (err) {
+        if (err instanceof CommanderError) {
+            throw err;
         }
-        width += isWideCodePoint(codePoint) ? 2 : 1;
+        const issue = {
+            kind: 'error',
+            stage: 'run',
+            scope: 'action',
+            reason: {
+                code: 'action_failed',
+                message: err instanceof Error ? err.message : 'action failed',
+                details: err instanceof Error
+                    ? {
+                        errorName: err.name,
+                        errorMessage: err.message,
+                    }
+                    : {
+                        errorValue: String(err),
+                    },
+            },
+        };
+        throw new CommanderError('ActionFailed', err instanceof Error ? err.message : 'action failed', commandPath).withIssue(issue);
     }
-    return width;
 }
-function padDisplayEnd(value, targetWidth) {
-    const width = getDisplayWidth(value);
-    if (width >= targetWidth) {
-        return value;
+
+const BUILTIN_HELP_OPTION = {
+    long: 'help',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Show help information',
+};
+const BUILTIN_VERSION_OPTION = {
+    long: 'version',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Show version number',
+};
+function errorKindToIssueScope(kind) {
+    switch (kind) {
+        case 'UnknownSubcommand':
+            return 'command';
+        case 'MissingRequiredArgument':
+        case 'TooManyArguments':
+        case 'UnexpectedArgument':
+            return 'argument';
+        case 'ActionFailed':
+            return 'action';
+        case 'ConfigurationError':
+            return 'runtime';
+        default:
+            return 'option';
     }
-    return value + ' '.repeat(targetWidth - width);
 }
-function isValidPrimitiveNumberLiteral(rawValue) {
-    if (rawValue.trim() !== rawValue || rawValue.length === 0) {
-        return false;
-    }
-    if (rawValue === 'NaN' || rawValue === 'Infinity' || rawValue === '-Infinity') {
-        return false;
-    }
-    if (BINARY_LITERAL_REGEX.test(rawValue)) {
-        return true;
-    }
-    if (OCTAL_LITERAL_REGEX.test(rawValue)) {
-        return true;
-    }
-    if (HEX_LITERAL_REGEX.test(rawValue)) {
-        return true;
+function createBuiltinOptionState(enabled) {
+    return {
+        version: enabled,
+        color: enabled,
+        devmode: enabled,
+        logLevel: enabled,
+        silent: enabled,
+        logDate: enabled,
+        logColorful: enabled,
+    };
+}
+function normalizeBuiltinConfig(builtin) {
+    const resolved = {
+        option: createBuiltinOptionState(true),
+    };
+    if (builtin === undefined) {
+        return resolved;
     }
-    const sign = rawValue[0] === '+' || rawValue[0] === '-' ? rawValue[0] : '';
-    const body = sign ? rawValue.slice(1) : rawValue;
-    if (body.length === 0) {
-        return false;
+    if (builtin === true) {
+        return {
+            option: createBuiltinOptionState(true),
+        };
     }
-    const expIndex = body.search(/[eE]/);
-    const basePart = expIndex === -1 ? body : body.slice(0, expIndex);
-    const expPart = expIndex === -1 ? '' : body.slice(expIndex);
-    if (expPart && !DECIMAL_EXPONENT_REGEX.test(expPart)) {
-        return false;
+    if (builtin === false) {
+        return {
+            option: createBuiltinOptionState(false),
+        };
     }
-    if (basePart.includes('.')) {
-        const decimalParts = basePart.split('.');
-        if (decimalParts.length !== 2) {
-            return false;
+    if (builtin.option !== undefined) {
+        if (builtin.option === false) {
+            resolved.option = createBuiltinOptionState(false);
         }
-        const [intPart, fracPart] = decimalParts;
-        const intOk = intPart.length === 0 || DECIMAL_INTEGER_REGEX.test(intPart);
-        const fracOk = fracPart.length === 0 || DECIMAL_FRACTION_REGEX.test(fracPart);
-        if (!intOk || !fracOk) {
-            return 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.devmode !== undefined)
+                resolved.option.devmode = builtin.option.devmode;
+            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 intPart.length > 0 || fracPart.length > 0;
     }
-    return DECIMAL_INTEGER_REGEX.test(basePart);
+    return resolved;
 }
-function parsePrimitiveNumber(rawValue) {
-    if (!isValidPrimitiveNumberLiteral(rawValue)) {
-        return undefined;
-    }
-    const normalized = rawValue.replaceAll('_', '');
-    const value = Number(normalized);
-    if (!Number.isFinite(value)) {
-        return undefined;
-    }
-    return value;
+
+function createCommandContext(params) {
+    const { leafCommand, chain, cmds, envs, reporter } = params;
+    const envSnapshot = { ...envs };
+    return {
+        cmd: leafCommand,
+        chain,
+        envs: envSnapshot,
+        controls: { help: false, version: false },
+        sources: {
+            preset: {
+                state: 'none',
+                argv: [],
+                envs: {},
+            },
+            user: {
+                cmds: [...cmds],
+                argv: [],
+                envs: envSnapshot,
+            },
+        },
+        reporter,
+    };
 }
-function normalizeSubcommandNameForDistance(name) {
-    return camelToKebabCase(name).toLowerCase();
+function freezeInputSources(sources) {
+    return Object.freeze({
+        preset: Object.freeze({
+            state: sources.preset.state,
+            argv: Object.freeze([...sources.preset.argv]),
+            envs: Object.freeze({ ...sources.preset.envs }),
+            meta: sources.preset.meta === undefined ? undefined : Object.freeze({ ...sources.preset.meta }),
+        }),
+        user: Object.freeze({
+            cmds: Object.freeze([...sources.user.cmds]),
+            argv: Object.freeze([...sources.user.argv]),
+            envs: Object.freeze({ ...sources.user.envs }),
+        }),
+    });
 }
-function levenshteinDistance(left, right) {
-    if (left === right) {
-        return 0;
-    }
-    if (left.length === 0) {
-        return right.length;
-    }
-    if (right.length === 0) {
-        return left.length;
+
+function buildHelpSubcommands(params) {
+    const { entries, getDescription } = params;
+    return entries.map(entry => ({
+        name: entry.name,
+        aliases: entry.aliases,
+        desc: getDescription(entry.command),
+    }));
+}
+function buildCompletionMeta(params) {
+    const { name, desc, mergedOptions, arguments_, supportsBuiltinVersion, builtinHelpOption, builtinVersionOption, subcommands, resolveSubcommandMeta, } = params;
+    const optionMap = new Map();
+    for (const option of mergedOptions) {
+        optionMap.set(option.long, option);
+    }
+    optionMap.set('help', builtinHelpOption);
+    if (supportsBuiltinVersion) {
+        optionMap.set('version', builtinVersionOption);
+    }
+    const options = Array.from(optionMap.values()).map(option => ({
+        long: option.long,
+        short: option.short,
+        desc: option.desc,
+        type: option.type,
+        args: option.args,
+        choices: option.choices?.map(choice => String(choice)),
+    }));
+    const argumentsMeta = arguments_.map(argument => ({
+        name: argument.name,
+        kind: argument.kind,
+        type: argument.type,
+        choices: argument.type === 'choice' ? argument.choices?.map(choice => String(choice)) : undefined,
+    }));
+    return {
+        name,
+        desc,
+        aliases: [],
+        options,
+        arguments: argumentsMeta,
+        subcommands: subcommands.map(entry => {
+            const subMeta = resolveSubcommandMeta(entry.command);
+            return {
+                ...subMeta,
+                name: entry.name,
+                aliases: entry.aliases,
+            };
+        }),
+    };
+}
+
+function resolvePresetFileAbsolutePath(params) {
+    const { runtime, filepath, baseDirectory } = params;
+    if (runtime.isAbsolute(filepath)) {
+        return filepath;
     }
-    let prev = Array.from({ length: right.length + 1 }, (_, i) => i);
-    for (let i = 0; i < left.length; i += 1) {
-        const current = [i + 1];
-        for (let j = 0; j < right.length; j += 1) {
-            const substitutionCost = left[i] === right[j] ? 0 : 1;
-            current[j + 1] = Math.min(current[j] + 1, prev[j + 1] + 1, prev[j] + substitutionCost);
+    return runtime.resolve(baseDirectory ?? runtime.cwd(), filepath);
+}
+async function readPresetFile(params) {
+    const { runtime, file, commandPath } = params;
+    try {
+        const stats = await runtime.stat(file.absolutePath);
+        if (stats.isDirectory()) {
+            throw new Error('target is a directory');
+        }
+        return await runtime.readFile(file.absolutePath);
+    }
+    catch (error) {
+        const ioError = error;
+        if (!file.explicit && ioError.code === 'ENOENT') {
+            return undefined;
         }
-        prev = current;
+        throw new CommanderError('ConfigurationError', `failed to read preset file "${file.displayPath}": ${error.message}`, commandPath);
     }
-    return prev[right.length];
 }
-function tokenizeLongOption(arg, commandPath) {
-    const eqIdx = arg.indexOf('=');
-    const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
-    const valuePart = eqIdx !== -1 ? arg.slice(eqIdx) : '';
-    if (namePart.includes('_')) {
-        throw new CommanderError('InvalidOptionFormat', `invalid option "${arg}": use '-' instead of '_'`, commandPath);
+function parsePresetEnvsContent(params) {
+    const { content, file, commandPath } = params;
+    try {
+        return parse(content);
     }
-    const lowerName = namePart.toLowerCase();
-    if (lowerName === '--no' || lowerName === '--no-') {
-        throw new CommanderError('InvalidNegativeOption', `invalid negative option syntax "${arg}"`, commandPath);
+    catch (error) {
+        throw new CommanderError('ConfigurationError', `failed to parse preset env file "${file.displayPath}": ${error.message}`, commandPath);
     }
-    if (lowerName.startsWith('--no-')) {
-        if (valuePart !== '') {
-            throw new CommanderError('NegativeOptionWithValue', `"${namePart}" does not accept a value`, commandPath);
-        }
-        if (!NEGATIVE_OPTION_REGEX.test(lowerName)) {
-            throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
+}
+async function buildPresetProfileInputs(params) {
+    const { runtime, commandPath, resolvedProfile, validatePresetOptionTokens } = params;
+    const presetArgv = [];
+    if (resolvedProfile !== undefined && resolvedProfile.optsArgv.length > 0) {
+        validatePresetOptionTokens(resolvedProfile.optsArgv, resolvedProfile.optsSourceLabel, commandPath);
+        presetArgv.push(...resolvedProfile.optsArgv);
+    }
+    const presetEnvs = {};
+    if (resolvedProfile !== undefined) {
+        if (resolvedProfile.profileEnvFileSource !== undefined) {
+            const content = await readPresetFile({
+                runtime,
+                file: resolvedProfile.profileEnvFileSource,
+                commandPath,
+            });
+            if (content !== undefined) {
+                Object.assign(presetEnvs, parsePresetEnvsContent({
+                    content,
+                    file: resolvedProfile.profileEnvFileSource,
+                    commandPath,
+                }));
+            }
+        }
+        Object.assign(presetEnvs, resolvedProfile.profileInlineEnvs);
+        if (resolvedProfile.variantEnvFileSource !== undefined) {
+            const content = await readPresetFile({
+                runtime,
+                file: resolvedProfile.variantEnvFileSource,
+                commandPath,
+            });
+            if (content !== undefined) {
+                Object.assign(presetEnvs, parsePresetEnvsContent({
+                    content,
+                    file: resolvedProfile.variantEnvFileSource,
+                    commandPath,
+                }));
+            }
         }
-        const camelName = kebabToCamelCase(lowerName.slice(5));
-        return {
-            original: arg,
-            resolved: `--${camelName}=false`,
-            name: camelName,
-            type: 'long',
-        };
-    }
-    if (!LONG_OPTION_REGEX.test(lowerName)) {
-        throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
+        Object.assign(presetEnvs, resolvedProfile.variantInlineEnvs);
     }
-    const camelName = kebabToCamelCase(lowerName.slice(2));
-    return {
-        original: arg,
-        resolved: `--${camelName}${valuePart}`,
-        name: camelName,
-        type: 'long',
-    };
+    return { presetArgv, presetEnvs };
 }
-function tokenizeShortOptions(arg, commandPath) {
-    if (arg.includes('=')) {
-        throw new CommanderError('UnsupportedShortSyntax', `"${arg}" is not supported. Use "-${arg[1]} ${arg.slice(3)}" instead`, commandPath);
-    }
-    const flags = arg.slice(1);
-    return flags.split('').map(flag => ({
-        original: `-${flag}`,
-        resolved: `-${flag}`,
-        name: flag,
-        type: 'short',
-    }));
+
+function getExitCode(error) {
+    return error.kind === 'ActionFailed' ? 1 : 2;
 }
-function tokenize(argv, commandPath) {
-    const optionTokens = [];
-    const restArgs = [];
-    let passThrough = false;
-    for (const arg of argv) {
-        if (arg === '--') {
-            passThrough = true;
-            continue;
-        }
-        if (passThrough) {
-            restArgs.push(arg);
-            continue;
-        }
-        if (arg.startsWith('--')) {
-            optionTokens.push(tokenizeLongOption(arg, commandPath));
-            continue;
+function renderTermination(params) {
+    const { termination, argv, envs, route, controlScan, findCommandByPath, resolveHelpCommand, resolveHelpColor, formatHelpForDisplay, print, } = params;
+    if (termination.kind === 'version') {
+        print(termination.version);
+        return;
+    }
+    const routeResult = route(argv);
+    const leafCommand = routeResult.chain[routeResult.chain.length - 1];
+    const controlScanResult = controlScan(routeResult.remaining, leafCommand);
+    const helpCommand = findCommandByPath(termination.targetCommandPath) ??
+        resolveHelpCommand(leafCommand, controlScanResult.helpTarget);
+    const helpColor = resolveHelpColor(helpCommand, controlScanResult.remaining, envs);
+    print(formatHelpForDisplay(helpCommand, helpColor));
+}
+function handleRunOutcome(params) {
+    const { outcome, argv, envs, route, controlScan, findCommandByPath, resolveHelpCommand, resolveHelpColor, formatHelpForDisplay, print, printError, exit, normalizeControlRunError, } = params;
+    if (outcome.kind === 'parsed') {
+        return;
+    }
+    if (outcome.kind === 'terminated') {
+        try {
+            renderTermination({
+                termination: outcome.termination,
+                argv,
+                envs,
+                route,
+                controlScan,
+                findCommandByPath,
+                resolveHelpCommand,
+                resolveHelpColor,
+                formatHelpForDisplay,
+                print,
+            });
+            return;
         }
-        if (arg.startsWith('-') && arg.length > 1) {
-            optionTokens.push(...tokenizeShortOptions(arg, commandPath));
-            continue;
+        catch (error) {
+            if (error instanceof CommanderError) {
+                const normalizedError = normalizeControlRunError(error);
+                printError(normalizedError.format());
+                exit(getExitCode(normalizedError));
+                return;
+            }
+            throw error;
         }
-        optionTokens.push({
-            original: arg,
-            resolved: arg,
-            name: '',
-            type: 'none',
-        });
     }
-    return { optionTokens, restArgs };
-}
-const BUILTIN_HELP_OPTION = {
-    long: 'help',
-    type: 'boolean',
-    args: 'none',
-    desc: 'Show help information',
-};
-const BUILTIN_VERSION_OPTION = {
-    long: 'version',
-    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,
-    };
+    printError(outcome.error.format());
+    exit(getExitCode(outcome.error));
 }
-function isNoColorEnabled(envs) {
-    return envs['NO_COLOR'] !== undefined;
+function unwrapParseOutcome(params) {
+    const { outcome, commandPath } = params;
+    if (outcome.kind === 'parsed') {
+        return outcome.parseResult;
+    }
+    if (outcome.kind === 'terminated') {
+        throw new CommanderError('ConfigurationError', 'internal invariant violation: parse mode must not produce termination', commandPath);
+    }
+    throw outcome.error;
 }
-function normalizeBuiltinConfig(builtin) {
-    const resolved = {
-        option: createBuiltinOptionState(true),
-    };
-    if (builtin === undefined) {
-        return resolved;
+
+function validateOptionConfig(params) {
+    const { opt, commandPath } = params;
+    if (opt.long === 'help' ||
+        opt.long === 'version' ||
+        opt.long === 'devmode' ||
+        opt.long === 'logLevel') {
+        throw new CommanderError('ConfigurationError', `option long name "${opt.long}" is reserved`, commandPath);
     }
-    if (builtin === true) {
-        return {
-            option: createBuiltinOptionState(true),
-        };
+    if (opt.type === 'boolean' && opt.args !== 'none') {
+        throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" must have args: 'none'`, commandPath);
     }
-    if (builtin === false) {
-        return {
-            option: createBuiltinOptionState(false),
-        };
+    if ((opt.type === 'string' || opt.type === 'number') && opt.args === 'none') {
+        throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required', 'optional', or 'variadic'`, commandPath);
     }
-    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;
-            }
-        }
+    if (opt.type === 'number' && opt.args === 'optional') {
+        throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, commandPath);
     }
-    return resolved;
-}
-class Command {
-    #name;
-    #desc;
-    #version;
-    #builtinConfig;
-    #builtin;
-    #presetConfig;
-    #reporter;
-    #runtime;
-    #parent;
-    #options = [];
-    #arguments = [];
-    #examples = [];
-    #subcommandsList = [];
-    #subcommandsMap = new Map();
-    #action = undefined;
-    constructor(config) {
-        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;
-        this.#runtime = config.runtime ?? getDefaultCommandRuntime();
+    if (opt.long.startsWith('no')) {
+        throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, commandPath);
     }
-    get name() {
-        return this.#name || undefined;
+    if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
+        throw new CommanderError('ConfigurationError', `option long name must be camelCase: "${opt.long}"`, commandPath);
     }
-    get description() {
-        return this.#desc;
+    if (opt.short !== undefined && opt.short.length !== 1) {
+        throw new CommanderError('ConfigurationError', `option short name must be a single character: "${opt.short}"`, commandPath);
     }
-    get version() {
-        return this.#version;
+    if (opt.required && opt.default !== undefined) {
+        throw new CommanderError('ConfigurationError', `option "--${opt.long}" cannot be both required and have a default value`, commandPath);
     }
-    get builtin() {
-        return this.#builtinConfig;
+    if (opt.type === 'boolean' && opt.required) {
+        throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" cannot be required`, commandPath);
     }
-    get preset() {
-        return this.#presetConfig === undefined ? undefined : { ...this.#presetConfig };
+    if (opt.required && opt.args !== 'required') {
+        throw new CommanderError('ConfigurationError', `required option "--${opt.long}" must use args: 'required'`, commandPath);
     }
-    get parent() {
-        return this.#parent;
+}
+function checkOptionUniqueness(params) {
+    const { opt, options, commandPath } = params;
+    if (options.some(o => o.long === opt.long)) {
+        throw new CommanderError('OptionConflict', `option "--${opt.long}" is already defined`, commandPath);
     }
-    get options() {
-        return [...this.#options];
+    if (opt.short && options.some(o => o.short === opt.short)) {
+        throw new CommanderError('OptionConflict', `short option "-${opt.short}" is already defined`, commandPath);
     }
-    get arguments() {
-        return [...this.#arguments];
+}
+function validateArgumentConfig(params) {
+    const { arg, arguments_, commandPath } = params;
+    if (arg.kind !== 'required' &&
+        arg.kind !== 'optional' &&
+        arg.kind !== 'variadic' &&
+        arg.kind !== 'some') {
+        throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid kind`, commandPath);
     }
-    get examples() {
-        return this.#examples.map(example => ({ ...example }));
+    if (arg.type !== 'string' && arg.type !== 'choice') {
+        throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid type`, commandPath);
     }
-    get subcommands() {
-        return new Map(this.#subcommandsMap);
+    if (arg.default !== undefined && arg.kind !== 'optional') {
+        throw new CommanderError('ConfigurationError', `only optional argument "${arg.name}" can have a default value`, commandPath);
     }
-    option(opt) {
-        this.#validateOptionConfig(opt);
-        this.#checkOptionUniqueness(opt);
-        this.#options.push(opt);
-        return this;
+    if (arg.type === 'string' && arg.choices !== undefined) {
+        throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "string" cannot declare choices`, commandPath);
     }
-    argument(arg) {
-        this.#validateArgumentConfig(arg);
-        this.#arguments.push(arg);
-        return this;
+    if (arg.type === 'choice') {
+        if (!Array.isArray(arg.choices) || arg.choices.length === 0) {
+            throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "choice" must declare a non-empty choices array`, commandPath);
+        }
+        if (arg.choices.some(choice => typeof choice !== 'string')) {
+            throw new CommanderError('ConfigurationError', `argument "${arg.name}" choices must be string[]`, commandPath);
+        }
     }
-    action(fn) {
-        this.#action = fn;
-        return this;
+    if (arg.default !== undefined) {
+        validateArgumentDefaultValue({ arg, commandPath });
     }
-    example(title, usage, desc) {
-        this.#examples.push(this.#normalizeExample({ title, usage, desc }));
-        return this;
+    if (arg.kind === 'variadic' || arg.kind === 'some') {
+        if (arguments_.some(a => a.kind === 'variadic' || a.kind === 'some')) {
+            throw new CommanderError('ConfigurationError', 'only one variadic/some argument is allowed', commandPath);
+        }
     }
-    subcommand(name, cmd) {
-        if (name === 'help') {
-            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name', this.#getCommandPath());
+    if (arguments_.length > 0) {
+        const last = arguments_[arguments_.length - 1];
+        if (last.kind === 'variadic' || last.kind === 'some') {
+            throw new CommanderError('ConfigurationError', 'variadic/some argument must be the last argument', commandPath);
         }
-        if (cmd.#parent && cmd.#parent !== this) {
-            throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
+    }
+    if (arg.kind === 'required') {
+        const hasOptional = arguments_.some(a => a.kind === 'optional' || a.kind === 'variadic' || a.kind === 'some');
+        if (hasOptional) {
+            throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot come after optional/variadic/some arguments`, commandPath);
         }
-        const occupied = this.#subcommandsMap.get(name);
-        if (occupied && occupied !== cmd) {
-            throw new CommanderError('ConfigurationError', `subcommand name/alias "${name}" conflicts with an existing command`, this.#getCommandPath());
+    }
+}
+function validateArgumentDefaultValue(params) {
+    const { arg, commandPath } = params;
+    if (typeof arg.default !== 'string') {
+        throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must match type "${arg.type}"`, commandPath);
+    }
+    if (arg.type === 'choice') {
+        const choices = arg.choices ?? [];
+        if (!choices.includes(arg.default)) {
+            throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must be one of declared choices`, commandPath);
         }
-        const existing = this.#subcommandsList.find(e => e.command === cmd);
-        if (existing) {
-            if (existing.name === name || existing.aliases.includes(name)) {
-                return this;
-            }
-            existing.aliases.push(name);
-            this.#subcommandsMap.set(name, cmd);
-        }
-        else {
-            cmd.#name = name;
-            cmd.#parent = this;
-            this.#subcommandsList.push({ name, aliases: [], command: cmd });
-            this.#subcommandsMap.set(name, cmd);
-        }
-        return this;
     }
-    async run(params) {
+}
+function normalizeExample(params) {
+    const { example, commandPath } = params;
+    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', commandPath);
+    }
+    if (!usage) {
+        throw new CommanderError('ConfigurationError', 'example usage cannot be empty', commandPath);
+    }
+    if (!desc) {
+        throw new CommanderError('ConfigurationError', 'example description cannot be empty', commandPath);
+    }
+    return { title, usage, desc };
+}
+
+class CommandKernel {
+    #port;
+    #diagnostics;
+    #contextAdapter;
+    constructor(params) {
+        this.#port = params.port;
+        this.#diagnostics = params.diagnostics;
+        this.#contextAdapter = params.contextAdapter;
+    }
+    async execute(params, mode) {
         const { argv, envs, reporter } = params;
         try {
-            const routeResult = this.#route(argv);
+            const routeResult = this.#port.route(argv);
             const { chain } = routeResult;
             const leafCommand = chain[chain.length - 1];
-            const ctx = this.#createContext({
+            let ctx = this.#port.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;
+            const controlScanResult = this.#port.controlScan(routeResult.remaining, leafCommand);
+            ctx = this.#contextAdapter.applyControlScan(ctx, controlScanResult);
+            if (mode === 'run') {
+                const termination = this.#port.controlRun(leafCommand, controlScanResult);
+                if (termination !== undefined) {
+                    ctx.sources.preset.state = 'skipped';
+                    return {
+                        kind: 'terminated',
+                        termination,
+                    };
+                }
             }
-            if (ctx.controls.version) {
-                console.log(leafCommand.#version);
-                return;
+            let presetResult;
+            try {
+                presetResult = await this.#port.preset(controlScanResult.remaining, ctx);
+            }
+            catch (err) {
+                if (err instanceof CommanderError) {
+                    throw this.#diagnostics.withErrorIssue(err, {
+                        stage: 'preset',
+                        scope: this.#port.issueScopeFromErrorKind(err.kind),
+                    });
+                }
+                throw err;
             }
-            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,
-                args: parseResult.args,
-                rawArgs: parseResult.rawArgs,
-            };
-            if (leafCommand.#action) {
-                await leafCommand.#runAction(actionParams);
+            ctx = this.#contextAdapter.applyPresetResult(ctx, presetResult);
+            const sourceSegments = presetResult.segments;
+            let optionTokens;
+            let restArgs;
+            try {
+                const tokenizeResult = this.#port.tokenize(sourceSegments, this.#port.getCommandPath(leafCommand));
+                optionTokens = tokenizeResult.optionTokens;
+                restArgs = tokenizeResult.restArgs;
+            }
+            catch (err) {
+                if (err instanceof CommanderError) {
+                    const enriched = this.#diagnostics.withErrorIssue(err, {
+                        stage: 'tokenize',
+                        scope: this.#port.issueScopeFromErrorKind(err.kind),
+                    });
+                    throw this.#diagnostics.withPresetInjectedHint(enriched, sourceSegments);
+                }
+                throw err;
             }
-            else if (leafCommand.#subcommandsList.length > 0) {
-                const helpColor = leafCommand.#resolveHelpColorFromTailArgv(presetResult.tailArgv, ctx.envs);
-                console.log(leafCommand.#formatHelpForDisplay({ color: helpColor }));
+            let optionPolicyMap;
+            try {
+                optionPolicyMap = this.#port.buildOptionPolicyMap(chain);
+            }
+            catch (err) {
+                if (err instanceof CommanderError) {
+                    const enriched = this.#diagnostics.withErrorIssue(err, {
+                        stage: 'builtin-resolve',
+                        scope: this.#port.issueScopeFromErrorKind(err.kind),
+                    });
+                    throw this.#diagnostics.withPresetInjectedHint(enriched, sourceSegments);
+                }
+                throw err;
             }
-            else {
-                throw new CommanderError('ConfigurationError', `no action defined for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
+            let resolveResult;
+            try {
+                resolveResult = this.#port.resolve(chain, optionTokens, optionPolicyMap);
+            }
+            catch (err) {
+                if (err instanceof CommanderError) {
+                    const enriched = this.#diagnostics.withErrorIssue(err, {
+                        stage: 'resolve',
+                        scope: this.#port.issueScopeFromErrorKind(err.kind),
+                    });
+                    throw this.#diagnostics.withPresetInjectedHint(enriched, sourceSegments);
+                }
+                throw err;
+            }
+            let parseResult;
+            try {
+                parseResult = this.#port.parse(chain, resolveResult, optionPolicyMap, ctx, restArgs);
+            }
+            catch (err) {
+                if (err instanceof CommanderError) {
+                    const optionConflictSource = this.#diagnostics.resolveOptionConflictSourceAttribution(err, sourceSegments);
+                    const optionConflictPreset = this.#diagnostics.resolveOptionConflictPresetAttribution(err, sourceSegments, optionConflictSource);
+                    const enriched = this.#diagnostics.withErrorIssue(err, {
+                        stage: 'parse',
+                        scope: this.#port.issueScopeFromErrorKind(err.kind),
+                        source: optionConflictSource,
+                        preset: optionConflictPreset,
+                    });
+                    throw this.#diagnostics.withPresetInjectedHint(enriched, sourceSegments);
+                }
+                throw err;
+            }
+            if (mode === 'run') {
+                try {
+                    await this.#port.run({
+                        leafCommand,
+                        parseResult,
+                        presetResult,
+                        ctx,
+                    });
+                }
+                catch (err) {
+                    if (err instanceof CommanderError) {
+                        throw this.#diagnostics.withErrorIssue(err, {
+                            stage: 'run',
+                            scope: this.#port.issueScopeFromErrorKind(err.kind),
+                        });
+                    }
+                    throw err;
+                }
             }
+            return {
+                kind: 'parsed',
+                parseResult,
+            };
         }
         catch (err) {
             if (err instanceof CommanderError) {
-                console.error(err.format());
-                process.exit(2);
-                return;
+                return {
+                    kind: 'failed',
+                    error: this.#diagnostics.normalizeCommanderError(err, {
+                        fallbackStage: mode === 'run' ? 'run' : 'parse',
+                        fallbackScope: this.#port.issueScopeFromErrorKind(err.kind),
+                    }),
+                };
             }
             throw err;
         }
     }
-    async parse(params) {
-        const { argv, envs, reporter } = params;
-        const routeResult = this.#route(argv);
-        const { chain } = routeResult;
-        const leafCommand = chain[chain.length - 1];
-        const ctx = this.#createContext({
-            chain,
-            cmds: routeResult.cmds,
-            envs,
-            reporter,
+}
+
+class CommandContextAdapter {
+    applyControlScan(ctx, controlScanResult) {
+        return {
+            ...ctx,
+            controls: controlScanResult.controls,
+            sources: {
+                ...ctx.sources,
+                user: {
+                    ...ctx.sources.user,
+                    argv: [...controlScanResult.remaining],
+                },
+            },
+        };
+    }
+    applyPresetResult(ctx, presetResult) {
+        return {
+            ...ctx,
+            sources: presetResult.sources,
+            envs: presetResult.envs,
+        };
+    }
+    toActionParams(parseResult) {
+        return {
+            ctx: parseResult.ctx,
+            builtin: parseResult.builtin,
+            opts: parseResult.opts,
+            args: parseResult.args,
+            rawArgs: parseResult.rawArgs,
+        };
+    }
+}
+
+class CommandHintAttributor {
+    withPresetInjectedHint(error, sourceSegments) {
+        const presetSegments = sourceSegments.filter(segment => segment.source === 'preset');
+        if (presetSegments.length === 0) {
+            return error;
+        }
+        if (error.kind === 'ConfigurationError') {
+            return error;
+        }
+        let nextError = error;
+        const primaryIssue = nextError.meta?.issues.find(issue => issue.kind === 'error');
+        const conflictSources = primaryIssue?.reason.code === 'option_conflict'
+            ? this.#inferOptionConflictSources(primaryIssue.reason.message, sourceSegments)
+            : undefined;
+        const hasMixedConflictAttribution = primaryIssue?.source?.related?.includes('user') === true &&
+            primaryIssue.source.related.includes('preset');
+        const isMixedConflict = hasMixedConflictAttribution ||
+            (conflictSources?.has('user') === true && conflictSources.has('preset'));
+        if (isMixedConflict &&
+            primaryIssue?.reason.code === 'option_conflict' &&
+            !nextError.meta?.issues.some(issue => issue.kind === 'hint' && issue.reason.code === 'mixed_source_conflict')) {
+            const mixedHint = {
+                kind: 'hint',
+                stage: primaryIssue.stage,
+                originStage: primaryIssue.originStage,
+                scope: 'option',
+                source: {
+                    related: ['user', 'preset'],
+                },
+                reason: {
+                    code: 'mixed_source_conflict',
+                    message: 'option conflict involves both user input and preset-injected tokens',
+                },
+                preset: this.#resolveOptionConflictPresetByMessage(primaryIssue.reason.message, sourceSegments, { related: ['user', 'preset'] }),
+            };
+            nextError = nextError.withIssue(mixedHint);
+        }
+        const shouldAttachPresetTokenHint = primaryIssue?.source?.primary === 'preset' || isMixedConflict;
+        if (!shouldAttachPresetTokenHint) {
+            return nextError;
+        }
+        if (nextError.meta?.issues.some(issue => issue.kind === 'hint' && issue.reason.code === 'preset_token_injected')) {
+            return nextError;
+        }
+        const firstSegment = presetSegments[0];
+        const moreCount = presetSegments.length - 1;
+        const moreText = moreCount > 0 ? ` (+${moreCount} more)` : '';
+        const currentPrimaryIssue = nextError.meta?.issues.find(issue => issue.kind === 'error');
+        const hint = {
+            kind: 'hint',
+            stage: currentPrimaryIssue?.stage ?? 'parse',
+            originStage: 'preset',
+            scope: 'preset',
+            source: { primary: 'preset' },
+            reason: {
+                code: 'preset_token_injected',
+                message: `token ${JSON.stringify(firstSegment.value)} was injected from preset profile opts${moreText}`,
+            },
+            preset: firstSegment.preset,
+        };
+        return nextError.withIssue(hint);
+    }
+    resolveOptionConflictSourceAttribution(error, sourceSegments) {
+        if (error.kind !== 'OptionConflict') {
+            return undefined;
+        }
+        const sources = this.#inferOptionConflictSources(error.message, sourceSegments);
+        if (sources.has('user') && sources.has('preset')) {
+            return {
+                related: ['user', 'preset'],
+            };
+        }
+        if (sources.has('preset')) {
+            return { primary: 'preset' };
+        }
+        if (sources.has('user')) {
+            return { primary: 'user' };
+        }
+        return undefined;
+    }
+    resolveOptionConflictPresetAttribution(error, sourceSegments, source) {
+        if (error.kind !== 'OptionConflict') {
+            return undefined;
+        }
+        return this.#resolveOptionConflictPresetByMessage(error.message, sourceSegments, source);
+    }
+    #resolveOptionConflictPresetByMessage(message, sourceSegments, source) {
+        const relevantSegments = this.#collectOptionConflictSegments(message, sourceSegments);
+        const relevantPresetSegment = relevantSegments.find(segment => segment.source === 'preset' && segment.preset !== undefined);
+        if (relevantPresetSegment?.preset !== undefined) {
+            return { ...relevantPresetSegment.preset };
+        }
+        const hasPresetSource = source?.primary === 'preset' || source?.related?.includes('preset') === true;
+        if (!hasPresetSource) {
+            return undefined;
+        }
+        const fallbackPresetSegment = sourceSegments.find(segment => segment.source === 'preset' && segment.preset !== undefined);
+        return fallbackPresetSegment?.preset === undefined
+            ? undefined
+            : { ...fallbackPresetSegment.preset };
+    }
+    #inferOptionConflictSources(message, sourceSegments) {
+        const relevantSegments = this.#collectOptionConflictSegments(message, sourceSegments);
+        const sources = new Set();
+        for (const segment of relevantSegments) {
+            sources.add(segment.source);
+        }
+        return sources;
+    }
+    #collectOptionConflictSegments(message, sourceSegments) {
+        const matchedLongs = Array.from(message.matchAll(/"(--[a-z][a-z0-9]*(?:-[a-z0-9]+)*)"/g), match => match[1]);
+        const matchedShorts = Array.from(message.matchAll(/"(-[A-Za-z0-9])"/g), match => match[1]);
+        const optionLiterals = new Set([...matchedLongs, ...matchedShorts]);
+        const optionSegments = sourceSegments.filter(segment => segment.value.startsWith('-'));
+        const relevantSegments = optionLiterals.size === 0
+            ? optionSegments
+            : optionSegments.filter(segment => {
+                for (const literal of optionLiterals) {
+                    if (segment.value === literal || segment.value.startsWith(`${literal}=`)) {
+                        return true;
+                    }
+                }
+                return false;
+            });
+        return relevantSegments;
+    }
+}
+
+const COMMAND_ERROR_ISSUE_CODES = [
+    'invalid_option_format',
+    'invalid_negative_option',
+    'negative_option_with_value',
+    'negative_option_type',
+    'unknown_option',
+    'unknown_subcommand',
+    'unexpected_argument',
+    'missing_value',
+    'invalid_type',
+    'unsupported_short_syntax',
+    'option_conflict',
+    'missing_required',
+    'invalid_choice',
+    'invalid_boolean_value',
+    'missing_required_argument',
+    'too_many_arguments',
+    'configuration_error',
+    'action_failed',
+];
+const COMMAND_HINT_ISSUE_CODES = [
+    'preset_token_injected',
+    'mixed_source_conflict',
+    'did_you_mean_subcommand',
+    'command_does_not_accept_positional_arguments',
+];
+const ERROR_ISSUE_CODE_SET = new Set(COMMAND_ERROR_ISSUE_CODES);
+const HINT_ISSUE_CODE_SET = new Set(COMMAND_HINT_ISSUE_CODES);
+function isErrorIssueCode(code) {
+    return ERROR_ISSUE_CODE_SET.has(code);
+}
+function isHintIssueCode(code) {
+    return HINT_ISSUE_CODE_SET.has(code);
+}
+
+function errorKindToIssueCode(kind) {
+    switch (kind) {
+        case 'InvalidOptionFormat':
+            return 'invalid_option_format';
+        case 'InvalidNegativeOption':
+            return 'invalid_negative_option';
+        case 'NegativeOptionWithValue':
+            return 'negative_option_with_value';
+        case 'NegativeOptionType':
+            return 'negative_option_type';
+        case 'UnknownOption':
+            return 'unknown_option';
+        case 'UnknownSubcommand':
+            return 'unknown_subcommand';
+        case 'UnexpectedArgument':
+            return 'unexpected_argument';
+        case 'MissingValue':
+            return 'missing_value';
+        case 'InvalidType':
+            return 'invalid_type';
+        case 'UnsupportedShortSyntax':
+            return 'unsupported_short_syntax';
+        case 'OptionConflict':
+            return 'option_conflict';
+        case 'MissingRequired':
+            return 'missing_required';
+        case 'InvalidChoice':
+            return 'invalid_choice';
+        case 'InvalidBooleanValue':
+            return 'invalid_boolean_value';
+        case 'MissingRequiredArgument':
+            return 'missing_required_argument';
+        case 'TooManyArguments':
+            return 'too_many_arguments';
+        case 'ActionFailed':
+            return 'action_failed';
+        case 'ConfigurationError':
+            return 'configuration_error';
+        default:
+            return 'configuration_error';
+    }
+}
+class CommandIssueNormalizer {
+    withErrorIssue(error, params) {
+        if (error.meta?.issues.some(existing => existing.kind === 'error')) {
+            return error;
+        }
+        return error.withIssue(this.#buildErrorIssue(error, params));
+    }
+    normalizeCommanderError(error, options) {
+        const issues = error.meta?.issues ?? [];
+        const normalizedIssues = this.#normalizeIssues(issues, {
+            error,
+            fallbackStage: options.fallbackStage,
+            fallbackScope: options.fallbackScope,
         });
-        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);
+        const nextMeta = {
+            commandPath: error.meta?.commandPath ?? error.commandPath,
+            token: error.meta?.token,
+            option: error.meta?.option,
+            argument: error.meta?.argument,
+            issues: normalizedIssues,
+        };
+        return new CommanderError(error.kind, error.message, error.commandPath, nextMeta);
+    }
+    #buildErrorIssue(error, params) {
+        const { stage, scope, token, source, preset, originStage, details } = params;
+        const tokenSource = token === undefined
+            ? undefined
+            : {
+                primary: token.source,
+            };
+        const defaultSource = error.kind === 'MissingRequiredArgument' || error.kind === 'UnknownSubcommand'
+            ? { primary: 'user' }
+            : undefined;
+        const issueSource = source ?? tokenSource ?? defaultSource;
+        const issuePreset = preset ?? token?.preset;
+        const presetSource = issueSource?.primary === 'preset' || issueSource?.related?.includes('preset');
+        const resolvedOriginStage = originStage ?? (presetSource && stage !== 'preset' ? 'preset' : undefined);
+        return {
+            kind: 'error',
+            stage,
+            originStage: resolvedOriginStage,
+            source: issueSource,
+            scope,
+            reason: {
+                code: errorKindToIssueCode(error.kind),
+                message: error.message,
+                details,
+            },
+            preset: issuePreset,
+        };
     }
-    formatHelp() {
-        return this.#renderHelpPlain(this.#buildHelpData());
+    #normalizeIssues(issues, options) {
+        const normalized = issues
+            .map(issue => this.#normalizeIssue(issue))
+            .filter((issue) => issue !== undefined);
+        const primaryError = normalized.find(issue => issue.kind === 'error');
+        const hints = normalized.filter(issue => issue.kind === 'hint');
+        if (primaryError === undefined) {
+            const fallbackError = this.#buildErrorIssue(options.error, {
+                stage: options.fallbackStage,
+                scope: options.fallbackScope,
+            });
+            return [fallbackError, ...hints];
+        }
+        return [primaryError, ...hints];
+    }
+    #normalizeIssue(issue) {
+        let source = this.#normalizeIssueSource(issue.source);
+        let preset = this.#normalizePresetIssueMeta(issue.preset);
+        const reasonCode = issue.reason.code;
+        if (!this.#hasPresetSource(source)) {
+            preset = undefined;
+        }
+        if (source?.primary === 'preset' && !this.#hasPresetLocator(preset)) {
+            source = this.#dropPresetPrimarySource(source);
+            if (!this.#hasPresetSource(source)) {
+                preset = undefined;
+            }
+        }
+        if (issue.kind === 'error') {
+            const normalizedCode = isErrorIssueCode(reasonCode)
+                ? reasonCode
+                : 'configuration_error';
+            const normalizedReason = normalizedCode === reasonCode
+                ? issue.reason
+                : {
+                    code: normalizedCode,
+                    message: `invalid error issue code "${reasonCode}"`,
+                    details: {
+                        ...(issue.reason.details ?? {}),
+                        invalidIssueCode: reasonCode,
+                    },
+                };
+            return {
+                ...issue,
+                source,
+                preset,
+                reason: normalizedReason,
+            };
+        }
+        if (!isHintIssueCode(reasonCode)) {
+            return undefined;
+        }
+        return {
+            ...issue,
+            source,
+            preset,
+        };
     }
-    #formatHelpForDisplay(params = {}) {
-        const { color = true } = params;
-        const helpData = this.#buildHelpData();
-        if (!this.#shouldRenderStyledHelp(color)) {
-            return this.#renderHelpPlain(helpData);
+    #normalizeIssueSource(source) {
+        if (source === undefined) {
+            return undefined;
         }
-        return this.#renderHelpTerminal(helpData);
+        const related = source.related === undefined ? undefined : Array.from(new Set(source.related));
+        const primary = source.primary;
+        if (primary !== undefined && related !== undefined && !related.includes(primary)) {
+            related.push(primary);
+        }
+        if (primary === undefined && (related === undefined || related.length === 0)) {
+            return undefined;
+        }
+        return {
+            primary,
+            related,
+        };
     }
-    #shouldRenderStyledHelp(color) {
-        return color && process.stdout.isTTY === true;
+    #dropPresetPrimarySource(source) {
+        const related = source.related?.filter(item => item !== 'preset');
+        if (related === undefined || related.length === 0) {
+            return undefined;
+        }
+        return {
+            related,
+        };
     }
-    #buildHelpData() {
-        const parseOptions = this.#resolveOptionPolicy().mergedOptions;
-        const allOptions = [...parseOptions, BUILTIN_HELP_OPTION];
-        if (this.#supportsBuiltinVersion()) {
-            allOptions.push(BUILTIN_VERSION_OPTION);
+    #normalizePresetIssueMeta(preset) {
+        if (preset === undefined) {
+            return undefined;
         }
-        const commandPath = this.#getCommandPath();
-        let usage = `Usage: ${commandPath}`;
+        const nextPreset = {
+            file: preset.file,
+            profile: preset.profile,
+            variant: preset.variant,
+            optionKey: preset.optionKey,
+        };
+        const hasAnyValue = nextPreset.file !== undefined ||
+            nextPreset.profile !== undefined ||
+            nextPreset.variant !== undefined ||
+            nextPreset.optionKey !== undefined;
+        return hasAnyValue ? nextPreset : undefined;
+    }
+    #hasPresetLocator(preset) {
+        return (preset?.file !== undefined || preset?.profile !== undefined || preset?.variant !== undefined);
+    }
+    #hasPresetSource(source) {
+        return source?.primary === 'preset' || source?.related?.includes('preset') === true;
+    }
+}
+
+class CommandDiagnosticsEngine {
+    #issueNormalizer = new CommandIssueNormalizer();
+    #hintAttributor = new CommandHintAttributor();
+    withErrorIssue(error, params) {
+        return this.#issueNormalizer.withErrorIssue(error, params);
+    }
+    withPresetInjectedHint(error, sourceSegments) {
+        return this.#hintAttributor.withPresetInjectedHint(error, sourceSegments);
+    }
+    normalizeCommanderError(error, options) {
+        return this.#issueNormalizer.normalizeCommanderError(error, options);
+    }
+    resolveOptionConflictSourceAttribution(error, sourceSegments) {
+        return this.#hintAttributor.resolveOptionConflictSourceAttribution(error, sourceSegments);
+    }
+    resolveOptionConflictPresetAttribution(error, sourceSegments, source) {
+        return this.#hintAttributor.resolveOptionConflictPresetAttribution(error, sourceSegments, source);
+    }
+}
+
+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 ANSI_ESCAPE_REGEX = new RegExp(String.raw `\x1B\[[0-?]*[ -/]*[@-~]`, 'g');
+function camelToKebabCase$3(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+function isNoColorEnabled$1(envs) {
+    return envs['NO_COLOR'] !== undefined;
+}
+function stripAnsi(value) {
+    return value.replace(ANSI_ESCAPE_REGEX, '');
+}
+function isCombiningMark(codePoint) {
+    return ((codePoint >= 0x0300 && codePoint <= 0x036f) ||
+        (codePoint >= 0x1ab0 && codePoint <= 0x1aff) ||
+        (codePoint >= 0x1dc0 && codePoint <= 0x1dff) ||
+        (codePoint >= 0x20d0 && codePoint <= 0x20ff) ||
+        (codePoint >= 0xfe20 && codePoint <= 0xfe2f));
+}
+function isWideCodePoint(codePoint) {
+    if (codePoint < 0x1100) {
+        return false;
+    }
+    return (codePoint <= 0x115f ||
+        codePoint === 0x2329 ||
+        codePoint === 0x232a ||
+        (codePoint >= 0x2e80 && codePoint <= 0x3247 && codePoint !== 0x303f) ||
+        (codePoint >= 0x3250 && codePoint <= 0x4dbf) ||
+        (codePoint >= 0x4e00 && codePoint <= 0xa4c6) ||
+        (codePoint >= 0xa960 && codePoint <= 0xa97c) ||
+        (codePoint >= 0xac00 && codePoint <= 0xd7a3) ||
+        (codePoint >= 0xf900 && codePoint <= 0xfaff) ||
+        (codePoint >= 0xfe10 && codePoint <= 0xfe19) ||
+        (codePoint >= 0xfe30 && codePoint <= 0xfe6b) ||
+        (codePoint >= 0xff01 && codePoint <= 0xff60) ||
+        (codePoint >= 0xffe0 && codePoint <= 0xffe6) ||
+        (codePoint >= 0x1b000 && codePoint <= 0x1b001) ||
+        (codePoint >= 0x1f200 && codePoint <= 0x1f251) ||
+        (codePoint >= 0x20000 && codePoint <= 0x3fffd));
+}
+function getDisplayWidth(value) {
+    const normalized = stripAnsi(value).normalize('NFC');
+    let width = 0;
+    for (const char of normalized) {
+        const codePoint = char.codePointAt(0);
+        if (codePoint === undefined || isCombiningMark(codePoint)) {
+            continue;
+        }
+        width += isWideCodePoint(codePoint) ? 2 : 1;
+    }
+    return width;
+}
+function padDisplayEnd(value, targetWidth) {
+    const width = getDisplayWidth(value);
+    if (width >= targetWidth) {
+        return value;
+    }
+    return value + ' '.repeat(targetWidth - width);
+}
+class CommandHelpRenderer {
+    buildHelpData(params) {
+        const allOptions = [...params.options, params.builtinHelpOption];
+        if (params.supportsBuiltinVersion) {
+            allOptions.push(params.builtinVersionOption);
+        }
+        let usage = `Usage: ${params.commandPath}`;
         if (allOptions.length > 0)
             usage += ' [options]';
-        if (this.#subcommandsList.length > 0)
+        if (params.subcommands.length > 0)
             usage += ' [command]';
-        for (const arg of this.#arguments) {
+        for (const arg of params.arguments) {
             if (arg.kind === 'required') {
                 usage += ` <${arg.name}>`;
             }
@@ -695,7 +1251,7 @@ class Command {
             }
         }
         const argumentsLines = [];
-        for (const arg of this.#arguments) {
+        for (const arg of params.arguments) {
             const sig = arg.kind === 'required'
                 ? `<${arg.name}>`
                 : arg.kind === 'optional'
@@ -731,11 +1287,11 @@ class Command {
             if (rankA !== rankB) {
                 return rankA - rankB;
             }
-            return camelToKebabCase(a.long).localeCompare(camelToKebabCase(b.long));
+            return camelToKebabCase$3(a.long).localeCompare(camelToKebabCase$3(b.long));
         });
         const options = [];
         for (const opt of sortedOptions) {
-            const kebabLong = camelToKebabCase(opt.long);
+            const kebabLong = camelToKebabCase$3(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
             if (opt.args === 'optional') {
@@ -754,24 +1310,24 @@ class Command {
             options.push({ sig, desc });
         }
         const commands = [];
-        if (this.#subcommandsList.length > 0) {
+        if (params.subcommands.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        const sortedSubcommands = [...this.#subcommandsList].sort((a, b) => a.name.localeCompare(b.name));
+        const sortedSubcommands = [...params.subcommands].sort((a, b) => a.name.localeCompare(b.name));
         for (const entry of sortedSubcommands) {
             let name = entry.name;
             if (entry.aliases.length > 0) {
                 name += `, ${entry.aliases.join(', ')}`;
             }
-            commands.push({ name, desc: entry.command.#desc });
+            commands.push({ name, desc: entry.desc });
         }
-        const examples = this.#examples.map(example => ({
+        const examples = params.examples.map(example => ({
             title: example.title,
-            usage: commandPath ? `${commandPath} ${example.usage}` : example.usage,
+            usage: params.commandPath ? `${params.commandPath} ${example.usage}` : example.usage,
             desc: example.desc,
         }));
         return {
-            desc: this.#desc,
+            desc: params.desc,
             usage,
             arguments: argumentsLines,
             options,
@@ -779,6 +1335,51 @@ class Command {
             examples,
         };
     }
+    formatHelp(helpData) {
+        return this.#renderHelpPlain(helpData);
+    }
+    formatHelpForDisplay(helpData, color) {
+        if (!this.#shouldRenderStyledHelp(color)) {
+            return this.#renderHelpPlain(helpData);
+        }
+        return this.#renderHelpTerminal(helpData);
+    }
+    resolveHelpColorFromTailArgv(params) {
+        const colorOption = params.options.find(opt => opt.long === 'color');
+        let color = !isNoColorEnabled$1(params.envs);
+        if (!colorOption || colorOption.type !== 'boolean' || colorOption.args !== 'none') {
+            return color;
+        }
+        const separatorIndex = params.tailArgv.indexOf('--');
+        const scanTokens = separatorIndex === -1 ? params.tailArgv : params.tailArgv.slice(0, separatorIndex);
+        for (const token of scanTokens) {
+            if (token === '--color') {
+                color = true;
+                continue;
+            }
+            if (token === '--no-color') {
+                color = false;
+                continue;
+            }
+            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"`, params.commandPath);
+            }
+        }
+        return color;
+    }
+    #shouldRenderStyledHelp(color) {
+        return color && process.stdout.isTTY === true;
+    }
     #renderHelpPlain(helpData) {
         const lines = [];
         const labelWidth = this.#getHelpLabelWidth(helpData);
@@ -873,243 +1474,287 @@ class Command {
         const outputLabel = styleLabel ? styleLabel(paddedLabel) : paddedLabel;
         return `  ${outputLabel}  ${desc}`;
     }
-    getCompletionMeta() {
-        const optionMap = new Map();
-        for (const option of this.#resolveOptionPolicy().mergedOptions) {
-            optionMap.set(option.long, option);
-        }
-        optionMap.set('help', BUILTIN_HELP_OPTION);
-        if (this.#supportsBuiltinVersion()) {
-            optionMap.set('version', BUILTIN_VERSION_OPTION);
-        }
-        const allOptions = Array.from(optionMap.values());
-        const options = [];
-        const argumentsMeta = [];
-        for (const opt of allOptions) {
-            options.push({
-                long: opt.long,
-                short: opt.short,
-                desc: opt.desc,
-                type: opt.type,
-                args: opt.args,
-                choices: opt.choices?.map(choice => String(choice)),
-            });
+}
+
+const DECIMAL_INTEGER_REGEX = /^\d(?:_?\d)*$/;
+const DECIMAL_FRACTION_REGEX = /^\d(?:_?\d)*$/;
+const DECIMAL_EXPONENT_REGEX = /^[eE][+-]?\d(?:_?\d)*$/;
+const BINARY_LITERAL_REGEX = /^0[bB][01](?:_?[01])*$/;
+const OCTAL_LITERAL_REGEX = /^0[oO][0-7](?:_?[0-7])*$/;
+const HEX_LITERAL_REGEX = /^0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*$/;
+function camelToKebabCase$2(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+function isNoColorEnabled(envs) {
+    return envs['NO_COLOR'] !== undefined;
+}
+function isValidPrimitiveNumberLiteral(rawValue) {
+    if (rawValue.trim() !== rawValue || rawValue.length === 0) {
+        return false;
+    }
+    if (rawValue === 'NaN' || rawValue === 'Infinity' || rawValue === '-Infinity') {
+        return false;
+    }
+    if (BINARY_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    if (OCTAL_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    if (HEX_LITERAL_REGEX.test(rawValue)) {
+        return true;
+    }
+    const sign = rawValue[0] === '+' || rawValue[0] === '-' ? rawValue[0] : '';
+    const body = sign ? rawValue.slice(1) : rawValue;
+    if (body.length === 0) {
+        return false;
+    }
+    const expIndex = body.search(/[eE]/);
+    const basePart = expIndex === -1 ? body : body.slice(0, expIndex);
+    const expPart = expIndex === -1 ? '' : body.slice(expIndex);
+    if (expPart && !DECIMAL_EXPONENT_REGEX.test(expPart)) {
+        return false;
+    }
+    if (basePart.includes('.')) {
+        const decimalParts = basePart.split('.');
+        if (decimalParts.length !== 2) {
+            return false;
         }
-        for (const arg of this.#arguments) {
-            argumentsMeta.push({
-                name: arg.name,
-                kind: arg.kind,
-                type: arg.type,
-                choices: arg.type === 'choice' ? arg.choices?.map(choice => String(choice)) : undefined,
-            });
+        const [intPart, fracPart] = decimalParts;
+        const intOk = intPart.length === 0 || DECIMAL_INTEGER_REGEX.test(intPart);
+        const fracOk = fracPart.length === 0 || DECIMAL_FRACTION_REGEX.test(fracPart);
+        if (!intOk || !fracOk) {
+            return false;
         }
-        return {
-            name: this.#name,
-            desc: this.#desc,
-            aliases: [],
-            options,
-            arguments: argumentsMeta,
-            subcommands: this.#subcommandsList.map(entry => {
-                const subMeta = entry.command.getCompletionMeta();
-                return {
-                    ...subMeta,
-                    name: entry.name,
-                    aliases: entry.aliases,
-                };
-            }),
-        };
+        return intPart.length > 0 || fracPart.length > 0;
     }
-    #findSubcommandEntry(token) {
-        return this.#subcommandsList.find(e => e.name === token || e.aliases.includes(token));
+    return DECIMAL_INTEGER_REGEX.test(basePart);
+}
+function parsePrimitiveNumber(rawValue) {
+    if (!isValidPrimitiveNumberLiteral(rawValue)) {
+        return undefined;
     }
-    #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.#findSubcommandEntry(token);
-            if (!entry)
-                break;
-            current = entry.command;
-            cmds.push(token);
-            chain.push(current);
-            idx += 1;
-        }
-        return { chain, remaining: argv.slice(idx), cmds };
+    const normalized = rawValue.replaceAll('_', '');
+    const value = Number(normalized);
+    if (!Number.isFinite(value)) {
+        return undefined;
     }
-    #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;
+    return value;
+}
+class CommandOptionParser {
+    parseOptions(params) {
+        const { tokens, allOptions, envs, commandPath } = params;
+        const opts = {};
+        const explicitOptionLongs = new Set();
+        let sawColorToken = false;
+        for (const opt of allOptions) {
+            if (opt.default !== undefined) {
+                opts[opt.long] = opt.default;
+            }
+            else if (opt.type === 'boolean' && opt.args === 'none') {
+                opts[opt.long] = false;
+            }
+            else if (opt.args === 'variadic') {
+                opts[opt.long] = [];
+            }
+        }
+        const optionByLong = new Map();
+        const optionByShort = new Map();
+        for (const opt of allOptions) {
+            optionByLong.set(opt.long, opt);
+            if (opt.short) {
+                optionByShort.set(opt.short, opt);
+            }
+        }
+        let i = 0;
+        while (i < tokens.length) {
+            const token = tokens[i];
+            const opt = token.type === 'long' ? optionByLong.get(token.name) : optionByShort.get(token.name);
+            if (!opt) {
+                i += 1;
+                continue;
+            }
+            explicitOptionLongs.add(opt.long);
+            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$2(opt.long)}" can only be used with boolean options`, commandPath);
+            }
+            if (opt.type === 'boolean' && opt.args === 'none') {
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    const value = token.resolved.slice(eqIdx + 1);
+                    if (value === 'true') {
+                        opts[opt.long] = true;
+                    }
+                    else if (value === 'false') {
+                        opts[opt.long] = false;
+                    }
+                    else {
+                        throw new CommanderError('InvalidBooleanValue', `invalid value "${value}" for boolean option "--${camelToKebabCase$2(opt.long)}". Use "true" or "false"`, commandPath);
+                    }
+                }
+                else {
+                    opts[opt.long] = true;
+                }
+                i += 1;
+                continue;
+            }
+            if (opt.args === 'required') {
+                const eqIdx = token.resolved.indexOf('=');
+                let rawValue;
+                if (eqIdx !== -1) {
+                    rawValue = token.resolved.slice(eqIdx + 1);
+                }
+                else if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                    rawValue = tokens[i + 1].original;
+                    i += 1;
+                }
+                else {
+                    throw new CommanderError('MissingValue', `option "--${camelToKebabCase$2(opt.long)}" requires a value`, commandPath);
+                }
+                opts[opt.long] = this.#convertValue(opt, rawValue, commandPath);
+                i += 1;
+                continue;
+            }
+            if (opt.args === 'optional') {
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    opts[opt.long] = this.#convertValue(opt, token.resolved.slice(eqIdx + 1), commandPath);
+                    i += 1;
+                    continue;
+                }
+                if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                    opts[opt.long] = this.#convertValue(opt, tokens[i + 1].original, commandPath);
+                    i += 1;
+                }
+                else {
+                    opts[opt.long] = undefined;
+                }
+                i += 1;
                 continue;
             }
-            if (token === '--version' && leafCommand.#supportsBuiltinVersion()) {
-                controls.version = true;
+            if (opt.args === 'variadic') {
+                const values = Array.isArray(opts[opt.long]) ? opts[opt.long] : [];
+                const eqIdx = token.resolved.indexOf('=');
+                if (eqIdx !== -1) {
+                    values.push(this.#convertValue(opt, token.resolved.slice(eqIdx + 1), commandPath));
+                }
+                else {
+                    while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
+                        i += 1;
+                        values.push(this.#convertValue(opt, tokens[i].original, commandPath));
+                    }
+                }
+                opts[opt.long] = values;
+                i += 1;
                 continue;
             }
-            remainingBeforeSeparator.push(token);
+            i += 1;
+        }
+        for (const opt of allOptions) {
+            if (opt.required && !Object.prototype.hasOwnProperty.call(opts, opt.long)) {
+                throw new CommanderError('MissingRequired', `missing required option "--${camelToKebabCase$2(opt.long)}"`, commandPath);
+            }
+        }
+        for (const opt of allOptions) {
+            if (opt.choices && opts[opt.long] !== undefined) {
+                const value = opts[opt.long];
+                const values = Array.isArray(value) ? value : [value];
+                const choices = opt.choices;
+                for (const v of values) {
+                    if (!choices.includes(v)) {
+                        throw new CommanderError('InvalidChoice', `invalid value "${v}" for option "--${camelToKebabCase$2(opt.long)}". Allowed: ${opt.choices.join(', ')}`, commandPath);
+                    }
+                }
+            }
+        }
+        if (isNoColorEnabled(envs) && !sawColorToken && opts['color'] === true) {
+            opts['color'] = false;
         }
-        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(),
+            opts,
+            explicitOptionLongs,
         };
     }
-    #resolveHelpCommand(leafCommand, helpTarget) {
-        if (helpTarget === undefined) {
-            return leafCommand;
+    applyBuiltinDevmodeLogLevel(params) {
+        const { opts, explicitOptionLongs, builtinOption, hasUserOption } = params;
+        const hasBuiltinDevmode = builtinOption.devmode;
+        const hasBuiltinLogLevel = builtinOption.logLevel && !hasUserOption('logLevel');
+        if (!hasBuiltinDevmode || !hasBuiltinLogLevel) {
+            return;
+        }
+        if (opts['devmode'] !== true) {
+            return;
         }
-        const target = leafCommand.#findSubcommandEntry(helpTarget);
-        if (target === undefined) {
-            return leafCommand;
+        if (explicitOptionLongs.has('logLevel')) {
+            return;
         }
-        return target.command;
+        opts['logLevel'] = 'debug';
     }
-    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 profileScanResult = this.#scanPresetProfileDirectives(beforeSeparator, commandPath);
-        const cleanArgv = separatorIndex === -1
-            ? profileScanResult.cleanArgv
-            : [...profileScanResult.cleanArgv, '--', ...afterSeparator];
-        const commandChain = ctx.chain;
-        const commandPresetFile = this.#resolveCommandPresetFileFromChain(commandChain);
-        const effectivePresetFile = profileScanResult.presetFile ?? commandPresetFile;
-        const commandPresetProfile = this.#resolveCommandPresetProfileFromChain(commandChain);
-        const useCommandPresetProfile = profileScanResult.presetProfile === undefined && commandPresetProfile !== undefined;
-        if (useCommandPresetProfile) {
-            this.#assertPresetProfileSelectorValue(commandPresetProfile, 'command.preset.profile', commandPath);
-        }
-        const effectivePresetProfile = profileScanResult.presetProfile ?? commandPresetProfile;
-        const effectivePresetProfileSourceName = profileScanResult.presetProfile !== undefined
-            ? PRESET_PROFILE_FLAG
-            : commandPresetProfile !== undefined
-                ? 'command.preset.profile'
-                : undefined;
-        if (effectivePresetFile === undefined && useCommandPresetProfile) {
-            throw new CommanderError('ConfigurationError', 'cannot use "command.preset.profile" without "command.preset.file" or "--preset-file"', commandPath);
-        }
-        const resolvedProfile = await this.#resolvePresetProfile({
-            presetFile: effectivePresetFile,
-            presetProfile: effectivePresetProfile,
-            presetProfileSourceName: effectivePresetProfileSourceName,
-            commandPath,
-        });
-        const userSources = {
-            cmds: [...ctx.sources.user.cmds],
-            argv: [...cleanArgv],
-            envs: { ...ctx.sources.user.envs },
+    resolveBuiltinParsedOptions(params) {
+        const { opts, builtinOption, hasUserOption } = params;
+        const builtin = {
+            devmode: builtinOption.devmode ? Boolean(opts['devmode']) : false,
         };
-        const presetArgv = [];
-        if (resolvedProfile !== undefined && resolvedProfile.optsArgv.length > 0) {
-            this.#validatePresetOptionTokens(resolvedProfile.optsArgv, resolvedProfile.optsSourceLabel, commandPath);
-            this.#assertPresetOptionFragments(resolvedProfile.optsArgv, resolvedProfile.optsSourceLabel, commandChain, optionPolicyMap);
-            presetArgv.push(...resolvedProfile.optsArgv);
-        }
-        const presetEnvs = {};
-        if (resolvedProfile !== undefined) {
-            if (resolvedProfile.profileEnvFileSource !== undefined) {
-                const content = await this.#readPresetFile(resolvedProfile.profileEnvFileSource, commandPath);
-                if (content !== undefined) {
-                    const parsed = this.#parsePresetEnvsContent(content, resolvedProfile.profileEnvFileSource, commandPath);
-                    Object.assign(presetEnvs, parsed);
-                }
-            }
-            Object.assign(presetEnvs, resolvedProfile.profileInlineEnvs);
-            if (resolvedProfile.variantEnvFileSource !== undefined) {
-                const content = await this.#readPresetFile(resolvedProfile.variantEnvFileSource, commandPath);
-                if (content !== undefined) {
-                    const parsed = this.#parsePresetEnvsContent(content, resolvedProfile.variantEnvFileSource, commandPath);
-                    Object.assign(presetEnvs, parsed);
-                }
-            }
-            Object.assign(presetEnvs, resolvedProfile.variantInlineEnvs);
+        if (builtinOption.color && !hasUserOption('color')) {
+            builtin.color = Boolean(opts['color']);
         }
-        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 };
-    }
-    #resolveCommandPresetFileFromChain(chain) {
-        for (let index = chain.length - 1; index >= 0; index -= 1) {
-            const preset = chain[index].#presetConfig;
-            if (preset?.file !== undefined) {
-                return preset.file;
+        if (builtinOption.logLevel && !hasUserOption('logLevel')) {
+            const logLevel = opts['logLevel'];
+            if (typeof logLevel === 'string') {
+                builtin.logLevel = logLevel;
             }
         }
-        return undefined;
-    }
-    #resolveCommandPresetProfileFromChain(chain) {
-        for (let index = chain.length - 1; index >= 0; index -= 1) {
-            const preset = chain[index].#presetConfig;
-            if (preset?.profile !== undefined) {
-                return preset.profile;
-            }
+        if (builtinOption.silent && !hasUserOption('silent')) {
+            builtin.silent = Boolean(opts['silent']);
         }
-        return undefined;
+        if (builtinOption.logDate && !hasUserOption('logDate')) {
+            builtin.logDate = Boolean(opts['logDate']);
+        }
+        if (builtinOption.logColorful && !hasUserOption('logColorful')) {
+            builtin.logColorful = Boolean(opts['logColorful']);
+        }
+        return builtin;
     }
-    #resolvePresetFileAbsolutePath(filepath, baseDirectory) {
-        if (this.#runtime.isAbsolute(filepath)) {
-            return filepath;
+    #convertValue(opt, rawValue, commandPath) {
+        if (opt.coerce) {
+            return opt.coerce(rawValue);
+        }
+        if (opt.type === 'number') {
+            const num = parsePrimitiveNumber(rawValue);
+            if (num === undefined) {
+                throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${camelToKebabCase$2(opt.long)}"`, commandPath);
+            }
+            return num;
         }
-        return this.#runtime.resolve(baseDirectory ?? this.#runtime.cwd(), filepath);
+        return rawValue;
     }
-    async #resolvePresetProfile(params) {
+}
+
+const PRESET_FILE_FLAG = '--preset-file';
+const PRESET_PROFILE_FLAG = '--preset-profile';
+const PRESET_SELECTOR_DELIMITER = ':';
+const PRESET_PROFILE_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const PRESET_VARIANT_NAME_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function kebabToCamelCase$1(str) {
+    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function camelToKebabCase$1(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+class CommandPresetProfileParser {
+    #resolvePresetFileAbsolutePath;
+    #resolvePath;
+    #readPresetFile;
+    constructor(params) {
+        this.#resolvePresetFileAbsolutePath = params.resolvePresetFileAbsolutePath;
+        this.#resolvePath = params.resolvePath;
+        this.#readPresetFile = params.readPresetFile;
+    }
+    async resolvePresetProfile(params) {
         const { presetFile, presetProfile, presetProfileSourceName, commandPath } = params;
         if (presetFile === undefined) {
             if (presetProfile !== undefined) {
@@ -1127,11 +1772,14 @@ class Command {
             return undefined;
         }
         const manifest = this.#parsePresetProfileManifest(content, profileFile.displayPath, commandPath);
-        const resolvedProfileSelector = presetProfile ?? manifest.defaults?.profile;
-        if (resolvedProfileSelector === undefined) {
-            throw new CommanderError('ConfigurationError', `missing profile for preset file "${profileFile.displayPath}": provide "${PRESET_PROFILE_FLAG}" or defaults.profile`, commandPath);
-        }
-        const { profileName: resolvedProfileName, variantName: explicitVariantName } = this.#parsePresetProfileSelector(resolvedProfileSelector, presetProfileSourceName ?? 'defaults.profile', commandPath);
+        const resolvedProfileSelector = this.#resolvePresetProfileSelector({
+            presetProfile,
+            presetProfileSourceName,
+            manifest,
+            commandPath,
+            presetFileDisplayPath: profileFile.displayPath,
+        });
+        const { profileName: resolvedProfileName, variantName: explicitVariantName } = this.#parsePresetProfileSelector(resolvedProfileSelector.selector, resolvedProfileSelector.sourceName, commandPath);
         const profile = manifest.profiles[resolvedProfileName];
         if (profile === undefined) {
             throw new CommanderError('ConfigurationError', `unknown preset profile "${resolvedProfileName}" in "${profileFile.displayPath}"`, commandPath);
@@ -1152,9 +1800,9 @@ class Command {
             : `${resolvedProfileName}${PRESET_SELECTOR_DELIMITER}${selectedVariantName}`;
         const mergedOpts = { ...(profile.opts ?? {}), ...(selectedVariant?.opts ?? {}) };
         const optsArgv = this.#buildPresetArgvFromProfileOptions(mergedOpts, profileSelectorLabel, commandPath);
-        const profileInlineEnvs = this.#normalizePresetProfileEnvs(profile.envs, profileSelectorLabel, commandPath);
-        const variantInlineEnvs = this.#normalizePresetProfileEnvs(selectedVariant?.envs, profileSelectorLabel, commandPath);
-        const profileDir = this.#runtime.resolve(profileFile.absolutePath, '..');
+        const profileInlineEnvs = this.#normalizePresetProfileEnvs(profile.envs);
+        const variantInlineEnvs = this.#normalizePresetProfileEnvs(selectedVariant?.envs);
+        const profileDir = this.#resolvePath(profileFile.absolutePath, '..');
         let profileEnvFileSource;
         if (profile.envFile !== undefined) {
             profileEnvFileSource = {
@@ -1176,19 +1824,95 @@ class Command {
             variantName: selectedVariantName,
             optsArgv,
             optsSourceLabel: `${profileFile.displayPath}#${profileSelectorLabel}.opts`,
+            issueMeta: {
+                file: profileFile.displayPath,
+                profile: resolvedProfileName,
+                variant: selectedVariantName,
+            },
             profileInlineEnvs,
             variantInlineEnvs,
             profileEnvFileSource,
             variantEnvFileSource,
         };
     }
-    #parsePresetProfileManifest(content, filepath, commandPath) {
-        let parsed;
-        try {
-            parsed = JSON.parse(content);
-        }
-        catch (error) {
-            throw new CommanderError('ConfigurationError', `failed to parse preset file "${filepath}": ${error.message}`, commandPath);
+    assertPresetProfileSelectorValue(selector, sourceName, commandPath) {
+        void this.#parsePresetProfileSelector(selector, sourceName, commandPath);
+    }
+    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_FILE_FLAG ||
+                token.startsWith(`${PRESET_FILE_FLAG}=`) ||
+                token === PRESET_PROFILE_FLAG ||
+                token.startsWith(`${PRESET_PROFILE_FLAG}=`)) {
+                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": preset directive "${token}" is not allowed`, commandPath);
+            }
+        }
+    }
+    #resolvePresetProfileSelector(params) {
+        const { presetProfile, presetProfileSourceName, manifest, commandPath, presetFileDisplayPath } = params;
+        if (presetProfile !== undefined) {
+            return {
+                selector: presetProfile,
+                sourceName: presetProfileSourceName ?? PRESET_PROFILE_FLAG,
+            };
+        }
+        const commandPathSuffixProfile = this.#resolveProfileNameByCommandPathSuffix({
+            commandPath,
+            profiles: manifest.profiles,
+        });
+        if (commandPathSuffixProfile !== undefined) {
+            return {
+                selector: commandPathSuffixProfile,
+                sourceName: 'commandPath.suffix',
+            };
+        }
+        if (manifest.defaults?.profile !== undefined) {
+            return {
+                selector: manifest.defaults.profile,
+                sourceName: 'defaults.profile',
+            };
+        }
+        if (manifest.profiles.default !== undefined) {
+            return {
+                selector: 'default',
+                sourceName: 'profiles["default"]',
+            };
+        }
+        throw new CommanderError('ConfigurationError', `missing profile for preset file "${presetFileDisplayPath}": provide "${PRESET_PROFILE_FLAG}", define command-path suffix profile, defaults.profile, or profile "default"`, commandPath);
+    }
+    #resolveProfileNameByCommandPathSuffix(params) {
+        const { commandPath, profiles } = params;
+        const commandNames = commandPath
+            .split(' ')
+            .map(value => value.trim())
+            .filter(Boolean);
+        for (let index = 0; index < commandNames.length; index += 1) {
+            const profileName = commandNames.slice(index).join('.');
+            if (profiles[profileName] !== undefined) {
+                return profileName;
+            }
+        }
+        return undefined;
+    }
+    #parsePresetProfileManifest(content, filepath, commandPath) {
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            throw new CommanderError('ConfigurationError', `failed to parse preset file "${filepath}": ${error.message}`, commandPath);
         }
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
             throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": root must be an object`, commandPath);
@@ -1208,7 +1932,7 @@ class Command {
                 if (typeof defaultsRecord.profile !== 'string') {
                     throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": "defaults.profile" must be a string`, commandPath);
                 }
-                this.#assertPresetProfileSelectorValue(defaultsRecord.profile, 'defaults.profile', commandPath);
+                this.assertPresetProfileSelectorValue(defaultsRecord.profile, 'defaults.profile', commandPath);
             }
             defaults = { profile: defaultsRecord.profile };
         }
@@ -1364,7 +2088,7 @@ class Command {
         }
         throw new CommanderError('ConfigurationError', `${valueLabel} must be boolean|string|number|(string|number)[]`, commandPath);
     }
-    #normalizePresetProfileEnvs(envs, _profileName, _commandPath) {
+    #normalizePresetProfileEnvs(envs) {
         return envs === undefined ? {} : { ...envs };
     }
     #normalizePresetOptionName(rawName, profileName, commandPath) {
@@ -1381,7 +2105,7 @@ class Command {
             if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(lowered)) {
                 throw new CommanderError('ConfigurationError', `invalid option name "${rawName}" in preset profile "${profileName}"`, commandPath);
             }
-            return kebabToCamelCase(lowered);
+            return kebabToCamelCase$1(lowered);
         }
         if (!/^[a-z][a-zA-Z0-9]*$/.test(stripped)) {
             throw new CommanderError('ConfigurationError', `invalid option name "${rawName}" in preset profile "${profileName}"`, commandPath);
@@ -1392,7 +2116,7 @@ class Command {
         const argv = [];
         for (const [rawName, rawValue] of Object.entries(opts)) {
             const optionName = this.#normalizePresetOptionName(rawName, profileName, commandPath);
-            const kebabName = camelToKebabCase(optionName);
+            const kebabName = camelToKebabCase$1(optionName);
             const positiveFlag = `--${kebabName}`;
             const negativeFlag = `--no-${kebabName}`;
             if (typeof rawValue === 'boolean') {
@@ -1414,80 +2138,6 @@ class Command {
         }
         return argv;
     }
-    #scanPresetProfileDirectives(argv, commandPath) {
-        const cleanArgv = [];
-        let presetFile;
-        let presetProfile;
-        const assignDirective = (flag, value) => {
-            if (flag === PRESET_FILE_FLAG) {
-                presetFile = value;
-            }
-            else {
-                this.#assertPresetProfileSelectorValue(value, PRESET_PROFILE_FLAG, commandPath);
-                presetProfile = value;
-            }
-        };
-        let index = 0;
-        while (index < argv.length) {
-            const token = argv[index];
-            if (token === PRESET_FILE_FLAG || token === PRESET_PROFILE_FLAG) {
-                const value = argv[index + 1];
-                if (value === undefined || value.length === 0) {
-                    throw new CommanderError('ConfigurationError', `missing value for "${token}"`, commandPath);
-                }
-                assignDirective(token, value);
-                index += 2;
-                continue;
-            }
-            if (token.startsWith(`${PRESET_FILE_FLAG}=`)) {
-                const value = token.slice(PRESET_FILE_FLAG.length + 1);
-                if (value.length === 0) {
-                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_FILE_FLAG}"`, commandPath);
-                }
-                assignDirective(PRESET_FILE_FLAG, value);
-                index += 1;
-                continue;
-            }
-            if (token.startsWith(`${PRESET_PROFILE_FLAG}=`)) {
-                const value = token.slice(PRESET_PROFILE_FLAG.length + 1);
-                if (value.length === 0) {
-                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_PROFILE_FLAG}"`, commandPath);
-                }
-                assignDirective(PRESET_PROFILE_FLAG, value);
-                index += 1;
-                continue;
-            }
-            cleanArgv.push(token);
-            index += 1;
-        }
-        return { cleanArgv, presetFile, presetProfile };
-    }
-    #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;
-        }
-    }
-    #assertPresetProfileSelectorValue(selector, sourceName, commandPath) {
-        void this.#parsePresetProfileSelector(selector, sourceName, commandPath);
-    }
     #parsePresetProfileSelector(selector, sourceName, commandPath) {
         const normalizedSelector = selector.trim();
         const separatorIndex = normalizedSelector.indexOf(PRESET_SELECTOR_DELIMITER);
@@ -1519,713 +2169,1387 @@ class Command {
         }
         throw new CommanderError('ConfigurationError', `invalid variant name for "${sourceName}": "${variantName}" (must match ${PRESET_VARIANT_NAME_REGEX.source})`, commandPath);
     }
-    async #readPresetFile(file, commandPath) {
-        try {
-            const stats = await this.#runtime.stat(file.absolutePath);
-            if (stats.isDirectory()) {
-                throw new Error('target is a directory');
-            }
-            return await this.#runtime.readFile(file.absolutePath);
+}
+
+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 devmodeOption = {
+    long: 'devmode',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable development mode',
+    default: false,
+};
+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}`);
         }
-        catch (error) {
-            const ioError = error;
-            if (!file.explicit && ioError.code === 'ENOENT') {
-                return undefined;
-            }
-            throw new CommanderError('ConfigurationError', `failed to read preset file "${file.displayPath}": ${error.message}`, commandPath);
+        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');
         }
+    },
+};
+
+const BUILTIN_COLOR_OPTION = {
+    long: 'color',
+    type: 'boolean',
+    args: 'none',
+    desc: 'Enable colored help output',
+    default: true,
+};
+function resolveOptionPolicy(params) {
+    const { builtinOption, localOptions } = params;
+    const optionMap = new Map();
+    const hasUserOption = (long) => localOptions.some(option => option.long === long);
+    if (builtinOption.color && !hasUserOption('color')) {
+        optionMap.set('color', BUILTIN_COLOR_OPTION);
     }
-    #parsePresetEnvsContent(content, file, commandPath) {
-        try {
-            return parse(content);
-        }
-        catch (error) {
-            throw new CommanderError('ConfigurationError', `failed to parse preset env file "${file.displayPath}": ${error.message}`, commandPath);
-        }
+    if (builtinOption.devmode) {
+        optionMap.set('devmode', devmodeOption);
     }
-    #validatePresetOptionTokens(tokens, filepath, commandPath) {
-        if (tokens.length === 0) {
-            return;
+    if (builtinOption.logLevel && !hasUserOption('logLevel')) {
+        optionMap.set('logLevel', logLevelOption);
+    }
+    if (builtinOption.silent && !hasUserOption('silent')) {
+        optionMap.set('silent', silentOption);
+    }
+    if (builtinOption.logDate && !hasUserOption('logDate')) {
+        optionMap.set('logDate', logDateOption);
+    }
+    if (builtinOption.logColorful && !hasUserOption('logColorful')) {
+        optionMap.set('logColorful', logColorfulOption);
+    }
+    for (const option of localOptions) {
+        optionMap.set(option.long, option);
+    }
+    return {
+        mergedOptions: Array.from(optionMap.values()),
+    };
+}
+function buildOptionPolicyMap(params) {
+    const { chain, resolveOptionPolicy } = params;
+    const optionPolicyMap = new Map();
+    for (const command of chain) {
+        optionPolicyMap.set(command, resolveOptionPolicy(command));
+    }
+    return optionPolicyMap;
+}
+function mustGetOptionPolicy(params) {
+    const { optionPolicyMap, command, resolveOptionPolicy } = params;
+    const policy = optionPolicyMap.get(command) ?? resolveOptionPolicy(command);
+    optionPolicyMap.set(command, policy);
+    return policy;
+}
+
+function scanControl(params) {
+    const { tailArgv, supportsBuiltinVersion } = params;
+    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 index = scanStartIndex; index < beforeSeparator.length; index += 1) {
+        const token = beforeSeparator[index];
+        if (token === '--help') {
+            controls.help = true;
+            continue;
         }
-        if (!tokens[0].startsWith('-')) {
-            throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": bare token "${tokens[0]}" cannot appear before any option token`, commandPath);
+        if (token === '--version' && supportsBuiltinVersion) {
+            controls.version = true;
+            continue;
         }
-        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_FILE_FLAG ||
-                token.startsWith(`${PRESET_FILE_FLAG}=`) ||
-                token === PRESET_PROFILE_FLAG ||
-                token.startsWith(`${PRESET_PROFILE_FLAG}=`)) {
-                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": preset directive "${token}" is not allowed`, commandPath);
-            }
+        remainingBeforeSeparator.push(token);
+    }
+    return {
+        controls,
+        remaining: separatorIndex === -1
+            ? remainingBeforeSeparator
+            : [...remainingBeforeSeparator, '--', ...afterSeparator],
+        helpTarget,
+    };
+}
+function runControl(params) {
+    const { leafCommand, controlScanResult, resolveHelpCommand, getCommandPath, getCommandVersion } = params;
+    if (controlScanResult.controls.help) {
+        const helpCommand = resolveHelpCommand(leafCommand, controlScanResult.helpTarget);
+        return {
+            kind: 'help',
+            targetCommandPath: getCommandPath(helpCommand),
+        };
+    }
+    if (controlScanResult.controls.version) {
+        const version = getCommandVersion(leafCommand);
+        if (version !== undefined) {
+            return {
+                kind: 'version',
+                targetCommandPath: getCommandPath(leafCommand),
+                version,
+            };
         }
     }
-    #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 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) {
-                shadowed.add(opt.long);
-            }
-        }
-        const argTokens = [];
-        for (const token of remaining) {
-            if (token.type !== 'none') {
-                const leafCommand = chain[chain.length - 1];
-                throw new CommanderError('UnknownOption', `unknown option "${token.original}" for command "${leafCommand.#getCommandPath()}"`, leafCommand.#getCommandPath());
-            }
-            argTokens.push(token);
-        }
-        return { consumedTokens, argTokens };
-    }
-    #shift(tokens, shadowed, allOptions) {
-        const effectiveOptions = allOptions.filter(o => !shadowed.has(o.long));
-        const optionByLong = new Map();
-        const optionByShort = new Map();
-        for (const opt of effectiveOptions) {
-            optionByLong.set(opt.long, opt);
-            if (opt.short) {
-                optionByShort.set(opt.short, opt);
-            }
+    return undefined;
+}
+
+function resolveStage(params) {
+    const { chain, tokens, optionPolicyMap, mustGetOptionPolicy, getLocalOptions, getCommandPath, withUnknownOptionIssue, } = params;
+    try {
+        return resolveTokensByChain({
+            chain,
+            tokens,
+            optionPolicyMap,
+            mustGetOptionPolicy,
+            getLocalOptions,
+            getCommandPath,
+        });
+    }
+    catch (error) {
+        if (error instanceof CommanderError && error.kind === 'UnknownOption') {
+            const unresolvedToken = error.meta?.token === undefined
+                ? undefined
+                : tokens.find(token => token.original === error.meta?.token);
+            throw withUnknownOptionIssue(error, unresolvedToken);
         }
-        const consumed = [];
-        const remaining = [];
-        let i = 0;
-        while (i < tokens.length) {
-            const token = tokens[i];
-            if (token.type === 'long') {
-                const opt = optionByLong.get(token.name);
-                if (opt) {
-                    consumed.push(token);
-                    if (opt.args === 'required') {
-                        if (!token.resolved.includes('=') && i + 1 < tokens.length) {
-                            i += 1;
-                            consumed.push(tokens[i]);
-                        }
+        throw error;
+    }
+}
+function shiftTokens(params) {
+    const { tokens, shadowed, allOptions } = params;
+    const effectiveOptions = allOptions.filter(option => !shadowed.has(option.long));
+    const optionByLong = new Map();
+    const optionByShort = new Map();
+    for (const option of effectiveOptions) {
+        optionByLong.set(option.long, option);
+        if (option.short) {
+            optionByShort.set(option.short, option);
+        }
+    }
+    const consumed = [];
+    const remaining = [];
+    let index = 0;
+    while (index < tokens.length) {
+        const token = tokens[index];
+        if (token.type === 'long') {
+            const option = optionByLong.get(token.name);
+            if (option !== undefined) {
+                consumed.push(token);
+                if (option.args === 'required') {
+                    if (!token.resolved.includes('=') && index + 1 < tokens.length) {
+                        index += 1;
+                        consumed.push(tokens[index]);
                     }
-                    else if (opt.args === 'optional') {
-                        if (!token.resolved.includes('=') &&
-                            i + 1 < tokens.length &&
-                            tokens[i + 1].type === 'none') {
-                            i += 1;
-                            consumed.push(tokens[i]);
-                        }
+                }
+                else if (option.args === 'optional') {
+                    if (!token.resolved.includes('=') &&
+                        index + 1 < tokens.length &&
+                        tokens[index + 1].type === 'none') {
+                        index += 1;
+                        consumed.push(tokens[index]);
                     }
-                    else if (opt.args === 'variadic') {
-                        if (!token.resolved.includes('=')) {
-                            while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                                i += 1;
-                                consumed.push(tokens[i]);
-                            }
-                        }
+                }
+                else if (option.args === 'variadic' && !token.resolved.includes('=')) {
+                    while (index + 1 < tokens.length && tokens[index + 1].type === 'none') {
+                        index += 1;
+                        consumed.push(tokens[index]);
                     }
-                    i += 1;
-                    continue;
                 }
-                remaining.push(token);
-                i += 1;
+                index += 1;
                 continue;
             }
-            if (token.type === 'short') {
-                const opt = optionByShort.get(token.name);
-                if (opt) {
-                    consumed.push(token);
-                    if (opt.args === 'required') {
-                        if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                            i += 1;
-                            consumed.push(tokens[i]);
-                        }
-                    }
-                    else if (opt.args === 'optional') {
-                        if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                            i += 1;
-                            consumed.push(tokens[i]);
-                        }
+            remaining.push(token);
+            index += 1;
+            continue;
+        }
+        if (token.type === 'short') {
+            const option = optionByShort.get(token.name);
+            if (option !== undefined) {
+                consumed.push(token);
+                if (option.args === 'required' || option.args === 'optional') {
+                    if (index + 1 < tokens.length && tokens[index + 1].type === 'none') {
+                        index += 1;
+                        consumed.push(tokens[index]);
                     }
-                    else if (opt.args === 'variadic') {
-                        while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                            i += 1;
-                            consumed.push(tokens[i]);
-                        }
+                }
+                else if (option.args === 'variadic') {
+                    while (index + 1 < tokens.length && tokens[index + 1].type === 'none') {
+                        index += 1;
+                        consumed.push(tokens[index]);
                     }
-                    i += 1;
-                    continue;
                 }
-                remaining.push(token);
-                i += 1;
+                index += 1;
                 continue;
             }
             remaining.push(token);
-            i += 1;
+            index += 1;
+            continue;
         }
-        return { consumed, remaining };
+        remaining.push(token);
+        index += 1;
     }
-    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
-        const { consumedTokens, argTokens } = resolveResult;
-        const leafCommand = chain[chain.length - 1];
-        this.#validateMergedShortOptions(chain, optionPolicyMap);
-        const optsMap = new Map();
-        for (const cmd of chain) {
-            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
-            const tokens = consumedTokens.get(cmd) ?? [];
-            const opts = cmd.#parseOptions(tokens, policy.mergedOptions, ctx.envs);
-            optsMap.set(cmd, opts);
-            for (const opt of policy.mergedOptions) {
-                if (opt.apply && opts[opt.long] !== undefined) {
-                    opt.apply(opts[opt.long], ctx);
-                }
-            }
+    return { consumed, remaining };
+}
+function resolveTokensByChain(params) {
+    const { chain, tokens, optionPolicyMap, mustGetOptionPolicy, getLocalOptions, getCommandPath } = params;
+    const consumedTokens = new Map();
+    let remaining = [...tokens];
+    const shadowed = new Set();
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const command = chain[index];
+        const policy = mustGetOptionPolicy(optionPolicyMap, command);
+        const result = shiftTokens({
+            tokens: remaining,
+            shadowed,
+            allOptions: policy.mergedOptions,
+        });
+        consumedTokens.set(command, result.consumed);
+        remaining = result.remaining;
+        for (const option of getLocalOptions(command)) {
+            shadowed.add(option.long);
+        }
+    }
+    const leafCommand = chain[chain.length - 1];
+    const leafCommandPath = getCommandPath(leafCommand);
+    const argTokens = [];
+    for (const token of remaining) {
+        if (token.type !== 'none') {
+            throw new CommanderError('UnknownOption', `unknown option "${token.original}" for command "${leafCommandPath}"`, leafCommandPath, {
+                commandPath: leafCommandPath,
+                token: token.original,
+                issues: [],
+            });
         }
-        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];
-            }
+        argTokens.push(token);
+    }
+    return { consumedTokens, argTokens };
+}
+function validateMergedShortOptions(params) {
+    const { chain, optionPolicyMap, mustGetOptionPolicy, rootCommandPath } = params;
+    const mergedByLong = new Map();
+    for (const command of chain) {
+        const policy = mustGetOptionPolicy(optionPolicyMap, command);
+        for (const option of policy.mergedOptions) {
+            mergedByLong.set(option.long, option);
+        }
+    }
+    const shortMap = new Map();
+    for (const option of mergedByLong.values()) {
+        if (!option.short) {
+            continue;
         }
-        leafCommand.#assertUnknownSubcommand(ctx.sources.user.argv);
-        const rawArgStrings = [...argTokens.map(t => t.original), ...restArgs];
-        const { args, rawArgs } = leafCommand.#parseArguments(rawArgStrings);
-        const parseCtx = {
-            ...ctx,
-            sources: this.#freezeInputSources(ctx.sources),
-        };
-        return { ctx: parseCtx, opts: leafLocalOpts, args, rawArgs };
+        const existingLong = shortMap.get(option.short);
+        if (existingLong !== undefined && existingLong !== option.long) {
+            throw new CommanderError('OptionConflict', `short option "-${option.short}" conflicts with "--${existingLong}"`, rootCommandPath);
+        }
+        shortMap.set(option.short, option.long);
     }
-    #parseOptions(tokens, allOptions, envs) {
-        const opts = {};
-        let sawColorToken = false;
-        for (const opt of allOptions) {
-            if (opt.default !== undefined) {
-                opts[opt.long] = opt.default;
-            }
-            else if (opt.type === 'boolean' && opt.args === 'none') {
-                opts[opt.long] = false;
-            }
-            else if (opt.args === 'variadic') {
-                opts[opt.long] = [];
-            }
+}
+
+function camelToKebabCase(str) {
+    return str.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+function normalizeSubcommandNameForDistance(name) {
+    return camelToKebabCase(name).toLowerCase();
+}
+function levenshteinDistance(left, right) {
+    if (left === right) {
+        return 0;
+    }
+    if (left.length === 0) {
+        return right.length;
+    }
+    if (right.length === 0) {
+        return left.length;
+    }
+    let prev = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 0; row < left.length; row += 1) {
+        const current = [row + 1];
+        for (let col = 0; col < right.length; col += 1) {
+            const substitutionCost = left[row] === right[col] ? 0 : 1;
+            current[col + 1] = Math.min(current[col] + 1, prev[col + 1] + 1, prev[col] + substitutionCost);
         }
-        const optionByLong = new Map();
-        const optionByShort = new Map();
-        for (const opt of allOptions) {
-            optionByLong.set(opt.long, opt);
-            if (opt.short) {
-                optionByShort.set(opt.short, opt);
-            }
+        prev = current;
+    }
+    return prev[right.length];
+}
+function convertArgumentValue(params) {
+    const { def, raw, commandPath } = params;
+    let value;
+    if (def.coerce) {
+        try {
+            value = def.coerce(raw);
         }
-        let i = 0;
-        while (i < tokens.length) {
-            const token = tokens[i];
-            const opt = token.type === 'long' ? optionByLong.get(token.name) : optionByShort.get(token.name);
-            if (!opt) {
-                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(opt.long)}" can only be used with boolean options`, this.#getCommandPath());
-            }
-            if (opt.type === 'boolean' && opt.args === 'none') {
-                const eqIdx = token.resolved.indexOf('=');
-                if (eqIdx !== -1) {
-                    const value = token.resolved.slice(eqIdx + 1);
-                    if (value === 'true') {
-                        opts[opt.long] = true;
-                    }
-                    else if (value === 'false') {
-                        opts[opt.long] = false;
-                    }
-                    else {
-                        throw new CommanderError('InvalidBooleanValue', `invalid value "${value}" for boolean option "--${camelToKebabCase(opt.long)}". Use "true" or "false"`, this.#getCommandPath());
-                    }
-                }
-                else {
-                    opts[opt.long] = true;
-                }
-                i += 1;
-                continue;
-            }
-            if (opt.args === 'required') {
-                const eqIdx = token.resolved.indexOf('=');
-                let rawValue;
-                if (eqIdx !== -1) {
-                    rawValue = token.resolved.slice(eqIdx + 1);
-                }
-                else if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                    rawValue = tokens[i + 1].original;
-                    i += 1;
-                }
-                else {
-                    throw new CommanderError('MissingValue', `option "--${camelToKebabCase(opt.long)}" requires a value`, this.#getCommandPath());
-                }
-                opts[opt.long] = this.#convertValue(opt, rawValue);
-                i += 1;
-                continue;
-            }
-            if (opt.args === 'optional') {
-                const eqIdx = token.resolved.indexOf('=');
-                if (eqIdx !== -1) {
-                    opts[opt.long] = this.#convertValue(opt, token.resolved.slice(eqIdx + 1));
-                    i += 1;
-                    continue;
-                }
-                if (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                    opts[opt.long] = this.#convertValue(opt, tokens[i + 1].original);
-                    i += 1;
-                }
-                else {
-                    opts[opt.long] = undefined;
-                }
-                i += 1;
-                continue;
+        catch {
+            throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, commandPath);
+        }
+    }
+    else {
+        value = raw;
+    }
+    if (typeof value !== 'string') {
+        throw new CommanderError('InvalidType', `invalid value for argument "${def.name}": expected ${def.type}`, commandPath);
+    }
+    if (def.type === 'choice') {
+        const choices = def.choices ?? [];
+        if (!choices.includes(value)) {
+            throw new CommanderError('InvalidChoice', `invalid value "${value}" for argument "${def.name}". Allowed: ${choices
+                .map(choice => JSON.stringify(choice))
+                .join(', ')}`, commandPath);
+        }
+    }
+    return value;
+}
+function parseArguments(params) {
+    const { argumentDefs, rawArgs, commandPath } = params;
+    const args = {};
+    if (argumentDefs.length === 0 && rawArgs.length > 0) {
+        throw new CommanderError('UnexpectedArgument', `unexpected argument "${rawArgs[0]}"`, commandPath);
+    }
+    const missing = [];
+    let remaining = rawArgs.length;
+    for (const def of argumentDefs) {
+        if (def.kind === 'required') {
+            if (remaining === 0) {
+                missing.push(def.name);
             }
-            if (opt.args === 'variadic') {
-                const values = Array.isArray(opts[opt.long]) ? opts[opt.long] : [];
-                const eqIdx = token.resolved.indexOf('=');
-                if (eqIdx !== -1) {
-                    values.push(this.#convertValue(opt, token.resolved.slice(eqIdx + 1)));
-                }
-                else {
-                    while (i + 1 < tokens.length && tokens[i + 1].type === 'none') {
-                        i += 1;
-                        values.push(this.#convertValue(opt, tokens[i].original));
-                    }
-                }
-                opts[opt.long] = values;
-                i += 1;
-                continue;
+            else {
+                remaining -= 1;
             }
-            i += 1;
+            continue;
         }
-        for (const opt of allOptions) {
-            if (opt.required && !Object.prototype.hasOwnProperty.call(opts, opt.long)) {
-                throw new CommanderError('MissingRequired', `missing required option "--${camelToKebabCase(opt.long)}"`, this.#getCommandPath());
+        if (def.kind === 'optional') {
+            if (remaining > 0) {
+                remaining -= 1;
             }
+            continue;
         }
-        for (const opt of allOptions) {
-            if (opt.choices && opts[opt.long] !== undefined) {
-                const value = opts[opt.long];
-                const values = Array.isArray(value) ? value : [value];
-                const choices = opt.choices;
-                for (const v of values) {
-                    if (!choices.includes(v)) {
-                        throw new CommanderError('InvalidChoice', `invalid value "${v}" for option "--${camelToKebabCase(opt.long)}". Allowed: ${opt.choices.join(', ')}`, this.#getCommandPath());
-                    }
-                }
+        if (def.kind === 'some') {
+            if (remaining === 0) {
+                missing.push(def.name);
             }
+            remaining = 0;
+            continue;
         }
-        if (isNoColorEnabled(envs) && !sawColorToken && opts['color'] === true) {
-            opts['color'] = false;
-        }
-        return opts;
+        remaining = 0;
     }
-    #convertValue(opt, rawValue) {
-        if (opt.coerce) {
-            return opt.coerce(rawValue);
-        }
-        if (opt.type === 'number') {
-            const num = parsePrimitiveNumber(rawValue);
-            if (num === undefined) {
-                throw new CommanderError('InvalidType', `invalid number "${rawValue}" for option "--${camelToKebabCase(opt.long)}"`, this.#getCommandPath());
-            }
-            return num;
-        }
-        return rawValue;
+    if (missing.length > 0) {
+        throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, commandPath);
     }
-    #parseArguments(rawArgs) {
-        const argumentDefs = this.#arguments;
-        const args = {};
-        if (argumentDefs.length === 0 && rawArgs.length > 0) {
-            throw new CommanderError('UnexpectedArgument', `unexpected argument "${rawArgs[0]}"`, this.#getCommandPath());
-        }
-        const missing = [];
-        let remaining = rawArgs.length;
-        for (const def of argumentDefs) {
-            if (def.kind === 'required') {
-                if (remaining === 0) {
-                    missing.push(def.name);
-                }
-                else {
-                    remaining -= 1;
-                }
-                continue;
-            }
-            if (def.kind === 'optional') {
-                if (remaining > 0) {
-                    remaining -= 1;
-                }
-                continue;
-            }
-            if (def.kind === 'some') {
-                if (remaining === 0) {
-                    missing.push(def.name);
-                }
-                remaining = 0;
-                continue;
-            }
-            remaining = 0;
+    let index = 0;
+    for (const def of argumentDefs) {
+        if (def.kind === 'variadic' || def.kind === 'some') {
+            const rest = rawArgs.slice(index);
+            args[def.name] = rest.map(raw => convertArgumentValue({ def, raw, commandPath }));
+            index = rawArgs.length;
+            break;
         }
-        if (missing.length > 0) {
-            throw new CommanderError('MissingRequiredArgument', `missing required argument(s): ${missing.join(', ')}`, this.#getCommandPath());
-        }
-        let index = 0;
-        for (const def of argumentDefs) {
-            if (def.kind === 'variadic') {
-                const rest = rawArgs.slice(index);
-                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
-                index = rawArgs.length;
-                break;
-            }
-            if (def.kind === 'some') {
-                const rest = rawArgs.slice(index);
-                args[def.name] = rest.map(raw => this.#convertArgument(def, raw));
-                index = rawArgs.length;
-                break;
-            }
-            if (def.kind === 'optional') {
-                const raw = rawArgs[index];
-                if (raw === undefined) {
-                    args[def.name] = def.default ?? undefined;
-                    continue;
-                }
-                args[def.name] = this.#convertArgument(def, raw);
-                index += 1;
+        if (def.kind === 'optional') {
+            const raw = rawArgs[index];
+            if (raw === undefined) {
+                args[def.name] = def.default ?? undefined;
                 continue;
             }
-            const raw = rawArgs[index];
-            args[def.name] = this.#convertArgument(def, raw);
+            args[def.name] = convertArgumentValue({ def, raw, commandPath });
             index += 1;
+            continue;
         }
-        const hasRestArgument = argumentDefs.some(a => a.kind === 'variadic' || a.kind === 'some');
-        if (!hasRestArgument && index < rawArgs.length) {
-            throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, this.#getCommandPath());
-        }
-        return { args, rawArgs };
+        const raw = rawArgs[index];
+        args[def.name] = convertArgumentValue({ def, raw, commandPath });
+        index += 1;
     }
-    #convertArgument(def, raw) {
-        let value;
-        if (def.coerce) {
-            try {
-                value = def.coerce(raw);
-            }
-            catch {
-                throw new CommanderError('InvalidType', `invalid value "${raw}" for argument "${def.name}"`, this.#getCommandPath());
-            }
-        }
-        else {
-            value = raw;
+    const hasRestArgument = argumentDefs.some(def => def.kind === 'variadic' || def.kind === 'some');
+    if (!hasRestArgument && index < rawArgs.length) {
+        throw new CommanderError('TooManyArguments', `too many arguments: expected ${argumentDefs.length}, got ${rawArgs.length}`, commandPath);
+    }
+    return { args, rawArgs };
+}
+function resolveDidYouMeanSubcommandName(token, subcommands) {
+    const source = normalizeSubcommandNameForDistance(token);
+    let minDistance = Number.POSITIVE_INFINITY;
+    let bestName;
+    let isUniqueBest = false;
+    for (const entry of subcommands) {
+        const target = normalizeSubcommandNameForDistance(entry.name);
+        const distance = levenshteinDistance(source, target);
+        if (distance < minDistance) {
+            minDistance = distance;
+            bestName = entry.name;
+            isUniqueBest = true;
+        }
+        else if (distance === minDistance) {
+            isUniqueBest = false;
+        }
+    }
+    if (minDistance <= 2 && isUniqueBest) {
+        return bestName;
+    }
+    return undefined;
+}
+function assertUnknownSubcommand(params) {
+    const { userTailArgv, subcommands, hasArguments, commandPath, withDiagnosticsIssue } = params;
+    if (subcommands.length === 0) {
+        return;
+    }
+    const token = userTailArgv[0];
+    if (token === undefined || token.startsWith('-') || token === 'help') {
+        return;
+    }
+    const matched = subcommands.some(entry => entry.name === token || entry.aliases.includes(token));
+    if (matched) {
+        return;
+    }
+    let error = new CommanderError('UnknownSubcommand', `unknown subcommand "${token}" for command "${commandPath}"`, commandPath);
+    error = withDiagnosticsIssue(error);
+    if (!hasArguments) {
+        const hint = {
+            kind: 'hint',
+            stage: 'parse',
+            scope: 'command',
+            reason: {
+                code: 'command_does_not_accept_positional_arguments',
+                message: `command "${commandPath}" does not accept positional arguments`,
+            },
+        };
+        error = error.withIssue(hint);
+    }
+    const candidate = resolveDidYouMeanSubcommandName(token, subcommands);
+    if (candidate !== undefined) {
+        const hint = {
+            kind: 'hint',
+            stage: 'parse',
+            scope: 'command',
+            reason: {
+                code: 'did_you_mean_subcommand',
+                message: `did you mean "${candidate}"?`,
+                details: { candidate },
+            },
+        };
+        error = error.withIssue(hint);
+    }
+    throw error;
+}
+function collectRawArguments(params) {
+    const { argTokens, restArgs } = params;
+    return [...argTokens.map(token => token.original), ...restArgs];
+}
+function parseStage(params) {
+    const { chain, resolveResult, optionPolicyMap, ctx, restArgs, rootCommandPath, mustGetOptionPolicy, parseOptions, applyBuiltinDevmodeLogLevel, resolveBuiltinParsedOptions, applyOptionCallbacks, getLocalOptions, getSubcommands, getArguments, getCommandPath, withUnknownSubcommandIssue, freezeInputSources, } = params;
+    const { consumedTokens, argTokens } = resolveResult;
+    const leafCommand = chain[chain.length - 1];
+    validateMergedShortOptions({
+        chain,
+        optionPolicyMap,
+        mustGetOptionPolicy: (map, command) => mustGetOptionPolicy(map, command),
+        rootCommandPath,
+    });
+    const optsMap = new Map();
+    const builtinMap = new Map();
+    for (const command of chain) {
+        const policy = mustGetOptionPolicy(optionPolicyMap, command);
+        const tokens = consumedTokens.get(command) ?? [];
+        const commandPath = getCommandPath(command);
+        const parseOptionsResult = parseOptions({
+            command,
+            tokens,
+            allOptions: policy.mergedOptions,
+            envs: ctx.envs,
+            commandPath,
+        });
+        const opts = parseOptionsResult.opts;
+        applyBuiltinDevmodeLogLevel({
+            command,
+            opts,
+            explicitOptionLongs: parseOptionsResult.explicitOptionLongs,
+        });
+        optsMap.set(command, opts);
+        builtinMap.set(command, resolveBuiltinParsedOptions({ command, opts }));
+        applyOptionCallbacks({
+            command,
+            opts,
+            allOptions: policy.mergedOptions,
+            ctx,
+        });
+    }
+    const leafLocalOpts = {};
+    const leafParsedOpts = optsMap.get(leafCommand) ?? {};
+    for (const option of getLocalOptions(leafCommand)) {
+        if (Object.prototype.hasOwnProperty.call(leafParsedOpts, option.long)) {
+            leafLocalOpts[option.long] = leafParsedOpts[option.long];
+        }
+    }
+    const leafCommandPath = getCommandPath(leafCommand);
+    const leafArguments = getArguments(leafCommand);
+    assertUnknownSubcommand({
+        userTailArgv: ctx.sources.user.argv,
+        subcommands: getSubcommands(leafCommand),
+        hasArguments: leafArguments.length > 0,
+        commandPath: leafCommandPath,
+        withDiagnosticsIssue: withUnknownSubcommandIssue,
+    });
+    const rawArgStrings = collectRawArguments({ argTokens, restArgs });
+    const { args, rawArgs } = parseArguments({
+        argumentDefs: leafArguments,
+        rawArgs: rawArgStrings,
+        commandPath: leafCommandPath,
+    });
+    const parseCtx = {
+        ...ctx,
+        sources: freezeInputSources(ctx.sources),
+    };
+    return {
+        ctx: parseCtx,
+        builtin: builtinMap.get(leafCommand) ?? { devmode: false },
+        opts: leafLocalOpts,
+        args,
+        rawArgs,
+    };
+}
+
+function resolvePresetConfigFromChain(params) {
+    const { chain, getPresetConfig } = params;
+    let presetFile;
+    let presetProfile;
+    for (let index = chain.length - 1; index >= 0; index -= 1) {
+        const presetConfig = getPresetConfig(chain[index]);
+        if (presetFile === undefined && presetConfig?.file !== undefined) {
+            presetFile = presetConfig.file;
         }
-        if (typeof value !== 'string') {
-            throw new CommanderError('InvalidType', `invalid value for argument "${def.name}": expected ${def.type}`, this.#getCommandPath());
+        if (presetProfile === undefined && presetConfig?.profile !== undefined) {
+            presetProfile = presetConfig.profile;
         }
-        if (def.type === 'choice') {
-            const choices = def.choices ?? [];
-            if (!choices.includes(value)) {
-                throw new CommanderError('InvalidChoice', `invalid value "${value}" for argument "${def.name}". Allowed: ${choices
-                    .map(choice => JSON.stringify(choice))
-                    .join(', ')}`, this.#getCommandPath());
-            }
+        if (presetFile !== undefined && presetProfile !== undefined) {
+            break;
         }
-        return value;
     }
-    #assertUnknownSubcommand(userTailArgv) {
-        if (this.#subcommandsList.length === 0) {
-            return;
-        }
-        const token = userTailArgv[0];
-        if (token === undefined || token.startsWith('-') || token === 'help') {
-            return;
-        }
-        if (this.#findSubcommandEntry(token) !== undefined) {
+    return { presetFile, presetProfile };
+}
+function scanPresetDirectives(params) {
+    const { argv, commandPath, presetFileFlag, presetProfileFlag, assertPresetProfileSelectorValue } = params;
+    const cleanArgv = [];
+    let presetFile;
+    let presetProfile;
+    const assignDirective = (flag, value) => {
+        if (flag === presetFileFlag) {
+            presetFile = value;
             return;
         }
-        const hints = [];
-        if (this.#arguments.length === 0) {
-            hints.push(`Hint: command "${this.#getCommandPath()}" does not accept positional arguments.`);
-        }
-        const candidate = this.#resolveDidYouMeanSubcommandName(token);
-        if (candidate !== undefined) {
-            hints.push(`Hint: did you mean "${candidate}"?`);
+        assertPresetProfileSelectorValue(value, presetProfileFlag, commandPath);
+        presetProfile = value;
+    };
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index];
+        if (token === presetFileFlag || token === presetProfileFlag) {
+            const value = argv[index + 1];
+            if (value === undefined || value.length === 0) {
+                throw new CommanderError('ConfigurationError', `missing value for "${token}"`, commandPath);
+            }
+            assignDirective(token, value);
+            index += 2;
+            continue;
         }
-        const details = hints.length > 0 ? `\n${hints.join('\n')}` : '';
-        throw new CommanderError('UnknownSubcommand', `unknown subcommand "${token}" for command "${this.#getCommandPath()}"${details}`, this.#getCommandPath());
-    }
-    #resolveDidYouMeanSubcommandName(token) {
-        const source = normalizeSubcommandNameForDistance(token);
-        let minDistance = Number.POSITIVE_INFINITY;
-        let bestName;
-        let isUniqueBest = false;
-        for (const entry of this.#subcommandsList) {
-            const target = normalizeSubcommandNameForDistance(entry.name);
-            const distance = levenshteinDistance(source, target);
-            if (distance < minDistance) {
-                minDistance = distance;
-                bestName = entry.name;
-                isUniqueBest = true;
-            }
-            else if (distance === minDistance) {
-                isUniqueBest = false;
+        if (token.startsWith(`${presetFileFlag}=`)) {
+            const value = token.slice(presetFileFlag.length + 1);
+            if (value.length === 0) {
+                throw new CommanderError('ConfigurationError', `missing value for "${presetFileFlag}"`, commandPath);
             }
+            assignDirective(presetFileFlag, value);
+            index += 1;
+            continue;
         }
-        if (minDistance <= 2 && isUniqueBest) {
-            return bestName;
+        if (token.startsWith(`${presetProfileFlag}=`)) {
+            const value = token.slice(presetProfileFlag.length + 1);
+            if (value.length === 0) {
+                throw new CommanderError('ConfigurationError', `missing value for "${presetProfileFlag}"`, commandPath);
+            }
+            assignDirective(presetProfileFlag, value);
+            index += 1;
+            continue;
         }
+        cleanArgv.push(token);
+        index += 1;
+    }
+    return { cleanArgv, presetFile, presetProfile };
+}
+function buildPresetSources(params) {
+    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta, presetResolvedEnvFile, } = params;
+    const presetSourceMeta = presetMeta === undefined
+        ? undefined
+        : {
+            applied: true,
+            file: presetMeta.file,
+            profile: presetMeta.profile,
+            variant: presetMeta.variant,
+            ...(presetResolvedEnvFile === undefined
+                ? {}
+                : {
+                    resolvedEnvFile: presetResolvedEnvFile,
+                }),
+        };
+    const presetState = presetSourceMeta === undefined ? 'none' : 'applied';
+    const sources = {
+        user: {
+            cmds: [...userCmds],
+            argv: [...userArgv],
+            envs: { ...userEnvs },
+        },
+        preset: {
+            state: presetState,
+            argv: [...presetArgv],
+            envs: { ...presetEnvs },
+            meta: presetSourceMeta === undefined ? undefined : { ...presetSourceMeta },
+        },
+    };
+    const envs = { ...sources.user.envs, ...sources.preset.envs };
+    const tailArgv = [...sources.preset.argv, ...sources.user.argv];
+    const segments = [
+        ...sources.preset.argv.map(value => ({
+            value,
+            source: 'preset',
+            preset: sources.preset.meta === undefined
+                ? undefined
+                : {
+                    file: sources.preset.meta.file,
+                    profile: sources.preset.meta.profile,
+                    variant: sources.preset.meta.variant,
+                },
+        })),
+        ...sources.user.argv.map(value => ({ value, source: 'user' })),
+    ];
+    return {
+        sources,
+        tailArgv,
+        envs,
+        segments,
+    };
+}
+async function resolvePresetStage(params) {
+    const { controlTailArgv, chain, commandPath, presetFileFlag, presetProfileFlag, getPresetConfig, assertPresetProfileSelectorValue, resolvePresetProfile, } = params;
+    const separatorIndex = controlTailArgv.indexOf('--');
+    const beforeSeparator = separatorIndex === -1 ? controlTailArgv : controlTailArgv.slice(0, separatorIndex);
+    const afterSeparator = separatorIndex === -1 ? [] : controlTailArgv.slice(separatorIndex + 1);
+    const profileScanResult = scanPresetDirectives({
+        argv: beforeSeparator,
+        commandPath,
+        presetFileFlag,
+        presetProfileFlag,
+        assertPresetProfileSelectorValue,
+    });
+    const cleanArgv = separatorIndex === -1
+        ? profileScanResult.cleanArgv
+        : [...profileScanResult.cleanArgv, '--', ...afterSeparator];
+    const resolvedCommandPresetConfig = resolvePresetConfigFromChain({
+        chain,
+        getPresetConfig,
+    });
+    const commandPresetFile = resolvedCommandPresetConfig.presetFile;
+    const effectivePresetFile = profileScanResult.presetFile ?? commandPresetFile;
+    const commandPresetProfile = resolvedCommandPresetConfig.presetProfile;
+    const useCommandPresetProfile = profileScanResult.presetProfile === undefined && commandPresetProfile !== undefined;
+    if (useCommandPresetProfile) {
+        assertPresetProfileSelectorValue(commandPresetProfile, 'command.preset.profile', commandPath);
+    }
+    const effectivePresetProfile = profileScanResult.presetProfile ?? commandPresetProfile;
+    const effectivePresetProfileSourceName = profileScanResult.presetProfile !== undefined
+        ? presetProfileFlag
+        : commandPresetProfile !== undefined
+            ? 'command.preset.profile'
+            : undefined;
+    if (effectivePresetFile === undefined && useCommandPresetProfile) {
+        throw new CommanderError('ConfigurationError', 'cannot use "command.preset.profile" without "command.preset.file" or "--preset-file"', commandPath);
+    }
+    const resolvedProfile = await resolvePresetProfile({
+        presetFile: effectivePresetFile,
+        presetProfile: effectivePresetProfile,
+        presetProfileSourceName: effectivePresetProfileSourceName,
+        commandPath,
+    });
+    return { cleanArgv, resolvedProfile };
+}
+async function runPresetStage(params) {
+    const { controlTailArgv, chain, commandPath, presetFileFlag, presetProfileFlag, runtime, userCmds, userEnvs, getPresetConfig, assertPresetProfileSelectorValue, resolvePresetProfile, validatePresetOptionTokens, } = params;
+    const { cleanArgv, resolvedProfile } = await resolvePresetStage({
+        controlTailArgv,
+        chain,
+        commandPath,
+        presetFileFlag,
+        presetProfileFlag,
+        getPresetConfig,
+        assertPresetProfileSelectorValue,
+        resolvePresetProfile,
+    });
+    const { presetArgv, presetEnvs } = await buildPresetProfileInputs({
+        runtime,
+        commandPath,
+        resolvedProfile,
+        validatePresetOptionTokens,
+    });
+    const { tailArgv, envs, segments, sources } = buildPresetSources({
+        userCmds,
+        userArgv: cleanArgv,
+        userEnvs,
+        presetArgv,
+        presetEnvs,
+        presetMeta: resolvedProfile?.issueMeta,
+        presetResolvedEnvFile: resolvePresetEnvFilePath(resolvedProfile),
+    });
+    return { tailArgv, envs, segments, sources };
+}
+function resolvePresetEnvFilePath(resolvedProfile) {
+    if (!resolvedProfile) {
         return undefined;
     }
-    #hasUserOption(long) {
-        return this.#options.some(option => option.long === long);
+    return (resolvedProfile.variantEnvFileSource?.absolutePath ??
+        resolvedProfile.profileEnvFileSource?.absolutePath);
+}
+
+function findSubcommandEntry(entries, token) {
+    return entries.find(entry => entry.name === token || entry.aliases.includes(token));
+}
+function routeCommandChain(params) {
+    const { root, argv, getSubcommandEntries } = params;
+    const chain = [root];
+    const cmds = [];
+    let current = root;
+    let index = 0;
+    while (index < argv.length) {
+        const token = argv[index];
+        if (token.startsWith('-')) {
+            break;
+        }
+        const entry = findSubcommandEntry(getSubcommandEntries(current), token);
+        if (entry === undefined) {
+            break;
+        }
+        current = entry.command;
+        cmds.push(token);
+        chain.push(current);
+        index += 1;
     }
-    #supportsBuiltinVersion() {
-        return this.#version !== undefined && this.#builtin.option.version;
+    return {
+        chain,
+        cmds,
+        remaining: argv.slice(index),
+    };
+}
+function resolveHelpCommand(params) {
+    const { leafCommand, helpTarget, getSubcommandEntries } = params;
+    if (helpTarget === undefined) {
+        return leafCommand;
     }
-    #resolveOptionPolicy() {
-        const optionMap = new Map();
-        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 (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 {
-            mergedOptions: Array.from(optionMap.values()),
-        };
+    const entry = findSubcommandEntry(getSubcommandEntries(leafCommand), helpTarget);
+    if (entry === undefined) {
+        return leafCommand;
     }
-    #buildOptionPolicyMap(chain) {
-        const optionPolicyMap = new Map();
-        for (const cmd of chain) {
-            optionPolicyMap.set(cmd, cmd.#resolveOptionPolicy());
+    return entry.command;
+}
+function findCommandByPath(params) {
+    const { root, commandPath, getCommandName, getSubcommandEntries } = params;
+    if (!commandPath) {
+        return root;
+    }
+    const segments = commandPath.split(' ').filter(Boolean);
+    if (segments.length === 0) {
+        return root;
+    }
+    let startIndex = 0;
+    const rootName = getCommandName(root);
+    if (rootName !== undefined && segments[0] === rootName) {
+        startIndex = 1;
+    }
+    let current = root;
+    for (const segment of segments.slice(startIndex)) {
+        if (current === undefined) {
+            return undefined;
         }
-        return optionPolicyMap;
+        const entry = findSubcommandEntry(getSubcommandEntries(current), segment);
+        current = entry?.command;
     }
-    #mustGetOptionPolicy(optionPolicyMap, cmd) {
-        const policy = optionPolicyMap.get(cmd) ?? cmd.#resolveOptionPolicy();
-        optionPolicyMap.set(cmd, policy);
-        return policy;
+    return current;
+}
+
+async function runStage(params) {
+    const { leafCommand, actionParams, tailArgv, envs, hasAction, runAction, hasSubcommands, renderHelpForDisplay, print, getCommandPath, } = params;
+    if (hasAction(leafCommand)) {
+        await runAction(leafCommand, actionParams);
+        return;
+    }
+    if (hasSubcommands(leafCommand)) {
+        print(renderHelpForDisplay(leafCommand, {
+            tailArgv,
+            envs,
+        }));
+        return;
     }
-    #validateMergedShortOptions(chain, optionPolicyMap) {
-        const mergedByLong = new Map();
-        for (const cmd of chain) {
-            const policy = this.#mustGetOptionPolicy(optionPolicyMap, cmd);
-            for (const opt of policy.mergedOptions) {
-                mergedByLong.set(opt.long, opt);
-            }
-        }
-        const shortMap = new Map();
-        for (const opt of mergedByLong.values()) {
-            if (!opt.short)
-                continue;
-            const existingLong = shortMap.get(opt.short);
-            if (existingLong && existingLong !== opt.long) {
-                throw new CommanderError('OptionConflict', `short option "-${opt.short}" conflicts with "--${existingLong}"`, this.#getCommandPath());
-            }
-            shortMap.set(opt.short, opt.long);
-        }
+    throw new CommanderError('ConfigurationError', `no action defined for command "${getCommandPath(leafCommand)}"`, getCommandPath(leafCommand));
+}
+
+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]+)*$/;
+function kebabToCamelCase(str) {
+    return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function tokenizeLongOption(segment, commandPath) {
+    const arg = segment.value;
+    const eqIdx = arg.indexOf('=');
+    const namePart = eqIdx !== -1 ? arg.slice(0, eqIdx) : arg;
+    const valuePart = eqIdx !== -1 ? arg.slice(eqIdx) : '';
+    if (namePart.includes('_')) {
+        throw new CommanderError('InvalidOptionFormat', `invalid option "${arg}": use '-' instead of '_'`, commandPath);
     }
-    #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());
-        }
-        if ((opt.type === 'string' || opt.type === 'number') && opt.args === 'none') {
-            throw new CommanderError('ConfigurationError', `${opt.type} option "--${opt.long}" must have args: 'required', 'optional', or 'variadic'`, this.#getCommandPath());
-        }
-        if (opt.type === 'number' && opt.args === 'optional') {
-            throw new CommanderError('ConfigurationError', `number option "--${opt.long}" does not support args: 'optional'`, this.#getCommandPath());
-        }
-        if (opt.long.startsWith('no')) {
-            throw new CommanderError('ConfigurationError', `option long name cannot start with "no": "${opt.long}"`, this.#getCommandPath());
-        }
-        if (!/^[a-z][a-zA-Z0-9]*$/.test(opt.long)) {
-            throw new CommanderError('ConfigurationError', `option long name must be camelCase: "${opt.long}"`, this.#getCommandPath());
-        }
-        if (opt.short !== undefined && opt.short.length !== 1) {
-            throw new CommanderError('ConfigurationError', `option short name must be a single character: "${opt.short}"`, this.#getCommandPath());
-        }
-        if (opt.required && opt.default !== undefined) {
-            throw new CommanderError('ConfigurationError', `option "--${opt.long}" cannot be both required and have a default value`, this.#getCommandPath());
-        }
-        if (opt.type === 'boolean' && opt.required) {
-            throw new CommanderError('ConfigurationError', `boolean option "--${opt.long}" cannot be required`, this.#getCommandPath());
-        }
-        if (opt.required && opt.args !== 'required') {
-            throw new CommanderError('ConfigurationError', `required option "--${opt.long}" must use args: 'required'`, this.#getCommandPath());
-        }
+    const lowerName = namePart.toLowerCase();
+    if (lowerName === '--no' || lowerName === '--no-') {
+        throw new CommanderError('InvalidNegativeOption', `invalid negative option syntax "${arg}"`, commandPath);
     }
-    #checkOptionUniqueness(opt) {
-        if (this.#options.some(o => o.long === opt.long)) {
-            throw new CommanderError('OptionConflict', `option "--${opt.long}" is already defined`, this.#getCommandPath());
+    if (lowerName.startsWith('--no-')) {
+        if (valuePart !== '') {
+            throw new CommanderError('NegativeOptionWithValue', `"${namePart}" does not accept a value`, commandPath);
         }
-        if (opt.short && this.#options.some(o => o.short === opt.short)) {
-            throw new CommanderError('OptionConflict', `short option "-${opt.short}" is already defined`, this.#getCommandPath());
+        if (!NEGATIVE_OPTION_REGEX.test(lowerName)) {
+            throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
         }
+        const camelName = kebabToCamelCase(lowerName.slice(5));
+        return {
+            original: arg,
+            resolved: `--${camelName}=false`,
+            name: camelName,
+            type: 'long',
+            source: segment.source,
+            preset: segment.preset,
+        };
     }
-    #validateArgumentConfig(arg) {
-        if (arg.kind !== 'required' &&
-            arg.kind !== 'optional' &&
-            arg.kind !== 'variadic' &&
-            arg.kind !== 'some') {
-            throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid kind`, this.#getCommandPath());
+    if (!LONG_OPTION_REGEX.test(lowerName)) {
+        throw new CommanderError('InvalidOptionFormat', `invalid option format "${arg}"`, commandPath);
+    }
+    const camelName = kebabToCamelCase(lowerName.slice(2));
+    return {
+        original: arg,
+        resolved: `--${camelName}${valuePart}`,
+        name: camelName,
+        type: 'long',
+        source: segment.source,
+        preset: segment.preset,
+    };
+}
+function tokenizeShortOptions(segment, commandPath) {
+    const arg = segment.value;
+    if (arg.includes('=')) {
+        throw new CommanderError('UnsupportedShortSyntax', `"${arg}" is not supported. Use "-${arg[1]} ${arg.slice(3)}" instead`, commandPath);
+    }
+    return arg
+        .slice(1)
+        .split('')
+        .map(flag => ({
+        original: `-${flag}`,
+        resolved: `-${flag}`,
+        name: flag,
+        type: 'short',
+        source: segment.source,
+        preset: segment.preset,
+    }));
+}
+function tokenizeArgv(segments, commandPath) {
+    const optionTokens = [];
+    const restArgs = [];
+    let passThrough = false;
+    for (const segment of segments) {
+        const arg = segment.value;
+        if (arg === '--') {
+            passThrough = true;
+            continue;
         }
-        if (arg.type !== 'string' && arg.type !== 'choice') {
-            throw new CommanderError('ConfigurationError', `argument "${arg.name}" must specify a valid type`, this.#getCommandPath());
+        if (passThrough) {
+            restArgs.push(segment.value);
+            continue;
         }
-        if (arg.default !== undefined && arg.kind !== 'optional') {
-            throw new CommanderError('ConfigurationError', `only optional argument "${arg.name}" can have a default value`, this.#getCommandPath());
+        if (arg.startsWith('--')) {
+            optionTokens.push(tokenizeLongOption(segment, commandPath));
+            continue;
         }
-        if (arg.type === 'string' && arg.choices !== undefined) {
-            throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "string" cannot declare choices`, this.#getCommandPath());
+        if (arg.startsWith('-') && arg.length > 1) {
+            optionTokens.push(...tokenizeShortOptions(segment, commandPath));
+            continue;
         }
-        if (arg.type === 'choice') {
-            if (!Array.isArray(arg.choices) || arg.choices.length === 0) {
-                throw new CommanderError('ConfigurationError', `argument "${arg.name}" of type "choice" must declare a non-empty choices array`, this.#getCommandPath());
-            }
-            if (arg.choices.some(choice => typeof choice !== 'string')) {
-                throw new CommanderError('ConfigurationError', `argument "${arg.name}" choices must be string[]`, this.#getCommandPath());
-            }
+        optionTokens.push({
+            original: arg,
+            resolved: arg,
+            name: '',
+            type: 'none',
+            source: segment.source,
+            preset: segment.preset,
+        });
+    }
+    return { optionTokens, restArgs };
+}
+
+class Command {
+    #name;
+    #desc;
+    #version;
+    #builtinConfig;
+    #builtin;
+    #presetConfig;
+    #reporter;
+    #runtime;
+    #contextAdapter = new CommandContextAdapter();
+    #diagnostics = new CommandDiagnosticsEngine();
+    #helpRenderer = new CommandHelpRenderer();
+    #optionParser = new CommandOptionParser();
+    #presetProfileParser;
+    #kernel;
+    #parent;
+    #options = [];
+    #arguments = [];
+    #examples = [];
+    #subcommandsList = [];
+    #subcommandsMap = new Map();
+    #action = undefined;
+    constructor(config) {
+        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;
+        this.#runtime = config.runtime ?? getDefaultCommandRuntime();
+        this.#presetProfileParser = new CommandPresetProfileParser({
+            resolvePresetFileAbsolutePath: (filepath, baseDirectory) => resolvePresetFileAbsolutePath({
+                runtime: this.#runtime,
+                filepath,
+                baseDirectory,
+            }),
+            resolvePath: (...paths) => this.#runtime.resolve(...paths),
+            readPresetFile: async (file, commandPath) => readPresetFile({ runtime: this.#runtime, file, commandPath }),
+        });
+        this.#kernel = new CommandKernel({
+            port: {
+                route: argv => this.#route(argv),
+                createContext: params => this.#createContext(params),
+                controlScan: (tailArgv, leafCommand) => this.#controlScan(tailArgv, leafCommand),
+                controlRun: (leafCommand, controlScanResult) => this.#controlRun(leafCommand, controlScanResult),
+                preset: async (tailArgv, ctx) => this.#preset(tailArgv, ctx),
+                tokenize: (segments, commandPath) => tokenizeArgv(segments, commandPath),
+                getCommandPath: command => command.#getCommandPath(),
+                buildOptionPolicyMap: chain => this.#buildOptionPolicyMap(chain),
+                resolve: (chain, optionTokens, optionPolicyMap) => this.#resolve(chain, optionTokens, optionPolicyMap),
+                parse: (chain, resolveResult, optionPolicyMap, ctx, restArgs) => this.#parse(chain, resolveResult, optionPolicyMap, ctx, restArgs),
+                run: async ({ leafCommand, parseResult, presetResult, ctx }) => runStage({
+                    leafCommand,
+                    actionParams: this.#contextAdapter.toActionParams(parseResult),
+                    tailArgv: presetResult.tailArgv,
+                    envs: ctx.envs,
+                    hasAction: command => command.#action !== undefined,
+                    runAction: async (command, actionParams) => runCommandAction({
+                        action: command.#action,
+                        actionParams,
+                        commandPath: command.#getCommandPath(),
+                    }),
+                    hasSubcommands: command => command.#subcommandsList.length > 0,
+                    renderHelpForDisplay: (command, options) => {
+                        const helpColor = command.#resolveHelpColorFromTailArgv(options.tailArgv, options.envs);
+                        return command.#formatHelpForDisplay({ color: helpColor });
+                    },
+                    print: content => {
+                        console.log(content);
+                    },
+                    getCommandPath: command => command.#getCommandPath(),
+                }),
+                issueScopeFromErrorKind: kind => errorKindToIssueScope(kind),
+            },
+            diagnostics: this.#diagnostics,
+            contextAdapter: this.#contextAdapter,
+        });
+    }
+    get name() {
+        return this.#name || undefined;
+    }
+    get description() {
+        return this.#desc;
+    }
+    get version() {
+        return this.#version;
+    }
+    get builtin() {
+        return this.#builtinConfig;
+    }
+    get preset() {
+        return this.#presetConfig === undefined ? undefined : { ...this.#presetConfig };
+    }
+    get parent() {
+        return this.#parent;
+    }
+    get options() {
+        return [...this.#options];
+    }
+    get arguments() {
+        return [...this.#arguments];
+    }
+    get examples() {
+        return this.#examples.map(example => ({ ...example }));
+    }
+    get subcommands() {
+        return new Map(this.#subcommandsMap);
+    }
+    option(opt) {
+        const commandPath = this.#getCommandPath();
+        validateOptionConfig({ opt, commandPath });
+        checkOptionUniqueness({ opt, options: this.#options, commandPath });
+        this.#options.push(opt);
+        return this;
+    }
+    argument(arg) {
+        validateArgumentConfig({
+            arg: arg,
+            arguments_: this.#arguments,
+            commandPath: this.#getCommandPath(),
+        });
+        this.#arguments.push(arg);
+        return this;
+    }
+    action(fn) {
+        this.#action = fn;
+        return this;
+    }
+    example(title, usage, desc) {
+        this.#examples.push(normalizeExample({
+            example: { title, usage, desc },
+            commandPath: this.#getCommandPath(),
+        }));
+        return this;
+    }
+    subcommand(name, cmd) {
+        if (name === 'help') {
+            throw new CommanderError('ConfigurationError', '"help" is a reserved subcommand name', this.#getCommandPath());
         }
-        if (arg.default !== undefined) {
-            this.#validateArgumentDefaultValue(arg);
+        if (cmd.#parent && cmd.#parent !== this) {
+            throw new CommanderError('ConfigurationError', `command "${cmd.#name}" already has a parent`, this.#getCommandPath());
         }
-        if (arg.kind === 'variadic' || arg.kind === 'some') {
-            if (this.#arguments.some(a => a.kind === 'variadic' || a.kind === 'some')) {
-                throw new CommanderError('ConfigurationError', 'only one variadic/some argument is allowed', this.#getCommandPath());
-            }
+        const occupied = this.#subcommandsMap.get(name);
+        if (occupied && occupied !== cmd) {
+            throw new CommanderError('ConfigurationError', `subcommand name/alias "${name}" conflicts with an existing command`, this.#getCommandPath());
         }
-        if (this.#arguments.length > 0) {
-            const last = this.#arguments[this.#arguments.length - 1];
-            if (last.kind === 'variadic' || last.kind === 'some') {
-                throw new CommanderError('ConfigurationError', 'variadic/some argument must be the last argument', this.#getCommandPath());
+        const existing = this.#subcommandsList.find(e => e.command === cmd);
+        if (existing) {
+            if (existing.name === name || existing.aliases.includes(name)) {
+                return this;
             }
+            existing.aliases.push(name);
+            this.#subcommandsMap.set(name, cmd);
         }
-        if (arg.kind === 'required') {
-            const hasOptional = this.#arguments.some(a => a.kind === 'optional' || a.kind === 'variadic' || a.kind === 'some');
-            if (hasOptional) {
-                throw new CommanderError('ConfigurationError', `required argument "${arg.name}" cannot come after optional/variadic/some arguments`, this.#getCommandPath());
-            }
+        else {
+            cmd.#name = name;
+            cmd.#parent = this;
+            this.#subcommandsList.push({ name, aliases: [], command: cmd });
+            this.#subcommandsMap.set(name, cmd);
         }
+        return this;
     }
-    #validateArgumentDefaultValue(arg) {
-        if (typeof arg.default !== 'string') {
-            throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must match type "${arg.type}"`, this.#getCommandPath());
-        }
-        if (arg.type === 'choice') {
-            const choices = arg.choices ?? [];
-            if (!choices.includes(arg.default)) {
-                throw new CommanderError('ConfigurationError', `default value for argument "${arg.name}" must be one of declared choices`, this.#getCommandPath());
-            }
-        }
+    async run(params) {
+        const outcome = await this.#execute(params, 'run');
+        handleRunOutcome({
+            outcome,
+            argv: params.argv,
+            envs: params.envs,
+            route: argv => this.#route(argv),
+            controlScan: (tailArgv, leafCommand) => this.#controlScan(tailArgv, leafCommand),
+            findCommandByPath: commandPath => this.#findCommandByPath(commandPath),
+            resolveHelpCommand: (leafCommand, helpTarget) => this.#resolveHelpCommand(leafCommand, helpTarget),
+            resolveHelpColor: (command, tailArgv, envs) => command.#resolveHelpColorFromTailArgv(tailArgv, envs),
+            formatHelpForDisplay: (command, color) => command.#formatHelpForDisplay({ color }),
+            print: content => {
+                console.log(content);
+            },
+            printError: content => {
+                console.error(content);
+            },
+            exit: code => this.#exit(code),
+            normalizeControlRunError: error => {
+                const enrichedError = this.#diagnostics.withErrorIssue(error, {
+                    stage: 'control-run',
+                    scope: 'control',
+                });
+                return this.#diagnostics.normalizeCommanderError(enrichedError, {
+                    fallbackStage: 'control-run',
+                    fallbackScope: 'control',
+                });
+            },
+        });
     }
-    #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 };
+    #exit(code) {
+        process.exit(code);
     }
-    async #runAction(params) {
-        if (!this.#action)
-            return;
-        try {
-            await this.#action(params);
-        }
-        catch (err) {
-            if (err instanceof Error) {
-                console.error(`Error: ${err.message}`);
-            }
-            else {
-                console.error('Error: action failed');
-            }
-            process.exit(1);
-        }
+    async parse(params) {
+        const outcome = await this.#execute(params, 'parse');
+        return unwrapParseOutcome({
+            outcome,
+            commandPath: this.#getCommandPath(),
+        });
     }
-    #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.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 color;
+    async #execute(params, mode) {
+        return this.#kernel.execute(params, mode);
     }
-    #freezeInputSources(sources) {
-        return Object.freeze({
-            preset: Object.freeze({
-                argv: Object.freeze([...sources.preset.argv]),
-                envs: Object.freeze({ ...sources.preset.envs }),
+    #controlRun(leafCommand, controlScanResult) {
+        return runControl({
+            leafCommand,
+            controlScanResult,
+            resolveHelpCommand: (leaf, helpTarget) => this.#resolveHelpCommand(leaf, helpTarget),
+            getCommandPath: command => command.#getCommandPath(),
+            getCommandVersion: command => command.#version,
+        });
+    }
+    #findCommandByPath(commandPath) {
+        return findCommandByPath({
+            root: this,
+            commandPath,
+            getCommandName: command => command.#name || undefined,
+            getSubcommandEntries: command => command.#subcommandsList,
+        });
+    }
+    formatHelp() {
+        return this.#helpRenderer.formatHelp(this.#buildHelpData());
+    }
+    #formatHelpForDisplay(params = {}) {
+        const { color = true } = params;
+        return this.#helpRenderer.formatHelpForDisplay(this.#buildHelpData(), color);
+    }
+    #buildHelpData() {
+        const subcommands = buildHelpSubcommands({
+            entries: this.#subcommandsList,
+            getDescription: command => command.#desc,
+        });
+        return this.#helpRenderer.buildHelpData({
+            desc: this.#desc,
+            commandPath: this.#getCommandPath(),
+            arguments: this.#arguments,
+            options: this.#resolveOptionPolicy().mergedOptions,
+            supportsBuiltinVersion: this.#supportsBuiltinVersion(),
+            subcommands,
+            examples: this.#examples,
+            builtinHelpOption: BUILTIN_HELP_OPTION,
+            builtinVersionOption: BUILTIN_VERSION_OPTION,
+        });
+    }
+    getCompletionMeta() {
+        return buildCompletionMeta({
+            name: this.#name,
+            desc: this.#desc,
+            mergedOptions: this.#resolveOptionPolicy().mergedOptions,
+            arguments_: this.#arguments,
+            supportsBuiltinVersion: this.#supportsBuiltinVersion(),
+            builtinHelpOption: BUILTIN_HELP_OPTION,
+            builtinVersionOption: BUILTIN_VERSION_OPTION,
+            subcommands: this.#subcommandsList,
+            resolveSubcommandMeta: command => command.getCompletionMeta(),
+        });
+    }
+    #route(argv) {
+        return routeCommandChain({
+            root: this,
+            argv,
+            getSubcommandEntries: command => command.#subcommandsList,
+        });
+    }
+    #controlScan(tailArgv, leafCommand) {
+        return scanControl({
+            tailArgv,
+            supportsBuiltinVersion: leafCommand.#supportsBuiltinVersion(),
+        });
+    }
+    #createContext(params) {
+        const { chain, cmds, envs, reporter } = params;
+        const leafCommand = chain[chain.length - 1];
+        return createCommandContext({
+            leafCommand,
+            chain,
+            cmds,
+            envs,
+            reporter: reporter ?? this.#reporter ?? new Reporter(),
+        });
+    }
+    #resolveHelpCommand(leafCommand, helpTarget) {
+        return resolveHelpCommand({
+            leafCommand,
+            helpTarget,
+            getSubcommandEntries: command => command.#subcommandsList,
+        });
+    }
+    async #preset(controlTailArgv, ctx) {
+        const commandPath = ctx.chain[ctx.chain.length - 1].#getCommandPath();
+        return runPresetStage({
+            controlTailArgv,
+            chain: ctx.chain,
+            commandPath,
+            presetFileFlag: PRESET_FILE_FLAG,
+            presetProfileFlag: PRESET_PROFILE_FLAG,
+            runtime: this.#runtime,
+            userCmds: ctx.sources.user.cmds,
+            userEnvs: ctx.sources.user.envs,
+            getPresetConfig: command => command.#presetConfig,
+            assertPresetProfileSelectorValue: (value, sourceName, path) => this.#presetProfileParser.assertPresetProfileSelectorValue(value, sourceName, path),
+            resolvePresetProfile: params => this.#presetProfileParser.resolvePresetProfile(params),
+            validatePresetOptionTokens: (tokens, filepath, path) => this.#presetProfileParser.validatePresetOptionTokens(tokens, filepath, path),
+        });
+    }
+    #resolve(chain, tokens, optionPolicyMap) {
+        return resolveStage({
+            chain,
+            tokens,
+            optionPolicyMap,
+            mustGetOptionPolicy: (map, command) => this.#mustGetOptionPolicy(map, command),
+            getLocalOptions: command => command.#options,
+            getCommandPath: command => command.#getCommandPath(),
+            withUnknownOptionIssue: (error, token) => this.#diagnostics.withErrorIssue(error, {
+                stage: 'resolve',
+                scope: 'option',
+                token,
             }),
-            user: Object.freeze({
-                cmds: Object.freeze([...sources.user.cmds]),
-                argv: Object.freeze([...sources.user.argv]),
-                envs: Object.freeze({ ...sources.user.envs }),
+        });
+    }
+    #parse(chain, resolveResult, optionPolicyMap, ctx, restArgs) {
+        return parseStage({
+            chain,
+            resolveResult,
+            optionPolicyMap,
+            ctx,
+            restArgs,
+            rootCommandPath: this.#getCommandPath(),
+            mustGetOptionPolicy: (map, command) => this.#mustGetOptionPolicy(map, command),
+            parseOptions: ({ command, tokens, allOptions, envs, commandPath }) => command.#optionParser.parseOptions({
+                tokens,
+                allOptions,
+                envs,
+                commandPath,
             }),
+            applyBuiltinDevmodeLogLevel: ({ command, opts, explicitOptionLongs }) => {
+                command.#optionParser.applyBuiltinDevmodeLogLevel({
+                    opts,
+                    explicitOptionLongs,
+                    builtinOption: command.#builtin.option,
+                    hasUserOption: long => command.#hasUserOption(long),
+                });
+            },
+            resolveBuiltinParsedOptions: ({ command, opts }) => command.#optionParser.resolveBuiltinParsedOptions({
+                opts,
+                builtinOption: command.#builtin.option,
+                hasUserOption: long => command.#hasUserOption(long),
+            }),
+            applyOptionCallbacks: ({ opts, allOptions, ctx }) => {
+                for (const option of allOptions) {
+                    if (option.apply && opts[option.long] !== undefined) {
+                        option.apply(opts[option.long], ctx);
+                    }
+                }
+            },
+            getLocalOptions: command => command.#options,
+            getSubcommands: command => command.#subcommandsList,
+            getArguments: command => command.#arguments,
+            getCommandPath: command => command.#getCommandPath(),
+            withUnknownSubcommandIssue: error => this.#diagnostics.withErrorIssue(error, {
+                stage: 'parse',
+                scope: 'command',
+                source: { primary: 'user' },
+            }),
+            freezeInputSources: sources => this.#freezeInputSources(sources),
+        });
+    }
+    #hasUserOption(long) {
+        return this.#options.some(option => option.long === long);
+    }
+    #supportsBuiltinVersion() {
+        return this.#version !== undefined && this.#builtin.option.version;
+    }
+    #resolveOptionPolicy() {
+        return resolveOptionPolicy({
+            builtinOption: this.#builtin.option,
+            localOptions: this.#options,
+        });
+    }
+    #buildOptionPolicyMap(chain) {
+        return buildOptionPolicyMap({
+            chain,
+            resolveOptionPolicy: command => command.#resolveOptionPolicy(),
         });
     }
+    #mustGetOptionPolicy(optionPolicyMap, cmd) {
+        return mustGetOptionPolicy({
+            optionPolicyMap,
+            command: cmd,
+            resolveOptionPolicy: command => command.#resolveOptionPolicy(),
+        });
+    }
+    #resolveHelpColorFromTailArgv(tailArgv, envs, policy = this.#resolveOptionPolicy()) {
+        return this.#helpRenderer.resolveHelpColorFromTailArgv({
+            tailArgv,
+            envs,
+            options: policy.mergedOptions,
+            commandPath: this.#getCommandPath(),
+        });
+    }
+    #freezeInputSources(sources) {
+        return freezeInputSources(sources);
+    }
     #getCommandPath() {
         const parts = [];
         let current = this;
@@ -2391,4 +3715,4 @@ class Coerce {
 
 setDefaultCommandRuntime(createBrowserCommandRuntime());
 
-export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, logLevelOption, setDefaultCommandRuntime, silentOption };
+export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };