@guanghechen/commander 4.7.4 → 4.7.6

package/lib/esm/browser.mjs

@@ -171,11 +171,9 @@ class CommanderError extends Error {
 
 const LONG_OPTION_REGEX = /^--[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const NEGATIVE_OPTION_REGEX = /^--no-[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
-const PRESET_OPTS_FLAG = '--preset-opts';
-const PRESET_ENVS_FLAG = '--preset-envs';
-const PRESET_ROOT_FLAG = '--preset-root';
-const DEFAULT_PRESET_OPTS_FILENAME = '.opt.local';
-const DEFAULT_PRESET_ENVS_FILENAME = '.env.local';
+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());
 }
@@ -189,6 +187,8 @@ 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, '');
 }
@@ -713,8 +713,28 @@ class Command {
             const desc = metadata.length > 0 ? `${arg.desc} ${metadata.join(' ')}` : arg.desc;
             argumentsLines.push({ sig, desc });
         }
+        const sortedOptions = [...allOptions].sort((a, b) => {
+            const optionRank = (option) => {
+                if (option.long === 'help') {
+                    return 0;
+                }
+                if (option.long === 'version') {
+                    return 1;
+                }
+                if (option.required === true) {
+                    return 2;
+                }
+                return 3;
+            };
+            const rankA = optionRank(a);
+            const rankB = optionRank(b);
+            if (rankA !== rankB) {
+                return rankA - rankB;
+            }
+            return camelToKebabCase(a.long).localeCompare(camelToKebabCase(b.long));
+        });
         const options = [];
