@guanghechen/commander 4.7.8 → 4.8.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Change Log
 
+## 4.8.0
+
+### Minor Changes
+
+- Expose preset directives in command help output under a dedicated `Preset Directives:` section.
+
+## 4.7.9
+
+### Patch Changes
+
+- Support preset profile fallback by command-path suffix using dot notation, and expose resolved
+  preset envFile path metadata in input sources.
+
 ## 4.7.8
 
 ### Patch Changes

package/lib/cjs/browser.cjs

@@ -1333,6 +1333,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1403,6 +1404,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1442,6 +1451,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1464,6 +1481,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -1774,11 +1792,14 @@ class CommandPresetProfileParser {
             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);
@@ -1859,6 +1880,52 @@ class CommandPresetProfileParser {
             }
         }
     }
+    #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 {
@@ -2786,7 +2853,7 @@ function scanPresetDirectives(params) {
     return { cleanArgv, presetFile, presetProfile };
 }
 function buildPresetSources(params) {
-    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta } = params;
+    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta, presetResolvedEnvFile, } = params;
     const presetSourceMeta = presetMeta === undefined
         ? undefined
         : {
@@ -2794,6 +2861,11 @@ function buildPresetSources(params) {
             file: presetMeta.file,
             profile: presetMeta.profile,
             variant: presetMeta.variant,
+            ...(presetResolvedEnvFile === undefined
+                ? {}
+                : {
+                    resolvedEnvFile: presetResolvedEnvFile,
+                }),
         };
     const presetState = presetSourceMeta === undefined ? 'none' : 'applied';
     const sources = {
@@ -2900,9 +2972,17 @@ async function runPresetStage(params) {
         presetArgv,
         presetEnvs,
         presetMeta: resolvedProfile?.issueMeta,
+        presetResolvedEnvFile: resolvePresetEnvFilePath(resolvedProfile),
     });
     return { tailArgv, envs, segments, sources };
 }
+function resolvePresetEnvFilePath(resolvedProfile) {
+    if (!resolvedProfile) {
+        return undefined;
+    }
+    return (resolvedProfile.variantEnvFileSource?.absolutePath ??
+        resolvedProfile.profileEnvFileSource?.absolutePath);
+}
 
 function findSubcommandEntry(entries, token) {
     return entries.find(entry => entry.name === token || entry.aliases.includes(token));
@@ -3324,6 +3404,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,

package/lib/cjs/node.cjs

@@ -1346,6 +1346,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1416,6 +1417,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1455,6 +1464,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1477,6 +1494,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -1787,11 +1805,14 @@ class CommandPresetProfileParser {
             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);
@@ -1872,6 +1893,52 @@ class CommandPresetProfileParser {
             }
         }
     }
+    #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 {
@@ -2799,7 +2866,7 @@ function scanPresetDirectives(params) {
     return { cleanArgv, presetFile, presetProfile };
 }
 function buildPresetSources(params) {
-    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta } = params;
+    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta, presetResolvedEnvFile, } = params;
     const presetSourceMeta = presetMeta === undefined
         ? undefined
         : {
@@ -2807,6 +2874,11 @@ function buildPresetSources(params) {
             file: presetMeta.file,
             profile: presetMeta.profile,
             variant: presetMeta.variant,
+            ...(presetResolvedEnvFile === undefined
+                ? {}
+                : {
+                    resolvedEnvFile: presetResolvedEnvFile,
+                }),
         };
     const presetState = presetSourceMeta === undefined ? 'none' : 'applied';
     const sources = {
@@ -2913,9 +2985,17 @@ async function runPresetStage(params) {
         presetArgv,
         presetEnvs,
         presetMeta: resolvedProfile?.issueMeta,
+        presetResolvedEnvFile: resolvePresetEnvFilePath(resolvedProfile),
     });
     return { tailArgv, envs, segments, sources };
 }
+function resolvePresetEnvFilePath(resolvedProfile) {
+    if (!resolvedProfile) {
+        return undefined;
+    }
+    return (resolvedProfile.variantEnvFileSource?.absolutePath ??
+        resolvedProfile.profileEnvFileSource?.absolutePath);
+}
 
 function findSubcommandEntry(entries, token) {
     return entries.find(entry => entry.name === token || entry.aliases.includes(token));
@@ -3337,6 +3417,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,

package/lib/esm/browser.mjs

@@ -1331,6 +1331,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1401,6 +1402,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1440,6 +1449,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1462,6 +1479,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -1772,11 +1790,14 @@ class CommandPresetProfileParser {
             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);
@@ -1857,6 +1878,52 @@ class CommandPresetProfileParser {
             }
         }
     }