-        for (const opt of allOptions) {
+        for (const opt of sortedOptions) {
             const kebabLong = camelToKebabCase(opt.long);
             let sig = opt.short ? `-${opt.short}, ` : '    ';
             sig += `--${kebabLong}`;
@@ -732,21 +752,13 @@ class Command {
                 desc += ` [choices: ${opt.choices.map(choice => JSON.stringify(choice)).join(', ')}]`;
             }
             options.push({ sig, desc });
-            if (opt.type === 'boolean' &&
-                opt.args === 'none' &&
-                opt.long !== 'help' &&
-                opt.long !== 'version') {
-                options.push({
-                    sig: `    --no-${kebabLong}`,
-                    desc: `Negate --${kebabLong}`,
-                });
-            }
         }
         const commands = [];
         if (this.#subcommandsList.length > 0) {
             commands.push({ name: 'help', desc: 'Show help for a command' });
         }
-        for (const entry of this.#subcommandsList) {
+        const sortedSubcommands = [...this.#subcommandsList].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(', ')}`;
@@ -1005,24 +1017,32 @@ class Command {
         const separatorIndex = controlTailArgv.indexOf('--');
         const beforeSeparator = separatorIndex === -1 ? controlTailArgv : controlTailArgv.slice(0, separatorIndex);
         const afterSeparator = separatorIndex === -1 ? [] : controlTailArgv.slice(separatorIndex + 1);
-        const rootScanResult = this.#scanPresetRootDirectives(beforeSeparator, commandPath);
-        const commandPreset = this.#resolveCommandPresetFromChain(ctx.chain);
-        const presetRoot = await this.#resolveEffectivePresetRoot(rootScanResult.cliPresetRoots, commandPreset, commandPath);
-        const fileScanResult = this.#scanPresetFileDirectives(rootScanResult.cleanArgv, commandPath);
+        const profileScanResult = this.#scanPresetProfileDirectives(beforeSeparator, commandPath);
         const cleanArgv = separatorIndex === -1
-            ? fileScanResult.cleanArgv
-            : [...fileScanResult.cleanArgv, '--', ...afterSeparator];
-        const presetOptsFiles = this.#resolvePresetFileSources({
-            cliFiles: fileScanResult.cliPresetOptsFiles,
-            commandPresetFile: this.#normalizeCommandPresetFile(commandPreset?.opt),
-            presetRoot,
-            defaultFilename: DEFAULT_PRESET_OPTS_FILENAME,
-        });
-        const presetEnvsFiles = this.#resolvePresetFileSources({
-            cliFiles: fileScanResult.cliPresetEnvsFiles,
-            commandPresetFile: this.#normalizeCommandPresetFile(commandPreset?.env),
-            presetRoot,
-            defaultFilename: DEFAULT_PRESET_ENVS_FILENAME,
+            ? 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],
@@ -1030,30 +1050,29 @@ class Command {
             envs: { ...ctx.sources.user.envs },
         };
         const presetArgv = [];
-        for (const file of presetOptsFiles) {
-            const content = await this.#readPresetFile(file, commandPath);
-            if (content === undefined) {
-                continue;
-            }
-            const tokens = this.#tokenizePresetOptions(content);
-            this.#validatePresetOptionTokens(tokens, file.displayPath, commandPath);
-            this.#assertPresetOptionFragments(tokens, file.displayPath, ctx.chain, optionPolicyMap);
-            presetArgv.push(...tokens);
+        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 = {};
-        for (const file of presetEnvsFiles) {
-            const content = await this.#readPresetFile(file, commandPath);
-            if (content === undefined) {
-                continue;
-            }
-            let parsed;
-            try {
-                parsed = parse(content);
+        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);
+                }
             }
-            catch (error) {
-                throw new CommanderError('ConfigurationError', `failed to parse preset envs file "${file.displayPath}": ${error.message}`, commandPath);
+            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, parsed);
+            Object.assign(presetEnvs, resolvedProfile.variantInlineEnvs);
         }
         const sources = {
             user: userSources,
@@ -1066,200 +1085,446 @@ class Command {
         const tailArgv = [...sources.preset.argv, ...sources.user.argv];
         return { tailArgv, envs, sources };
     }
-    #resolveCommandPresetFromChain(chain) {
+    #resolveCommandPresetFileFromChain(chain) {
         for (let index = chain.length - 1; index >= 0; index -= 1) {
             const preset = chain[index].#presetConfig;
-            if (preset?.root !== undefined) {
-                return preset;
+            if (preset?.file !== undefined) {
+                return preset.file;
             }
         }
         return undefined;
     }
-    async #resolveEffectivePresetRoot(cliPresetRoots, commandPreset, commandPath) {
-        if (cliPresetRoots.length > 0) {
-            const root = cliPresetRoots[cliPresetRoots.length - 1];
-            return await this.#assertPresetRoot(root, PRESET_ROOT_FLAG, commandPath);
+    #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 (commandPreset?.root === undefined) {
-            return undefined;
+        return undefined;
+    }
+    #resolvePresetFileAbsolutePath(filepath, baseDirectory) {
+        if (this.#runtime.isAbsolute(filepath)) {
+            return filepath;
         }
-        return await this.#assertPresetRoot(commandPreset.root, 'command.preset.root', commandPath);
+        return this.#runtime.resolve(baseDirectory ?? this.#runtime.cwd(), filepath);
     }
-    async #assertPresetRoot(root, sourceName, commandPath) {
-        if (!this.#runtime.isAbsolute(root)) {
-            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" is not an absolute directory`, commandPath);
+    async #resolvePresetProfile(params) {
+        const { presetFile, presetProfile, presetProfileSourceName, commandPath } = params;
+        if (presetFile === undefined) {
+            if (presetProfile !== undefined) {
+                throw new CommanderError('ConfigurationError', `cannot use "${PRESET_PROFILE_FLAG}" without "${PRESET_FILE_FLAG}"`, commandPath);
+            }
+            return undefined;
+        }
+        const profileFile = {
+            displayPath: presetFile,
+            absolutePath: this.#resolvePresetFileAbsolutePath(presetFile),
+            explicit: true,
+        };
+        const content = await this.#readPresetFile(profileFile, commandPath);
+        if (content === undefined) {
+            return undefined;
         }
-        let stats;
+        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 profile = manifest.profiles[resolvedProfileName];
+        if (profile === undefined) {
+            throw new CommanderError('ConfigurationError', `unknown preset profile "${resolvedProfileName}" in "${profileFile.displayPath}"`, commandPath);
+        }
+        const selectedVariantName = explicitVariantName ?? profile.defaultVariant;
+        let selectedVariant;
+        if (selectedVariantName !== undefined) {
+            const variants = profile.variants ?? {};
+            selectedVariant = variants[selectedVariantName];
+            if (selectedVariant === undefined) {
+                const availableVariants = Object.keys(variants);
+                const availableText = availableVariants.length > 0 ? availableVariants.join(', ') : '<none>';
+                throw new CommanderError('ConfigurationError', `unknown preset variant "${selectedVariantName}" for profile "${resolvedProfileName}" in "${profileFile.displayPath}" (available: ${availableText})`, commandPath);
+            }
+        }
+        const profileSelectorLabel = selectedVariantName === undefined
+            ? resolvedProfileName
+            : `${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, '..');
+        let profileEnvFileSource;
+        if (profile.envFile !== undefined) {
+            profileEnvFileSource = {
+                displayPath: profile.envFile,
+                absolutePath: this.#resolvePresetFileAbsolutePath(profile.envFile, profileDir),
+                explicit: true,
+            };
+        }
+        let variantEnvFileSource;
+        if (selectedVariant?.envFile !== undefined) {
+            variantEnvFileSource = {
+                displayPath: selectedVariant.envFile,
+                absolutePath: this.#resolvePresetFileAbsolutePath(selectedVariant.envFile, profileDir),
+                explicit: true,
+            };
+        }
+        return {
+            profileName: resolvedProfileName,
+            variantName: selectedVariantName,
+            optsArgv,
+            optsSourceLabel: `${profileFile.displayPath}#${profileSelectorLabel}.opts`,
+            profileInlineEnvs,
+            variantInlineEnvs,
+            profileEnvFileSource,
+            variantEnvFileSource,
+        };
+    }
+    #parsePresetProfileManifest(content, filepath, commandPath) {
+        let parsed;
         try {
-            stats = await this.#runtime.stat(root);
+            parsed = JSON.parse(content);
         }
         catch (error) {
-            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" cannot be accessed (${error.message})`, commandPath);
+            throw new CommanderError('ConfigurationError', `failed to parse preset file "${filepath}": ${error.message}`, commandPath);
         }
-        if (!stats.isDirectory()) {
-            throw new CommanderError('ConfigurationError', `invalid preset root from "${sourceName}": "${root}" is not a directory`, commandPath);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": root must be an object`, commandPath);
         }
-        return root;
-    }
-    #normalizeCommandPresetFile(filepath) {
-        if (filepath === undefined) {
-            return undefined;
+        const root = parsed;
+        if (root.version !== 1) {
+            throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": "version" must be 1`, commandPath);
         }
-        if (!this.#isValidPresetFileValue(filepath)) {
-            return undefined;
+        let defaults;
+        const rawDefaults = root.defaults;
+        if (rawDefaults !== undefined) {
+            if (typeof rawDefaults !== 'object' || rawDefaults === null || Array.isArray(rawDefaults)) {
+                throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": "defaults" must be an object`, commandPath);
+            }
+            const defaultsRecord = rawDefaults;
+            if (defaultsRecord.profile !== undefined) {
+                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);
+            }
+            defaults = { profile: defaultsRecord.profile };
+        }
+        const rawProfiles = root.profiles;
+        if (typeof rawProfiles !== 'object' || rawProfiles === null || Array.isArray(rawProfiles)) {
+            throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": "profiles" must be an object`, commandPath);
         }
-        return filepath;
+        const profilesRecord = {};
+        for (const [profileName, profileValue] of Object.entries(rawProfiles)) {
+            this.#assertPresetProfileName(profileName, `profiles["${profileName}"]`, commandPath);
+            if (typeof profileValue !== 'object' ||
+                profileValue === null ||
+                Array.isArray(profileValue)) {
+                throw new CommanderError('ConfigurationError', `invalid preset file "${filepath}": profile "${profileName}" must be an object`, commandPath);
+            }
+            profilesRecord[profileName] = this.#parsePresetProfileItem(profileValue, profileName, filepath, commandPath);
+        }
+        return {
+            version: 1,
+            defaults,
+            profiles: profilesRecord,
+        };
     }