+    #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 {
@@ -2784,7 +2851,7 @@ function scanPresetDirectives(params) {
     return { cleanArgv, presetFile, presetProfile };
 }
 function buildPresetSources(params) {
-    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta } = params;
+    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta, presetResolvedEnvFile, } = params;
     const presetSourceMeta = presetMeta === undefined
         ? undefined
         : {
@@ -2792,6 +2859,11 @@ function buildPresetSources(params) {
             file: presetMeta.file,
             profile: presetMeta.profile,
             variant: presetMeta.variant,
+            ...(presetResolvedEnvFile === undefined
+                ? {}
+                : {
+                    resolvedEnvFile: presetResolvedEnvFile,
+                }),
         };
     const presetState = presetSourceMeta === undefined ? 'none' : 'applied';
     const sources = {
@@ -2898,9 +2970,17 @@ async function runPresetStage(params) {
         presetArgv,
         presetEnvs,
         presetMeta: resolvedProfile?.issueMeta,
+        presetResolvedEnvFile: resolvePresetEnvFilePath(resolvedProfile),
     });
     return { tailArgv, envs, segments, sources };
 }
+function resolvePresetEnvFilePath(resolvedProfile) {
+    if (!resolvedProfile) {
+        return undefined;
+    }
+    return (resolvedProfile.variantEnvFileSource?.absolutePath ??
+        resolvedProfile.profileEnvFileSource?.absolutePath);
+}
 
 function findSubcommandEntry(entries, token) {
     return entries.find(entry => entry.name === token || entry.aliases.includes(token));
@@ -3322,6 +3402,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,

package/lib/esm/node.mjs

@@ -1344,6 +1344,7 @@ class CommandHelpRenderer {
             usage,
             arguments: argumentsLines,
             options,
+            presetDirectives: params.presetDirectives ?? [],
             commands,
             examples,
         };
@@ -1414,6 +1415,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push('Preset Directives:');
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push('Commands:');
             for (const { name, desc } of helpData.commands) {
@@ -1453,6 +1462,14 @@ class CommandHelpRenderer {
             }
             lines.push('');
         }
+        const presetDirectives = helpData.presetDirectives ?? [];
+        if (presetDirectives.length > 0) {
+            lines.push(styleText('Preset Directives:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
+            for (const { sig, desc } of presetDirectives) {
+                lines.push(this.#renderAlignedHelpLine(sig, desc, labelWidth, value => styleText(value, TERMINAL_STYLE.cyan)));
+            }
+            lines.push('');
+        }
         if (helpData.commands.length > 0) {
             lines.push(styleText('Commands:', TERMINAL_STYLE.bold, TERMINAL_STYLE.underline));
             for (const { name, desc } of helpData.commands) {
@@ -1475,6 +1492,7 @@ class CommandHelpRenderer {
         const labels = [
             ...helpData.arguments.map(line => line.sig),
             ...helpData.options.map(line => line.sig),
+            ...(helpData.presetDirectives ?? []).map(line => line.sig),
             ...helpData.commands.map(line => line.name),
         ];
         if (labels.length === 0) {
@@ -1785,11 +1803,14 @@ class CommandPresetProfileParser {
             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);
@@ -1870,6 +1891,52 @@ class CommandPresetProfileParser {
             }
         }
     }
+    #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 {
@@ -2797,7 +2864,7 @@ function scanPresetDirectives(params) {
     return { cleanArgv, presetFile, presetProfile };
 }
 function buildPresetSources(params) {
-    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta } = params;
+    const { userCmds, userArgv, userEnvs, presetArgv, presetEnvs, presetMeta, presetResolvedEnvFile, } = params;
     const presetSourceMeta = presetMeta === undefined
         ? undefined
         : {
@@ -2805,6 +2872,11 @@ function buildPresetSources(params) {
             file: presetMeta.file,
             profile: presetMeta.profile,
             variant: presetMeta.variant,
+            ...(presetResolvedEnvFile === undefined
+                ? {}
+                : {
+                    resolvedEnvFile: presetResolvedEnvFile,
+                }),
         };
     const presetState = presetSourceMeta === undefined ? 'none' : 'applied';
     const sources = {
@@ -2911,9 +2983,17 @@ async function runPresetStage(params) {
         presetArgv,
         presetEnvs,
         presetMeta: resolvedProfile?.issueMeta,
+        presetResolvedEnvFile: resolvePresetEnvFilePath(resolvedProfile),
     });
     return { tailArgv, envs, segments, sources };
 }
+function resolvePresetEnvFilePath(resolvedProfile) {
+    if (!resolvedProfile) {
+        return undefined;
+    }
+    return (resolvedProfile.variantEnvFileSource?.absolutePath ??
+        resolvedProfile.profileEnvFileSource?.absolutePath);
+}
 
 function findSubcommandEntry(entries, token) {
     return entries.find(entry => entry.name === token || entry.aliases.includes(token));
@@ -3335,6 +3415,16 @@ class Command {
             commandPath: this.#getCommandPath(),
             arguments: this.#arguments,
             options: this.#resolveOptionPolicy().mergedOptions,
+            presetDirectives: [
+                {
+                    sig: `${PRESET_FILE_FLAG} <value>`,
+                    desc: 'Load preset manifest file',
+                },
+                {
+                    sig: `${PRESET_PROFILE_FLAG} <value>`,
+                    desc: 'Select preset profile: <profile> or <profile>:<variant>; requires --preset-file or command preset.file',
+                },
+            ],
             supportsBuiltinVersion: this.#supportsBuiltinVersion(),
             subcommands,
             examples: this.#examples,

package/lib/types/browser.d.ts

@@ -17,6 +17,7 @@ interface ICommandPresetSourceMeta {
     file?: string;
     profile?: string;
     variant?: string;
+    resolvedEnvFile?: string;
 }
 /** Preset execution state in input source snapshot */
 type ICommandPresetSourceState = 'skipped' | 'none' | 'applied';
@@ -390,6 +391,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help preset directive line (internal) */
+interface IHelpPresetDirectiveLine {
+    sig: string;
+    desc: string;
+}
 /** Help argument line (internal) */
 interface IHelpArgumentLine {
     sig: string;
@@ -412,6 +418,7 @@ interface IHelpData {
     usage: string;
     arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
+    presetDirectives?: IHelpPresetDirectiveLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
 }
@@ -673,4 +680,4 @@ declare function getDefaultCommandRuntime(): ICommandRuntime;
 declare function setDefaultCommandRuntime(runtime: ICommandRuntime): void;
 
 export { Coerce, Command, CommanderError, createBrowserCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, IHelpPresetDirectiveLine, ISubcommandEntry };

package/lib/types/node.d.ts

@@ -17,6 +17,7 @@ interface ICommandPresetSourceMeta {
     file?: string;
     profile?: string;
     variant?: string;
+    resolvedEnvFile?: string;
 }
 /** Preset execution state in input source snapshot */
 type ICommandPresetSourceState = 'skipped' | 'none' | 'applied';
@@ -390,6 +391,11 @@ interface IHelpOptionLine {
     sig: string;
     desc: string;
 }
+/** Help preset directive line (internal) */
+interface IHelpPresetDirectiveLine {
+    sig: string;
+    desc: string;
+}
 /** Help argument line (internal) */
 interface IHelpArgumentLine {
     sig: string;
@@ -412,6 +418,7 @@ interface IHelpData {
     usage: string;
     arguments: IHelpArgumentLine[];
     options: IHelpOptionLine[];
+    presetDirectives?: IHelpPresetDirectiveLine[];
     commands: IHelpCommandLine[];
     examples: IHelpExampleLine[];
 }
@@ -726,4 +733,4 @@ declare class PwshCompletion {
 }
 
 export { BashCompletion, Coerce, Command, CommanderError, CompletionCommand, FishCompletion, PwshCompletion, createBrowserCommandRuntime, createNodeCommandRuntime, getDefaultCommandRuntime, isDomain, isIp, isIpv4, isIpv6, logColorfulOption, logDateOption, setDefaultCommandRuntime, silentOption };
-export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, ISubcommandEntry };
+export type { ICommand, ICommandAction, ICommandActionParams, ICommandArgumentConfig, ICommandArgumentKind, ICommandArgumentType, ICommandArgvSegment, ICommandBuiltinConfig, ICommandBuiltinOptionConfig, ICommandBuiltinOptionResolved, ICommandBuiltinParsedOptions, ICommandBuiltinResolved, ICommandConfig, ICommandContext, ICommandControlScanResult, ICommandControls, ICommandErrorIssue, ICommandErrorIssueCode, ICommandErrorMeta, ICommandExample, ICommandHintIssue, ICommandHintIssueCode, ICommandInputSources, ICommandIssue, ICommandIssueBase, ICommandIssueCode, ICommandIssueKind, ICommandIssueReason, ICommandIssueScope, ICommandIssueSourceAttribution, ICommandOptionArgs, ICommandOptionConfig, ICommandOptionType, ICommandParseResult, ICommandParsedArgs, ICommandParsedOpts, ICommandPresetConfig, ICommandPresetIssueMeta, ICommandPresetProfileDefaults, ICommandPresetProfileItem, ICommandPresetProfileManifest, ICommandPresetProfileOptionValue, ICommandPresetProfileVariantItem, ICommandPresetResult, ICommandPresetSourceMeta, ICommandPresetSourceState, ICommandResolveResult, ICommandRouteResult, ICommandRunParams, ICommandRuntime, ICommandRuntimeStats, ICommandShiftResult, ICommandStage, ICommandToken, ICommandTokenSource, ICommandTokenType, ICommandTokenizeResult, ICommanderErrorKind, ICompletionArgumentMeta, ICompletionCommandConfig, ICompletionMeta, ICompletionOptionMeta, ICompletionPaths, ICompletionShellType, IHelpArgumentLine, IHelpCommandLine, IHelpData, IHelpExampleLine, IHelpOptionLine, IHelpPresetDirectiveLine, ISubcommandEntry };

package/package.json

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

package/lib/schema/preset.config.schema.json

@@ -1,152 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://guanghechen.github.io/sora/schemas/commander/preset.config.schema.json",
-  "title": "Commander Preset Config",
-  "description": "Preset profile manifest for @guanghechen/commander --preset-file.",
-  "type": "object",
-  "additionalProperties": false,
-  "required": ["version", "profiles"],
-  "examples": [
-    {
-      "version": 1,
-      "defaults": { "profile": "dev:local" },
-      "profiles": {
-        "dev": {
-          "envFile": "dev.env",
-          "envs": { "NODE_ENV": "development" },
-          "opts": { "logLevel": "debug", "retry": 2 },
-          "defaultVariant": "local",
-          "variants": {
-            "local": { "opts": { "retry": 1 } },
-            "ci": { "envFile": "ci.env", "envs": { "CI": "1" } }
-          }
-        }
-      }
-    }
-  ],
-  "properties": {
-    "$schema": {
-      "type": "string",
-      "description": "Optional schema reference for editors (e.g. VSCode)."
-    },
-    "version": {
-      "type": "integer",
-      "const": 1,
-      "description": "Schema version."
-    },
-    "defaults": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "profile": {
-          "$ref": "#/$defs/profileSelector"
-        }
-      },
-      "description": "Default selector when --preset-profile is not provided."
-    },
-    "profiles": {
-      "type": "object",
-      "minProperties": 1,
-      "propertyNames": {
-        "$ref": "#/$defs/profileName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/profileItem"
-      },
-      "description": "Profiles keyed by profile name."
-    }
-  },
-  "$defs": {
-    "profileName": {
-      "type": "string",
-      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
-      "description": "Profile/variant name."
-    },
-    "profileSelector": {
-      "type": "string",
-      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*(?::[A-Za-z0-9][A-Za-z0-9._-]*)?$",
-      "description": "Selector format: <profile> or <profile>:<variant>."
-    },
-    "optionName": {
-      "type": "string",
-      "pattern": "^(?:--)?(?:[a-z][a-zA-Z0-9]*|[A-Za-z][A-Za-z0-9]*(?:-[A-Za-z0-9]+)+)$",
-      "description": "Option key in opts map; aligned with runtime normalization."
-    },
-    "optionValue": {
-      "oneOf": [
-        { "type": "boolean" },
-        { "type": "string" },
-        { "type": "number" },
-        {
-          "type": "array",
-          "items": {
-            "oneOf": [{ "type": "string" }, { "type": "number" }]
-          }
-        }
-      ]
-    },
-    "envMap": {
-      "type": "object",
-      "additionalProperties": {
-        "type": "string"
-      }
-    },
-    "optsMap": {
-      "type": "object",
-      "propertyNames": {
-        "$ref": "#/$defs/optionName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/optionValue"
-      }
-    },
-    "variantItem": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "envFile": {
-          "type": "string",
-          "minLength": 1
-        },
-        "envs": {
-          "$ref": "#/$defs/envMap"
-        },
-        "opts": {
-          "$ref": "#/$defs/optsMap"
-        }
-      }
-    },
-    "variantsMap": {
-      "type": "object",
-      "propertyNames": {
-        "$ref": "#/$defs/profileName"
-      },
-      "additionalProperties": {
-        "$ref": "#/$defs/variantItem"
-      }
-    },
-    "profileItem": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "envFile": {
-          "type": "string",
-          "minLength": 1
-        },
-        "envs": {
-          "$ref": "#/$defs/envMap"
-        },
-        "opts": {
-          "$ref": "#/$defs/optsMap"
-        },
-        "defaultVariant": {
-          "$ref": "#/$defs/profileName"
-        },
-        "variants": {
-          "$ref": "#/$defs/variantsMap"
-        }
-      },
-      "description": "defaultVariant existence in variants must still be validated by runtime."
-    }
-  }
-}