-    #resolvePresetFileSources(params) {
-        const { cliFiles, commandPresetFile, presetRoot, defaultFilename } = params;
-        if (cliFiles.length > 0) {
-            return cliFiles.map(filepath => ({
-                displayPath: filepath,
-                absolutePath: this.#resolvePresetFileAbsolutePath(filepath, presetRoot),
-                explicit: true,
-            }));
+    #parsePresetProfileItem(profileValue, profileName, filepath, commandPath) {
+        const labelPrefix = `invalid preset file "${filepath}": profile "${profileName}"`;
+        const envFile = profileValue.envFile;
+        if (envFile !== undefined) {
+            if (typeof envFile !== 'string') {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.envFile must be a string`, commandPath);
+            }
         }
-        if (presetRoot === undefined) {
-            return [];
+        const rawEnvs = profileValue.envs;
+        let envs;
+        if (rawEnvs !== undefined) {
+            if (typeof rawEnvs !== 'object' || rawEnvs === null || Array.isArray(rawEnvs)) {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.envs must be an object`, commandPath);
+            }
+            envs = {};
+            for (const [key, value] of Object.entries(rawEnvs)) {
+                if (typeof value !== 'string') {
+                    throw new CommanderError('ConfigurationError', `${labelPrefix}.envs["${key}"] must be a string`, commandPath);
+                }
+                envs[key] = value;
+            }
+        }
+        const rawOpts = profileValue.opts;
+        let opts;
+        if (rawOpts !== undefined) {
+            if (typeof rawOpts !== 'object' || rawOpts === null || Array.isArray(rawOpts)) {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.opts must be an object`, commandPath);
+            }
+            opts = {};
+            for (const [key, value] of Object.entries(rawOpts)) {
+                opts[key] = this.#parsePresetProfileOptionValue(value, `${labelPrefix}.opts["${key}"]`, commandPath);
+            }
+        }
+        const rawDefaultVariant = profileValue.defaultVariant;
+        let defaultVariant;
+        if (rawDefaultVariant !== undefined) {
+            if (typeof rawDefaultVariant !== 'string') {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.defaultVariant must be a string`, commandPath);
+            }
+            this.#assertPresetVariantName(rawDefaultVariant, `${labelPrefix}.defaultVariant`, commandPath);
+            defaultVariant = rawDefaultVariant;
+        }
+        const rawVariants = profileValue.variants;
+        let variants;
+        if (rawVariants !== undefined) {
+            if (typeof rawVariants !== 'object' || rawVariants === null || Array.isArray(rawVariants)) {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.variants must be an object`, commandPath);
+            }
+            variants = {};
+            for (const [variantName, variantValue] of Object.entries(rawVariants)) {
+                this.#assertPresetVariantName(variantName, `${labelPrefix}.variants["${variantName}"]`, commandPath);
+                if (typeof variantValue !== 'object' ||
+                    variantValue === null ||
+                    Array.isArray(variantValue)) {
+                    throw new CommanderError('ConfigurationError', `${labelPrefix}.variants["${variantName}"] must be an object`, commandPath);
+                }
+                variants[variantName] = this.#parsePresetProfileVariantItem(variantValue, `${labelPrefix}.variants["${variantName}"]`, commandPath);
+            }
         }
-        if (commandPresetFile !== undefined) {
-            return [
-                {
-                    displayPath: commandPresetFile,
-                    absolutePath: this.#resolvePresetFileAbsolutePath(commandPresetFile, presetRoot),
-                    explicit: true,
-                },
-            ];
-        }
-        const absolutePath = this.#runtime.resolve(presetRoot, defaultFilename);
-        return [
-            {
-                displayPath: absolutePath,
-                absolutePath,
-                explicit: false,
-            },
-        ];
+        if (defaultVariant !== undefined &&
+            (variants === undefined || variants[defaultVariant] === undefined)) {
+            throw new CommanderError('ConfigurationError', `${labelPrefix}.defaultVariant "${defaultVariant}" is not found in variants`, commandPath);
+        }
+        return {
+            envFile,
+            envs,
+            opts,
+            defaultVariant,
+            variants,
+        };
     }
-    #resolvePresetFileAbsolutePath(filepath, presetRoot) {
-        if (this.#runtime.isAbsolute(filepath)) {
-            return filepath;
+    #parsePresetProfileVariantItem(variantValue, labelPrefix, commandPath) {
+        const envFile = variantValue.envFile;
+        if (envFile !== undefined) {
+            if (typeof envFile !== 'string') {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.envFile must be a string`, commandPath);
+            }
         }
-        if (presetRoot !== undefined) {
-            return this.#runtime.resolve(presetRoot, filepath);
+        const rawEnvs = variantValue.envs;
+        let envs;
+        if (rawEnvs !== undefined) {
+            if (typeof rawEnvs !== 'object' || rawEnvs === null || Array.isArray(rawEnvs)) {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.envs must be an object`, commandPath);
+            }
+            envs = {};
+            for (const [key, value] of Object.entries(rawEnvs)) {
+                if (typeof value !== 'string') {
+                    throw new CommanderError('ConfigurationError', `${labelPrefix}.envs["${key}"] must be a string`, commandPath);
+                }
+                envs[key] = value;
+            }
         }
-        return this.#runtime.resolve(this.#runtime.cwd(), filepath);
+        const rawOpts = variantValue.opts;
+        let opts;
+        if (rawOpts !== undefined) {
+            if (typeof rawOpts !== 'object' || rawOpts === null || Array.isArray(rawOpts)) {
+                throw new CommanderError('ConfigurationError', `${labelPrefix}.opts must be an object`, commandPath);
+            }
+            opts = {};
+            for (const [key, value] of Object.entries(rawOpts)) {
+                opts[key] = this.#parsePresetProfileOptionValue(value, `${labelPrefix}.opts["${key}"]`, commandPath);
+            }
+        }
+        return {
+            envFile,
+            envs,
+            opts,
+        };
     }
-    #assertPresetOptionFragments(tokens, filepath, chain, optionPolicyMap) {
-        if (tokens.length === 0) {
-            return;
+    #parsePresetProfileOptionValue(value, valueLabel, commandPath) {
+        if (typeof value === 'boolean' || typeof value === 'string') {
+            return value;
         }
-        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);
+        if (typeof value === 'number') {
+            if (!Number.isFinite(value)) {
+                throw new CommanderError('ConfigurationError', `${valueLabel} must be a finite number`, commandPath);
             }
+            return value;
         }
-        catch (error) {
-            if (error instanceof CommanderError) {
-                if (error.kind === 'ConfigurationError') {
-                    throw error;
+        if (Array.isArray(value)) {
+            return value.map((item, index) => {
+                if (typeof item === 'string') {
+                    return item;
                 }
-                throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": ${error.message}`, commandPath);
+                if (typeof item === 'number' && Number.isFinite(item)) {
+                    return item;
+                }
+                throw new CommanderError('ConfigurationError', `${valueLabel}[${index}] must be a string or finite number`, commandPath);
+            });
+        }
+        throw new CommanderError('ConfigurationError', `${valueLabel} must be boolean|string|number|(string|number)[]`, commandPath);
+    }
+    #normalizePresetProfileEnvs(envs, _profileName, _commandPath) {
+        return envs === undefined ? {} : { ...envs };
+    }
+    #normalizePresetOptionName(rawName, profileName, commandPath) {
+        const value = rawName.trim();
+        if (value.length === 0) {
+            throw new CommanderError('ConfigurationError', `invalid option name "" in preset profile "${profileName}"`, commandPath);
+        }
+        const stripped = value.startsWith('--') ? value.slice(2) : value;
+        if (stripped.length === 0) {
+            throw new CommanderError('ConfigurationError', `invalid option name "${rawName}" in preset profile "${profileName}"`, commandPath);
+        }
+        if (stripped.includes('-')) {
+            const lowered = stripped.toLowerCase();
+            if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(lowered)) {
+                throw new CommanderError('ConfigurationError', `invalid option name "${rawName}" in preset profile "${profileName}"`, commandPath);
             }
-            throw error;
+            return kebabToCamelCase(lowered);
+        }
+        if (!/^[a-z][a-zA-Z0-9]*$/.test(stripped)) {
+            throw new CommanderError('ConfigurationError', `invalid option name "${rawName}" in preset profile "${profileName}"`, commandPath);
         }
+        return stripped;
     }
-    #scanPresetRootDirectives(argv, commandPath) {
-        const cleanArgv = [];
-        const cliPresetRoots = [];
-        let index = 0;
-        while (index < argv.length) {
-            const token = argv[index];
-            if (token === PRESET_ROOT_FLAG) {
-                const value = argv[index + 1];
-                if (value === undefined || value.length === 0) {
-                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_ROOT_FLAG}"`, commandPath);
-                }
-                cliPresetRoots.push(value);
-                index += 2;
+    #buildPresetArgvFromProfileOptions(opts, profileName, commandPath) {
+        const argv = [];
+        for (const [rawName, rawValue] of Object.entries(opts)) {
+            const optionName = this.#normalizePresetOptionName(rawName, profileName, commandPath);
+            const kebabName = camelToKebabCase(optionName);
+            const positiveFlag = `--${kebabName}`;
+            const negativeFlag = `--no-${kebabName}`;
+            if (typeof rawValue === 'boolean') {
+                argv.push(rawValue ? positiveFlag : negativeFlag);
                 continue;
             }
-            if (token.startsWith(`${PRESET_ROOT_FLAG}=`)) {
-                const value = token.slice(PRESET_ROOT_FLAG.length + 1);
-                if (value.length === 0) {
-                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_ROOT_FLAG}"`, commandPath);
-                }
-                cliPresetRoots.push(value);
-                index += 1;
+            if (typeof rawValue === 'string') {
+                argv.push(positiveFlag, rawValue);
                 continue;
             }
-            cleanArgv.push(token);
-            index += 1;
+            if (typeof rawValue === 'number') {
+                argv.push(positiveFlag, String(rawValue));
+                continue;
+            }
+            if (rawValue.length === 0) {
+                continue;
+            }
+            argv.push(positiveFlag, ...rawValue.map(value => String(value)));
         }
-        return { cleanArgv, cliPresetRoots };
+        return argv;
     }
-    #scanPresetFileDirectives(argv, commandPath) {
+    #scanPresetProfileDirectives(argv, commandPath) {
         const cleanArgv = [];
-        const cliPresetOptsFiles = [];
-        const cliPresetEnvsFiles = [];
-        const assertAndPush = (flag, value) => {
-            this.#assertPresetFileValue(value, flag, commandPath);
-            if (flag === PRESET_OPTS_FLAG) {
-                cliPresetOptsFiles.push(value);
+        let presetFile;
+        let presetProfile;
+        const assignDirective = (flag, value) => {
+            if (flag === PRESET_FILE_FLAG) {
+                presetFile = value;
             }
             else {
-                cliPresetEnvsFiles.push(value);
+                this.#assertPresetProfileSelectorValue(value, PRESET_PROFILE_FLAG, commandPath);
+                presetProfile = value;
             }
         };
         let index = 0;
         while (index < argv.length) {
             const token = argv[index];
-            if (token === PRESET_OPTS_FLAG || token === PRESET_ENVS_FLAG) {
+            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);
                 }
-                assertAndPush(token, value);
+                assignDirective(token, value);
                 index += 2;
                 continue;
             }
-            if (token.startsWith(`${PRESET_OPTS_FLAG}=`)) {
-                const value = token.slice(PRESET_OPTS_FLAG.length + 1);
+            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_OPTS_FLAG}"`, commandPath);
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_FILE_FLAG}"`, commandPath);
                 }
-                assertAndPush(PRESET_OPTS_FLAG, value);
+                assignDirective(PRESET_FILE_FLAG, value);
                 index += 1;
                 continue;
             }
-            if (token.startsWith(`${PRESET_ENVS_FLAG}=`)) {
-                const value = token.slice(PRESET_ENVS_FLAG.length + 1);
+            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_ENVS_FLAG}"`, commandPath);
+                    throw new CommanderError('ConfigurationError', `missing value for "${PRESET_PROFILE_FLAG}"`, commandPath);
                 }
-                assertAndPush(PRESET_ENVS_FLAG, value);
+                assignDirective(PRESET_PROFILE_FLAG, value);
                 index += 1;
                 continue;
             }
             cleanArgv.push(token);
             index += 1;
         }
-        return { cleanArgv, cliPresetOptsFiles, cliPresetEnvsFiles };
+        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;
+        }
     }
-    #isValidPresetFileValue(filepath) {
-        return filepath.length > 0 && !filepath.startsWith('..');
+    #assertPresetProfileSelectorValue(selector, sourceName, commandPath) {
+        void this.#parsePresetProfileSelector(selector, sourceName, commandPath);
     }
-    #assertPresetFileValue(filepath, directive, commandPath) {
-        if (this.#isValidPresetFileValue(filepath)) {
+    #parsePresetProfileSelector(selector, sourceName, commandPath) {
+        const normalizedSelector = selector.trim();
+        const separatorIndex = normalizedSelector.indexOf(PRESET_SELECTOR_DELIMITER);
+        if (separatorIndex < 0) {
+            this.#assertPresetProfileName(normalizedSelector, sourceName, commandPath);
+            return { profileName: normalizedSelector };
+        }
+        if (normalizedSelector.indexOf(PRESET_SELECTOR_DELIMITER, separatorIndex + 1) >= 0) {
+            throw new CommanderError('ConfigurationError', `invalid value for "${sourceName}": "${selector}" (must be "<profile>" or "<profile>:<variant>")`, commandPath);
+        }
+        const profileName = normalizedSelector.slice(0, separatorIndex);
+        const variantName = normalizedSelector.slice(separatorIndex + 1);
+        if (profileName.length === 0 || variantName.length === 0) {
+            throw new CommanderError('ConfigurationError', `invalid value for "${sourceName}": "${selector}" (must be "<profile>" or "<profile>:<variant>")`, commandPath);
+        }
+        this.#assertPresetProfileName(profileName, sourceName, commandPath);
+        this.#assertPresetVariantName(variantName, sourceName, commandPath);
+        return { profileName, variantName };
+    }
+    #assertPresetProfileName(profileName, sourceName, commandPath) {
+        if (PRESET_PROFILE_NAME_REGEX.test(profileName)) {
             return;
         }
-        throw new CommanderError('ConfigurationError', `invalid value for "${directive}": "${filepath}" (must be non-empty and must not start with "..")`, commandPath);
+        throw new CommanderError('ConfigurationError', `invalid profile name for "${sourceName}": "${profileName}" (must match ${PRESET_PROFILE_NAME_REGEX.source})`, commandPath);
+    }
+    #assertPresetVariantName(variantName, sourceName, commandPath) {
+        if (PRESET_VARIANT_NAME_REGEX.test(variantName)) {
+            return;
+        }
+        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);
         }
         catch (error) {
@@ -1270,11 +1535,13 @@ class Command {
             throw new CommanderError('ConfigurationError', `failed to read preset file "${file.displayPath}": ${error.message}`, commandPath);
         }
     }
-    #tokenizePresetOptions(content) {
-        return content
-            .split(/\s+/)
-            .map(token => token.trim())
-            .filter(token => token.length > 0);
+    #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);
+        }
     }
     #validatePresetOptionTokens(tokens, filepath, commandPath) {
         if (tokens.length === 0) {
@@ -1290,12 +1557,10 @@ class Command {
             if (token === 'help' || token === '--help' || token === '--version') {
                 throw new CommanderError('ConfigurationError', `invalid preset options in "${filepath}": control token "${token}" is not allowed`, commandPath);
             }
-            if (token === PRESET_ROOT_FLAG ||
-                token.startsWith(`${PRESET_ROOT_FLAG}=`) ||
-                token === PRESET_OPTS_FLAG ||
-                token.startsWith(`${PRESET_OPTS_FLAG}=`) ||
-                token === PRESET_ENVS_FLAG ||
-                token.startsWith(`${PRESET_ENVS_FLAG}=`)) {
+            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);
             }
         }