@karmaniverous/get-dotenv 6.0.0 → 6.1.1

package/dist/cli.mjs

@@ -169,6 +169,10 @@ function defaultsDeep(...layers) {
 /**
  * Serialize a dotenv record to a file with minimal quoting (multiline values are quoted).
  * Future-proofs for ordering/sorting changes (currently insertion order).
+ *
+ * @param filename - Destination dotenv file path.
+ * @param data - Env-like map of values to write (values may be `undefined`).
+ * @returns A `Promise\<void\>` which resolves when the file has been written.
  */
 async function writeDotenvFile(filename, data) {
     // Serialize: key=value with quotes only for multiline values.
@@ -404,14 +408,20 @@ const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Numbe
     }
 };
 /**
- * Load a module default export from a JS/TS file with robust fallbacks:
- * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
- *   1) try direct import (if a TS loader is active),
- *   2) esbuild bundle to a temp ESM file,
- *   3) typescript.transpileModule fallback for simple modules.
+ * Load a module default export from a JS/TS file with robust fallbacks.
+ *
+ * Behavior by extension:
+ *
+ * - `.js`/`.mjs`/`.cjs`: direct dynamic import.
+ * - `.ts`/`.mts`/`.cts`/`.tsx`:
+ *   - try direct dynamic import (when a TS loader is active),
+ *   - else compile via `esbuild` to a cached `.mjs` file and import,
+ *   - else fallback to `typescript.transpileModule` for simple modules.
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * @typeParam T - Type of the expected default export.
+ * @param absPath - Absolute path to the source file.
+ * @param cacheDirName - Cache subfolder under `.tsbuild/`.
+ * @returns A `Promise\<T | undefined\>` resolving to the default export (if any).
  */
 const loadModuleDefault = async (absPath, cacheDirName) => {
     const ext = path.extname(absPath).toLowerCase();
@@ -483,6 +493,10 @@ const loadModuleDefault = async (absPath, cacheDirName) => {
 /**
  * Omit keys whose runtime value is undefined from a shallow object.
  * Returns a Partial with non-undefined value types preserved.
+ *
+ * @typeParam T - Input object shape.
+ * @param obj - Object to filter.
+ * @returns A shallow copy of `obj` without keys whose value is `undefined`.
  */
 function omitUndefined(obj) {
     const out = {};
@@ -494,6 +508,10 @@ function omitUndefined(obj) {
 }
 /**
  * Specialized helper for env-like maps: drop undefined and return string-only.
+ *
+ * @typeParam V - Value type for present entries (must extend `string`).
+ * @param obj - Env-like record containing `string | undefined` values.
+ * @returns A new record containing only the keys with defined values.
  */
 function omitUndefinedRecord(obj) {
     const out = {};
@@ -711,6 +729,10 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
  * - Else if `requiredKeys` is present, check presence (value !== undefined).
  * - Returns a flat list of issue strings; caller decides warn vs fail.
+ *
+ * @param finalEnv - Final composed environment to validate.
+ * @param sources - Resolved config sources providing `schema` and/or `requiredKeys`.
+ * @returns A list of human-readable issue strings (empty when valid).
  */
 const validateEnvAgainstSources = (finalEnv, sources) => {
     const pick = (getter) => {
@@ -770,6 +792,11 @@ const validateEnvAgainstSources = (finalEnv, sources) => {
  * Apply a dynamic map to the target progressively.
  * - Functions receive (target, env) and may return string | undefined.
  * - Literals are assigned directly (including undefined).
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param map - Dynamic map to apply (functions and/or literal values).
+ * @param env - Selected environment name (if any) passed through to dynamic functions.
+ * @returns Nothing.
  */
 function applyDynamicMap(target, map, env) {
     if (!map)
@@ -789,6 +816,12 @@ function applyDynamicMap(target, map, env) {
  * Error behavior:
  * - On failure to load/compile/evaluate the module, throws a unified message:
  *   "Unable to load dynamic TypeScript file: <absPath>. Install 'esbuild'..."
+ *
+ * @param target - Mutable target environment to assign into.
+ * @param absPath - Absolute path to the dynamic module file.
+ * @param env - Selected environment name (if any).
+ * @param cacheDirName - Cache subdirectory under `.tsbuild/` for compiled artifacts.
+ * @returns A `Promise\<void\>` which resolves after the module (if present) has been applied.
  */
 async function loadAndApplyDynamic(target, absPath, env, cacheDirName) {
     if (!(await fs.exists(absPath)))
@@ -1951,6 +1984,10 @@ function renderOptionGroups(cmd) {
 /**
  * Compose root/parent help output by inserting grouped sections between
  * Options and Commands, ensuring a trailing blank line.
+ *
+ * @param base - Base help text produced by Commander.
+ * @param cmd - Command instance whose grouped options should be rendered.
+ * @returns The modified help text with grouped blocks inserted.
  */
 function buildHelpInformation(base, cmd) {
     const groups = renderOptionGroups(cmd);
@@ -2463,6 +2500,10 @@ const toHelpConfig = (merged, plugins) => {
 /**
  * Compose a child-process env overlay from dotenv and the merged CLI options bag.
  * Returns a shallow object including getDotenvCliOptions when serializable.
+ *
+ * @param merged - Resolved CLI options bag (or a JSON-serializable subset).
+ * @param dotenv - Composed dotenv variables for the current invocation.
+ * @returns A string-only env overlay suitable for child process spawning.
  */
 function composeNestedEnv(merged, dotenv) {
     const out = {};
@@ -2485,6 +2526,7 @@ function composeNestedEnv(merged, dotenv) {
  * Strip one layer of symmetric outer quotes (single or double) from a string.
  *
  * @param s - Input string.
+ * @returns `s` without one symmetric outer quote pair (when present).
  */
 const stripOne = (s) => {
     if (s.length < 2)
@@ -2497,6 +2539,9 @@ const stripOne = (s) => {
 /**
  * Preserve argv array for Node -e/--eval payloads under shell-off and
  * peel one symmetric outer quote layer from the code argument.
+ *
+ * @param args - Argument vector intended for direct execution (shell-off).
+ * @returns Either the original `args` or a modified copy with a normalized eval payload.
  */
 function maybePreserveNodeEvalArgv(args) {
     if (args.length >= 3) {
@@ -2963,23 +3008,57 @@ function applyRootVisibility(program, visibility) {
  * Apply resolved AWS context to `process.env` and `ctx.plugins`.
  * Centralizes logic shared between the plugin action and `afterResolve` hook.
  *
+ * @param out - Resolved AWS context to apply.
+ * @param ctx - Host context to publish non-sensitive metadata into.
  * @param setProcessEnv - Whether to write credentials/region to `process.env` (default true).
+ * @returns Nothing.
  */
 function applyAwsContext(out, ctx, setProcessEnv = true) {
     const { profile, region, credentials } = out;
     if (setProcessEnv) {
-        if (region) {
-            process.env.AWS_REGION = region;
-            if (!process.env.AWS_DEFAULT_REGION) {
-                process.env.AWS_DEFAULT_REGION = region;
+        // Ensure AWS credential sources are mutually exclusive.
+        // The AWS SDK warns (and may change precedence in future) when both
+        // AWS_PROFILE and AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY are set.
+        const clear = (keys) => {
+            for (const k of keys) {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete process.env[k];
             }
-        }
+        };
+        const clearProfileVars = () => {
+            clear(['AWS_PROFILE', 'AWS_DEFAULT_PROFILE', 'AWS_SDK_LOAD_CONFIG']);
+        };
+        const clearStaticCreds = () => {
+            clear([
+                'AWS_ACCESS_KEY_ID',
+                'AWS_SECRET_ACCESS_KEY',
+                'AWS_SESSION_TOKEN',
+            ]);
+        };
+        // Mode A: exported/static credentials (clear profile vars)
         if (credentials) {
+            clearProfileVars();
             process.env.AWS_ACCESS_KEY_ID = credentials.accessKeyId;
             process.env.AWS_SECRET_ACCESS_KEY = credentials.secretAccessKey;
             if (credentials.sessionToken !== undefined) {
                 process.env.AWS_SESSION_TOKEN = credentials.sessionToken;
             }
+            else {
+                delete process.env.AWS_SESSION_TOKEN;
+            }
+        }
+        else if (profile) {
+            // Mode B: profile-based (SSO) credentials (clear static creds)
+            clearStaticCreds();
+            process.env.AWS_PROFILE = profile;
+            process.env.AWS_DEFAULT_PROFILE = profile;
+            process.env.AWS_SDK_LOAD_CONFIG = '1';
+        }
+        if (region) {
+            process.env.AWS_REGION = region;
+            if (!process.env.AWS_DEFAULT_REGION) {
+                process.env.AWS_DEFAULT_REGION = region;
+            }
         }
     }
     // Always publish minimal, non-sensitive metadata
@@ -2990,7 +3069,7 @@ function applyAwsContext(out, ctx, setProcessEnv = true) {
     };
 }
 
-const DEFAULT_TIMEOUT_MS = 15_000;
+const AWS_CLI_TIMEOUT_MS = 15_000;
 const trim = (s) => (typeof s === 'string' ? s.trim() : '');
 const unquote = (s) => s.length >= 2 &&
     ((s.startsWith('"') && s.endsWith('"')) ||
@@ -2999,6 +3078,9 @@ const unquote = (s) => s.length >= 2 &&
     : s;
 /**
  * Parse AWS credentials from JSON output (AWS CLI v2 export-credentials).
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsJson = (txt) => {
     try {
@@ -3022,6 +3104,10 @@ const parseExportCredentialsJson = (txt) => {
 /**
  * Parse AWS credentials from environment-export output (shell-agnostic).
  * Supports POSIX `export KEY=VAL` and PowerShell `$Env:KEY=VAL`.
+ * Also supports AWS CLI `windows-cmd` (`set KEY=VAL`) and `env-no-export` (`KEY=VAL`).
+ *
+ * @param txt - Raw stdout text from the AWS CLI.
+ * @returns Parsed credentials, or `undefined` when the input is not recognized.
  */
 const parseExportCredentialsEnv = (txt) => {
     const lines = txt.split(/\r?\n/);
@@ -3032,12 +3118,17 @@ const parseExportCredentialsEnv = (txt) => {
         const line = raw.trim();
         if (!line)
             continue;
-        // POSIX: export AWS_ACCESS_KEY_ID=..., export AWS_SECRET_ACCESS_KEY=..., export AWS_SESSION_TOKEN=...
+        // POSIX: export AWS_ACCESS_KEY_ID=..., ...
         let m = /^export\s+([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
-        if (!m) {
-            // PowerShell: $Env:AWS_ACCESS_KEY_ID="...", etc.
-            m = /^\$Env:([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
-        }
+        // PowerShell: $Env:AWS_ACCESS_KEY_ID="...", etc.
+        if (!m)
+            m = /^\$Env:([A-Z0-9_]+)\s*=\s*(.+)$/i.exec(line);
+        // Windows cmd: set AWS_ACCESS_KEY_ID=..., etc.
+        if (!m)
+            m = /^(?:set)\s+([A-Z0-9_]+)\s*=\s*(.+)$/i.exec(line);
+        // env-no-export: AWS_ACCESS_KEY_ID=..., etc.
+        if (!m)
+            m = /^([A-Z0-9_]+)\s*=\s*(.+)$/.exec(line);
         if (!m)
             continue;
         const k = m[1];
@@ -3062,7 +3153,7 @@ const parseExportCredentialsEnv = (txt) => {
         };
     return undefined;
 };
-const getAwsConfigure = async (key, profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+const getAwsConfigure = async (key, profile, timeoutMs = AWS_CLI_TIMEOUT_MS) => {
     const r = await runCommandResult(['aws', 'configure', 'get', key, '--profile', profile], false, {
         env: process.env,
         timeoutMs,
@@ -3077,36 +3168,50 @@ const getAwsConfigure = async (key, profile, timeoutMs = DEFAULT_TIMEOUT_MS) =>
     }
     return undefined;
 };
-const exportCredentials = async (profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
-    // Try JSON format first (AWS CLI v2)
-    const rJson = await runCommandResult([
-        'aws',
-        'configure',
-        'export-credentials',
-        '--profile',
-        profile,
-        '--format',
-        'json',
-    ], false, { env: process.env, timeoutMs });
-    if (rJson.exitCode === 0) {
-        const creds = parseExportCredentialsJson(rJson.stdout);
-        if (creds)
-            return creds;
-    }
-    // Fallback: env lines
-    const rEnv = await runCommandResult(['aws', 'configure', 'export-credentials', '--profile', profile], false, { env: process.env, timeoutMs });
-    if (rEnv.exitCode === 0) {
-        const creds = parseExportCredentialsEnv(rEnv.stdout);
+const exportCredentials = async (profile, timeoutMs = AWS_CLI_TIMEOUT_MS) => {
+    const tryExport = async (format) => {
+        const argv = [
+            'aws',
+            'configure',
+            'export-credentials',
+            '--profile',
+            profile,
+            ...(format ? ['--format', format] : []),
+        ];
+        const r = await runCommandResult(argv, false, {
+            env: process.env,
+            timeoutMs,
+        });
+        if (r.exitCode !== 0)
+            return undefined;
+        const out = trim(r.stdout);
+        if (!out)
+            return undefined;
+        // Some formats produce JSON ("process"), some produce shell-ish env lines.
+        return parseExportCredentialsJson(out) ?? parseExportCredentialsEnv(out);
+    };
+    // Prefer the default/JSON "process" format first; then fall back to shell env outputs.
+    // Note: AWS CLI v2 supports: process | env | env-no-export | powershell | windows-cmd
+    const formats = [
+        'process',
+        ...(process.platform === 'win32'
+            ? ['powershell', 'windows-cmd', 'env', 'env-no-export']
+            : ['env', 'env-no-export']),
+    ];
+    for (const f of formats) {
+        const creds = await tryExport(f);
         if (creds)
             return creds;
     }
-    return undefined;
+    // Final fallback: no --format (AWS CLI default output)
+    return tryExport(undefined);
 };
 /**
  * Resolve AWS context (profile, region, credentials) using configuration and environment.
  * Applies strategy (cli-export vs none) and handling for SSO login-on-demand.
  *
  * @param options - Context options including current dotenv and plugin config.
+ * @returns A `Promise\<AwsContext\>` containing any resolved profile, region, and credentials.
  */
 const resolveAwsContext = async ({ dotenv, cfg, }) => {
     const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';
@@ -3131,31 +3236,27 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
             out.region = region;
         return out;
     }
-    // Env-first credentials.
     let credentials;
-    const envId = trim(process.env.AWS_ACCESS_KEY_ID);
-    const envSecret = trim(process.env.AWS_SECRET_ACCESS_KEY);
-    const envToken = trim(process.env.AWS_SESSION_TOKEN);
-    if (envId && envSecret) {
-        credentials = {
-            accessKeyId: envId,
-            secretAccessKey: envSecret,
-            ...(envToken ? { sessionToken: envToken } : {}),
-        };
-    }
-    else if (profile) {
+    // Profile wins over ambient env creds when present (from flags/config/dotenv).
+    if (profile) {
         // Try export-credentials
         credentials = await exportCredentials(profile);
         // On failure, detect SSO and optionally login then retry
         if (!credentials) {
             const ssoSession = await getAwsConfigure('sso_session', profile);
-            const looksSSO = typeof ssoSession === 'string' && ssoSession.length > 0;
+            // Legacy SSO profiles use sso_start_url/sso_region rather than sso_session.
+            const ssoStartUrl = await getAwsConfigure('sso_start_url', profile);
+            const looksSSO = (typeof ssoSession === 'string' && ssoSession.length > 0) ||
+                (typeof ssoStartUrl === 'string' && ssoStartUrl.length > 0);
             if (looksSSO && cfg.loginOnDemand) {
-                // Best-effort login, then retry export once.
-                await runCommandResult(['aws', 'sso', 'login', '--profile', profile], false, {
+                // Interactive login (no timeout by default), then retry export once.
+                const exit = await runCommand(['aws', 'sso', 'login', '--profile', profile], false, {
                     env: process.env,
-                    timeoutMs: DEFAULT_TIMEOUT_MS,
+                    stdio: 'inherit',
                 });
+                if (exit !== 0) {
+                    throw new Error(`aws sso login failed for profile '${profile}' (exit ${String(exit)})`);
+                }
                 credentials = await exportCredentials(profile);
             }
         }
@@ -3173,6 +3274,19 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
             }
         }
     }
+    else {
+        // Env-first credentials when no profile is present.
+        const envId = trim(process.env.AWS_ACCESS_KEY_ID);
+        const envSecret = trim(process.env.AWS_SECRET_ACCESS_KEY);
+        const envToken = trim(process.env.AWS_SESSION_TOKEN);
+        if (envId && envSecret) {
+            credentials = {
+                accessKeyId: envId,
+                secretAccessKey: envSecret,
+                ...(envToken ? { sessionToken: envToken } : {}),
+            };
+        }
+    }
     // Final region resolution
     if (!region && profile)
         region = await getAwsConfigure('region', profile);
@@ -3188,10 +3302,213 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
     return out;
 };
 
+/**
+ * Create the AWS plugin `afterResolve` hook.
+ *
+ * This runs once per invocation after the host resolves dotenv context.
+ *
+ * @param plugin - The AWS plugin instance.
+ * @returns An `afterResolve` hook function suitable for assigning to `plugin.afterResolve`.
+ *
+ * @internal
+ */
+function attachAwsAfterResolveHook(plugin) {
+    return async (cli, ctx) => {
+        const cfg = plugin.readConfig(cli);
+        const out = await resolveAwsContext({
+            dotenv: ctx.dotenv,
+            cfg,
+        });
+        applyAwsContext(out, ctx, true);
+        // Optional: low-noise breadcrumb for diagnostics
+        if (process.env.GETDOTENV_DEBUG) {
+            try {
+                const msg = JSON.stringify({
+                    profile: out.profile,
+                    region: out.region,
+                    hasCreds: Boolean(out.credentials),
+                });
+                process.stderr.write(`[aws] afterResolve ${msg}\n`);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    };
+}
+
+/** @internal */
+const isRecord = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Create an AWS plugin config overlay from Commander-parsed option values.
+ *
+ * This preserves tri-state intent:
+ * - If a flag was not provided, it should not overwrite config-derived defaults.
+ * - If `--no-…` was provided, it must explicitly force the boolean false.
+ *
+ * @param opts - Commander option values for the current invocation.
+ * @returns A partial AWS plugin config object containing only explicit overrides.
+ *
+ * @internal
+ */
+function awsConfigOverridesFromCommandOpts(opts) {
+    const o = isRecord(opts) ? opts : {};
+    const overlay = {};
+    // Map boolean toggles (respect explicit --no-*)
+    if (Object.prototype.hasOwnProperty.call(o, 'loginOnDemand')) {
+        overlay.loginOnDemand = Boolean(o.loginOnDemand);
+    }
+    // Strings/enums
+    if (typeof o.profile === 'string')
+        overlay.profile = o.profile;
+    if (typeof o.region === 'string')
+        overlay.region = o.region;
+    if (typeof o.defaultRegion === 'string')
+        overlay.defaultRegion = o.defaultRegion;
+    if (o.strategy === 'cli-export' || o.strategy === 'none') {
+        overlay.strategy = o.strategy;
+    }
+    // Advanced key overrides
+    if (typeof o.profileKey === 'string')
+        overlay.profileKey = o.profileKey;
+    if (typeof o.profileFallbackKey === 'string') {
+        overlay.profileFallbackKey = o.profileFallbackKey;
+    }
+    if (typeof o.regionKey === 'string')
+        overlay.regionKey = o.regionKey;
+    return overlay;
+}
+
+/**
+ * Attach the default action for the AWS plugin mount.
+ *
+ * Behavior:
+ * - With args: forwards to AWS CLI (`aws <args...>`) under the established session.
+ * - Without args: session-only establishment (no forward).
+ *
+ * @param cli - The `aws` command mount.
+ * @param plugin - The AWS plugin instance.
+ *
+ * @internal
+ */
+function attachAwsDefaultAction(cli, plugin, awsCmd) {
+    awsCmd.action(async (args, opts, thisCommand) => {
+        // Access merged root CLI options (installed by root hooks).
+        const bag = readMergedOptions(thisCommand);
+        const capture = shouldCapture(bag.capture);
+        const underTests = process.env.GETDOTENV_TEST === '1' ||
+            typeof process.env.VITEST_WORKER_ID === 'string';
+        // Build overlay cfg from subcommand flags layered over discovered config.
+        const ctx = cli.getCtx();
+        const cfgBase = plugin.readConfig(cli);
+        const cfg = {
+            ...cfgBase,
+            ...awsConfigOverridesFromCommandOpts(opts),
+        };
+        // Resolve current context with overrides
+        const out = await resolveAwsContext({
+            dotenv: ctx.dotenv,
+            cfg,
+        });
+        // Publish env/context
+        applyAwsContext(out, ctx, true);
+        // Forward when positional args are present; otherwise session-only.
+        if (args.length > 0) {
+            const argv = ['aws', ...args];
+            const shellSetting = resolveShell(bag.scripts, 'aws', bag.shell);
+            const exit = await runCommand(argv, shellSetting, {
+                env: buildSpawnEnv(process.env, ctx.dotenv),
+                stdio: capture ? 'pipe' : 'inherit',
+            });
+            // Deterministic termination (suppressed under tests)
+            if (!underTests) {
+                process.exit(typeof exit === 'number' ? exit : 0);
+            }
+            return;
+        }
+        // Session only: low-noise breadcrumb under debug
+        if (process.env.GETDOTENV_DEBUG) {
+            try {
+                const msg = JSON.stringify({
+                    profile: out.profile,
+                    region: out.region,
+                    hasCreds: Boolean(out.credentials),
+                });
+                process.stderr.write(`[aws] session established ${msg}\n`);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        if (!underTests)
+            process.exit(0);
+    });
+}
+
+/**
+ * Attach options/arguments for the AWS plugin mount.
+ *
+ * @param cli - The `aws` command mount.
+ * @param plugin - The AWS plugin instance (for dynamic option descriptions).
+ *
+ * @internal
+ */
+function attachAwsOptions(cli, plugin) {
+    return (cli
+        // Description is owned by the plugin index (src/plugins/aws/index.ts).
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .allowUnknownOption(true)
+        // Boolean toggles with dynamic help labels (effective defaults)
+        .addOption(plugin.createPluginDynamicOption(cli, '--login-on-demand', (_bag, cfg) => `attempt aws sso login on-demand${cfg.loginOnDemand ? ' (default)' : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--no-login-on-demand', (_bag, cfg) => `disable sso login on-demand${cfg.loginOnDemand === false ? ' (default)' : ''}`))
+        // Strings / enums
+        .addOption(plugin.createPluginDynamicOption(cli, '--profile <string>', (_bag, cfg) => `AWS profile name${cfg.profile ? ` (default: ${JSON.stringify(cfg.profile)})` : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--region <string>', (_bag, cfg) => `AWS region${cfg.region ? ` (default: ${JSON.stringify(cfg.region)})` : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--default-region <string>', (_bag, cfg) => `fallback region${cfg.defaultRegion ? ` (default: ${JSON.stringify(cfg.defaultRegion)})` : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--strategy <string>', (_bag, cfg) => `credential acquisition strategy: cli-export|none${cfg.strategy ? ` (default: ${JSON.stringify(cfg.strategy)})` : ''}`))
+        // Advanced key overrides
+        .addOption(plugin.createPluginDynamicOption(cli, '--profile-key <string>', (_bag, cfg) => `dotenv/config key for local profile${cfg.profileKey ? ` (default: ${JSON.stringify(cfg.profileKey)})` : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--profile-fallback-key <string>', (_bag, cfg) => `fallback dotenv/config key for profile${cfg.profileFallbackKey ? ` (default: ${JSON.stringify(cfg.profileFallbackKey)})` : ''}`))
+        .addOption(plugin.createPluginDynamicOption(cli, '--region-key <string>', (_bag, cfg) => `dotenv/config key for region${cfg.regionKey ? ` (default: ${JSON.stringify(cfg.regionKey)})` : ''}`))
+        // Accept any extra operands so Commander does not error when tokens appear after "--".
+        .argument('[args...]'));
+}
+
+/**
+ * Attach the AWS plugin `preSubcommand` hook.
+ *
+ * Ensures `aws --profile/--region <child>` applies the AWS session setup before
+ * child subcommand execution.
+ *
+ * @param cli - The `aws` command mount.
+ * @param plugin - The AWS plugin instance.
+ *
+ * @internal
+ */
+function attachAwsPreSubcommandHook(cli, plugin) {
+    cli.hook('preSubcommand', async (thisCommand) => {
+        // Avoid side effects for help rendering.
+        if (process.argv.includes('-h') || process.argv.includes('--help'))
+            return;
+        const ctx = cli.getCtx();
+        const cfgBase = plugin.readConfig(cli);
+        const cfg = {
+            ...cfgBase,
+            ...awsConfigOverridesFromCommandOpts(thisCommand.opts()),
+        };
+        const out = await resolveAwsContext({
+            dotenv: ctx.dotenv,
+            cfg,
+        });
+        applyAwsContext(out, ctx, true);
+    });
+}
+
 /**
  * Zod schema for AWS plugin configuration.
  */
-const AwsPluginConfigSchema = z$2.object({
+const awsPluginConfigSchema = z$2.object({
     profile: z$2.string().optional(),
     region: z$2.string().optional(),
     defaultRegion: z$2.string().optional(),
@@ -3215,129 +3532,16 @@ const AwsPluginConfigSchema = z$2.object({
 const awsPlugin = () => {
     const plugin = definePlugin({
         ns: 'aws',
-        configSchema: AwsPluginConfigSchema,
-        setup: (cli) => {
-            // Mount: aws (provided)
-            cli
-                .description('Establish an AWS session and optionally forward to the AWS CLI')
-                .enablePositionalOptions()
-                .passThroughOptions()
-                .allowUnknownOption(true)
-                // Boolean toggles with dynamic help labels (effective defaults)
-                .addOption(plugin.createPluginDynamicOption(cli, '--login-on-demand', (_bag, cfg) => `attempt aws sso login on-demand${cfg.loginOnDemand ? ' (default)' : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--no-login-on-demand', (_bag, cfg) => `disable sso login on-demand${cfg.loginOnDemand === false ? ' (default)' : ''}`))
-                // Strings / enums
-                .addOption(plugin.createPluginDynamicOption(cli, '--profile <string>', (_bag, cfg) => `AWS profile name${cfg.profile ? ` (default: ${JSON.stringify(cfg.profile)})` : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--region <string>', (_bag, cfg) => `AWS region${cfg.region ? ` (default: ${JSON.stringify(cfg.region)})` : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--default-region <string>', (_bag, cfg) => `fallback region${cfg.defaultRegion ? ` (default: ${JSON.stringify(cfg.defaultRegion)})` : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--strategy <string>', (_bag, cfg) => `credential acquisition strategy: cli-export|none${cfg.strategy ? ` (default: ${JSON.stringify(cfg.strategy)})` : ''}`))
-                // Advanced key overrides
-                .addOption(plugin.createPluginDynamicOption(cli, '--profile-key <string>', (_bag, cfg) => `dotenv/config key for local profile${cfg.profileKey ? ` (default: ${JSON.stringify(cfg.profileKey)})` : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--profile-fallback-key <string>', (_bag, cfg) => `fallback dotenv/config key for profile${cfg.profileFallbackKey ? ` (default: ${JSON.stringify(cfg.profileFallbackKey)})` : ''}`))
-                .addOption(plugin.createPluginDynamicOption(cli, '--region-key <string>', (_bag, cfg) => `dotenv/config key for region${cfg.regionKey ? ` (default: ${JSON.stringify(cfg.regionKey)})` : ''}`))
-                // Accept any extra operands so Commander does not error when tokens appear after "--".
-                .argument('[args...]')
-                .action(async (args, opts, thisCommand) => {
-                const pluginInst = plugin;
-                // Access merged root CLI options (installed by passOptions())
-                const bag = readMergedOptions(thisCommand);
-                const capture = shouldCapture(bag.capture);
-                const underTests = process.env.GETDOTENV_TEST === '1' ||
-                    typeof process.env.VITEST_WORKER_ID === 'string';
-                // Build overlay cfg from subcommand flags layered over discovered config.
-                const ctx = cli.getCtx();
-                const cfgBase = pluginInst.readConfig(cli);
-                const o = opts;
-                const overlay = {};
-                // Map boolean toggles (respect explicit --no-*)
-                if (Object.prototype.hasOwnProperty.call(o, 'loginOnDemand'))
-                    overlay.loginOnDemand = Boolean(o.loginOnDemand);
-                // Strings/enums
-                if (typeof o.profile === 'string')
-                    overlay.profile = o.profile;
-                if (typeof o.region === 'string')
-                    overlay.region = o.region;
-                if (typeof o.defaultRegion === 'string')
-                    overlay.defaultRegion = o.defaultRegion;
-                if (typeof o.strategy === 'string')
-                    overlay.strategy = o.strategy;
-                // Advanced key overrides
-                if (typeof o.profileKey === 'string')
-                    overlay.profileKey = o.profileKey;
-                if (typeof o.profileFallbackKey === 'string')
-                    overlay.profileFallbackKey = o.profileFallbackKey;
-                if (typeof o.regionKey === 'string')
-                    overlay.regionKey = o.regionKey;
-                const cfg = {
-                    ...cfgBase,
-                    ...overlay,
-                };
-                // Resolve current context with overrides
-                const out = await resolveAwsContext({
-                    dotenv: ctx.dotenv,
-                    cfg,
-                });
-                // Publish env/context
-                applyAwsContext(out, ctx, true);
-                // Forward when positional args are present; otherwise session-only.
-                if (Array.isArray(args) && args.length > 0) {
-                    const argv = ['aws', ...args];
-                    const shellSetting = resolveShell(bag.scripts, 'aws', bag.shell);
-                    const exit = await runCommand(argv, shellSetting, {
-                        env: buildSpawnEnv(process.env, ctx.dotenv),
-                        stdio: capture ? 'pipe' : 'inherit',
-                    });
-                    // Deterministic termination (suppressed under tests)
-                    if (!underTests) {
-                        process.exit(typeof exit === 'number' ? exit : 0);
-                    }
-                    return;
-                }
-                else {
-                    // Session only: low-noise breadcrumb under debug
-                    if (process.env.GETDOTENV_DEBUG) {
-                        try {
-                            const msg = JSON.stringify({
-                                profile: out.profile,
-                                region: out.region,
-                                hasCreds: Boolean(out.credentials),
-                            });
-                            process.stderr.write(`[aws] session established ${msg}\n`);
-                        }
-                        catch {
-                            /* ignore */
-                        }
-                    }
-                    if (!underTests)
-                        process.exit(0);
-                    return;
-                }
-            });
+        configSchema: awsPluginConfigSchema,
+        setup(cli) {
+            cli.description('Establish an AWS session and optionally forward to the AWS CLI');
+            const awsCmd = attachAwsOptions(cli, plugin);
+            attachAwsPreSubcommandHook(cli, plugin);
+            attachAwsDefaultAction(cli, plugin, awsCmd);
             return undefined;
         },
-        afterResolve: async (_cli, ctx) => {
-            const cfg = plugin.readConfig(_cli);
-            const out = await resolveAwsContext({
-                dotenv: ctx.dotenv,
-                cfg,
-            });
-            applyAwsContext(out, ctx, true);
-            // Optional: low-noise breadcrumb for diagnostics
-            if (process.env.GETDOTENV_DEBUG) {
-                try {
-                    const msg = JSON.stringify({
-                        profile: out.profile,
-                        region: out.region,
-                        hasCreds: Boolean(out.credentials),
-                    });
-                    process.stderr.write(`[aws] afterResolve ${msg}\n`);
-                }
-                catch {
-                    /* ignore */
-                }
-            }
-        },
     });
+    plugin.afterResolve = attachAwsAfterResolveHook(plugin);
     return plugin;
 };
 
@@ -13799,21 +14003,78 @@ class GetCallerIdentityCommand extends Command
 }
 
 /**
- * AWS Whoami plugin: prints the current AWS caller identity (account, arn, userid).
- * Intended to be mounted under the `aws` plugin.
+ * Attach the default action for the `aws whoami` command.
+ *
+ * This behavior executes only when `aws whoami` is invoked without a subcommand.
+ *
+ * @param cli - The `whoami` command mount.
+ * @returns Nothing.
+ */
+function attachWhoamiDefaultAction(cli) {
+    cli.action(async () => {
+        // The AWS SDK default providers will read credentials from process.env,
+        // which the aws parent has already populated.
+        const client = new STSClient$1();
+        const result = await client.send(new GetCallerIdentityCommand());
+        console.log(JSON.stringify(result, null, 2));
+    });
+}
+
+/**
+ * Attach options/arguments for the `aws whoami` plugin mount.
+ *
+ * This subcommand currently takes no flags/args; this module exists to keep the
+ * wiring layout consistent across shipped plugins (options vs actions).
+ *
+ * Note: the plugin description is owned by `src/plugins/aws/whoami/index.ts` and
+ * must not be set here.
+ *
+ * @param cli - The `whoami` command mount under `aws`.
+ * @returns The same `cli` instance for chaining.
+ *
+ * @internal
+ */
+function attachWhoamiOptions(cli) {
+    return cli;
+}
+
+/**
+ * Attach the `really` subcommand under `aws whoami`.
+ *
+ * Reads `SECRET_IDENTITY` from the resolved get-dotenv context (`cli.getCtx().dotenv`).
+ *
+ * @param cli - The `whoami` command mount.
+ * @returns Nothing.
+ */
+function attachWhoamiReallyAction(cli) {
+    const really = cli
+        .ns('really')
+        .description('Print SECRET_IDENTITY from the resolved dotenv context');
+    really.action(() => {
+        const secretIdentity = really.getCtx().dotenv.SECRET_IDENTITY;
+        console.log(`Your secret identity is ${secretIdentity ?? 'still a secret'}.`);
+    });
+}
+
+/**
+ * AWS Whoami plugin factory.
+ *
+ * This plugin demonstrates a “bucket of subcommands” pattern:
+ * - Subcommand behavior is articulated in separate modules as `attach*` helpers.
+ * - Those helpers are not individually composable plugins; they are internal wiring for one plugin instance.
+ *
+ * @returns A plugin instance mounted at `aws whoami`.
  */
 const awsWhoamiPlugin = () => definePlugin({
     ns: 'whoami',
     setup(cli) {
-        cli
-            .description('Print AWS caller identity (uses parent aws session)')
-            .action(async () => {
-            // The AWS SDK default providers will read credentials from process.env,
-            // which the aws parent has already populated.
-            const client = new STSClient$1();
-            const result = await client.send(new GetCallerIdentityCommand());
-            console.log(JSON.stringify(result, null, 2));
-        });
+        cli.description('Print AWS caller identity (uses parent aws session)');
+        // Options/args (none today, but keep layout consistent with other plugins).
+        const whoami = attachWhoamiOptions(cli);
+        // Default behavior: `getdotenv aws whoami`
+        attachWhoamiDefaultAction(whoami);
+        // Subcommand behavior: `getdotenv aws whoami really`
+        attachWhoamiReallyAction(whoami);
         return undefined;
     },
 });
@@ -13921,7 +14182,7 @@ const execShellCommandBatch = async ({ command, getDotenvCliOptions, dotenvEnv,
 /**
  * Attach the default "cmd" subcommand action with contextual typing.
  */
-const attachDefaultCmdAction$1 = (plugin, cli, batchCmd, pluginOpts, cmd) => {
+const attachBatchCmdAction = (plugin, cli, batchCmd, pluginOpts, cmd) => {
     cmd.action(async (commandParts, _subOpts, thisCommand) => {
         const mergedBag = readMergedOptions(batchCmd);
         const logger = mergedBag.logger;
@@ -14030,11 +14291,37 @@ const attachDefaultCmdAction$1 = (plugin, cli, batchCmd, pluginOpts, cmd) => {
     });
 };
 
+/**
+ * Attach the default `cmd` subcommand under the `batch` command.
+ *
+ * This encapsulates:
+ * - Subcommand construction (`new Command().name('cmd')…`)
+ * - Action wiring
+ * - Mounting as the default subcommand for `batch`
+ *
+ * @param plugin - The batch plugin instance.
+ * @param cli - The batch command mount.
+ * @param batchCmd - The `batch` command (same as `cli` mount).
+ * @param pluginOpts - Batch plugin factory options.
+ *
+ * @internal
+ */
+const attachBatchCmdSubcommand = (plugin, cli, batchCmd, pluginOpts) => {
+    const cmdSub = new Command$1()
+        .name('cmd')
+        .description('execute command, conflicts with --command option (default subcommand)')
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .argument('[command...]');
+    attachBatchCmdAction(plugin, cli, batchCmd, pluginOpts, cmdSub);
+    batchCmd.addCommand(cmdSub, { isDefault: true });
+};
+
 /**
  * Attach the parent-level action for the batch plugin.
  * Handles parent flags (e.g. `getdotenv batch -l`) and delegates to the batch executor.
  */
-const attachParentInvoker$1 = (plugin, cli, pluginOpts, parent) => {
+const attachBatchDefaultAction = (plugin, cli, pluginOpts, parent) => {
     parent.action(async function (...args) {
         // Commander Unknown generics: [...unknown[], OptionValues, thisCommand]
         const thisCommand = args[args.length - 1];
@@ -14135,6 +14422,45 @@ const attachParentInvoker$1 = (plugin, cli, pluginOpts, parent) => {
     });
 };
 
+/**
+ * Attach options/arguments for the batch plugin mount.
+ *
+ * Note: the plugin description is owned by `src/plugins/batch/index.ts` and
+ * must not be set here.
+ *
+ * @param plugin - Batch plugin instance (for dynamic option descriptions).
+ * @param cli - The `batch` command mount.
+ * @returns The same `cli` instance for chaining.
+ *
+ * @internal
+ */
+function attachBatchOptions(plugin, cli) {
+    const GROUP = `plugin:${cli.name()}`;
+    return (cli
+        .enablePositionalOptions()
+        .passThroughOptions()
+        // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
+        .addOption((() => {
+        const opt = plugin.createPluginDynamicOption(cli, '-p, --pkg-cwd', (_bag, cfg) => `use nearest package directory as current working directory${cfg.pkgCwd ? ' (default)' : ''}`);
+        cli.setOptionGroup(opt, GROUP);
+        return opt;
+    })())
+        .addOption((() => {
+        const opt = plugin.createPluginDynamicOption(cli, '-r, --root-path <string>', (_bag, cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.rootPath || './')})`);
+        cli.setOptionGroup(opt, GROUP);
+        return opt;
+    })())
+        .addOption((() => {
+        const opt = plugin.createPluginDynamicOption(cli, '-g, --globs <string>', (_bag, cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.globs || '*')})`);
+        cli.setOptionGroup(opt, GROUP);
+        return opt;
+    })())
+        .option('-c, --command <string>', 'command executed according to the base shell resolution')
+        .option('-l, --list', 'list working directories without executing command')
+        .option('-e, --ignore-errors', 'ignore errors and continue with next path')
+        .argument('[command...]'));
+}
+
 /**
  * Zod schema for a single script entry (string or object).
  */
@@ -14148,7 +14474,7 @@ const ScriptSchema = z$2.union([
 /**
  * Zod schema for batch plugin configuration.
  */
-const BatchConfigSchema = z$2.object({
+const batchPluginConfigSchema = z$2.object({
     scripts: z$2.record(z$2.string(), ScriptSchema).optional(),
     shell: z$2.union([z$2.string(), z$2.boolean()]).optional(),
     rootPath: z$2.string().optional(),
@@ -14174,45 +14500,15 @@ const batchPlugin = (opts = {}) => {
         ns: 'batch',
         // Host validates this when config-loader is enabled; plugins may also
         // re-validate at action time as a safety belt.
-        configSchema: BatchConfigSchema,
+        configSchema: batchPluginConfigSchema,
         setup(cli) {
             const batchCmd = cli; // mount provided by host
-            const GROUP = `plugin:${cli.name()}`;
-            batchCmd
-                .description('Batch command execution across multiple working directories.')
-                .enablePositionalOptions()
-                .passThroughOptions()
-                // Dynamic help: show effective defaults from the merged/interpolated plugin config slice.
-                .addOption((() => {
-                const opt = plugin.createPluginDynamicOption(cli, '-p, --pkg-cwd', (_bag, cfg) => `use nearest package directory as current working directory${cfg.pkgCwd ? ' (default)' : ''}`);
-                cli.setOptionGroup(opt, GROUP);
-                return opt;
-            })())
-                .addOption((() => {
-                const opt = plugin.createPluginDynamicOption(cli, '-r, --root-path <string>', (_bag, cfg) => `path to batch root directory from current working directory (default: ${JSON.stringify(cfg.rootPath || './')})`);
-                cli.setOptionGroup(opt, GROUP);
-                return opt;
-            })())
-                .addOption((() => {
-                const opt = plugin.createPluginDynamicOption(cli, '-g, --globs <string>', (_bag, cfg) => `space-delimited globs from root path (default: ${JSON.stringify(cfg.globs || '*')})`);
-                cli.setOptionGroup(opt, GROUP);
-                return opt;
-            })())
-                .option('-c, --command <string>', 'command executed according to the base shell resolution')
-                .option('-l, --list', 'list working directories without executing command')
-                .option('-e, --ignore-errors', 'ignore errors and continue with next path')
-                .argument('[command...]');
-            // Default subcommand "cmd" with contextual typing for args/opts
-            const cmdSub = new Command$1()
-                .name('cmd')
-                .description('execute command, conflicts with --command option (default subcommand)')
-                .enablePositionalOptions()
-                .passThroughOptions()
-                .argument('[command...]');
-            attachDefaultCmdAction$1(plugin, cli, batchCmd, opts, cmdSub);
-            batchCmd.addCommand(cmdSub, { isDefault: true });
-            // Parent invoker (unified naming)
-            attachParentInvoker$1(plugin, cli, opts, batchCmd);
+            batchCmd.description('Batch command execution across multiple working directories.');
+            attachBatchOptions(plugin, batchCmd);
+            // Default subcommand `cmd` (mounted as batch default subcommand)
+            attachBatchCmdSubcommand(plugin, cli, batchCmd, opts);
+            // Default action for the batch command mount (parent flags and positional form)
+            attachBatchDefaultAction(plugin, cli, opts, batchCmd);
             return undefined;
         },
     });
@@ -14306,14 +14602,11 @@ async function runCmdWithContext(cli, merged, command, _opts) {
 }
 
 /**
- * Attach the default "cmd" subcommand action (unified name).
+ * Attach the default "cmd" subcommand action.
  * Mirrors the prior inline implementation in cmd/index.ts.
  */
-const attachDefaultCmdAction = (cli, cmd, aliasKey) => {
-    cmd
-        .enablePositionalOptions()
-        .passThroughOptions()
-        .action(async function (...allArgs) {
+const attachCmdDefaultAction = (cli, cmd, aliasKey) => {
+    cmd.action(async function (...allArgs) {
         // Commander passes: [...positionals, options, thisCommand]
         const thisCommand = allArgs[allArgs.length - 1];
         const commandParts = allArgs[0];
@@ -14346,11 +14639,29 @@ const attachDefaultCmdAction = (cli, cmd, aliasKey) => {
     });
 };
 
+/**
+ * Attach options/arguments for the cmd plugin mount.
+ *
+ * Note: the plugin description is owned by `src/plugins/cmd/index.ts` and must
+ * not be set here.
+ *
+ * @param cli - The `cmd` command mount.
+ * @returns The same `cli` instance for chaining.
+ *
+ * @internal
+ */
+function attachCmdOptions(cli) {
+    return cli
+        .enablePositionalOptions()
+        .passThroughOptions()
+        .argument('[command...]');
+}
+
 /**
  * Install the parent-level invoker (alias) for the cmd plugin.
  * Unifies naming with batch attachParentInvoker; behavior unchanged.
  */
-const attachParentInvoker = (cli, options, _cmd, plugin) => {
+const attachCmdParentInvoker = (cli, options, plugin) => {
     const dbg = (...args) => {
         if (process.env.GETDOTENV_DEBUG) {
             try {
@@ -14461,7 +14772,7 @@ const attachParentInvoker = (cli, options, _cmd, plugin) => {
 /**
  * Zod schema for cmd plugin configuration.
  */
-const CmdConfigSchema = z$2
+const cmdPluginConfigSchema = z$2
     .object({
     expand: z$2.boolean().optional(),
 })
@@ -14481,7 +14792,7 @@ const CmdConfigSchema = z$2
 const cmdPlugin = (options = {}) => {
     const plugin = definePlugin({
         ns: 'cmd',
-        configSchema: CmdConfigSchema,
+        configSchema: cmdPluginConfigSchema,
         setup(cli) {
             const aliasSpec = typeof options.optionAlias === 'string'
                 ? { flags: options.optionAlias}
@@ -14493,14 +14804,13 @@ const cmdPlugin = (options = {}) => {
             };
             const aliasKey = aliasSpec ? deriveKey(aliasSpec.flags) : undefined;
             // Mount is the command ('cmd'); attach default action.
-            cli
-                .description('Execute command according to the --shell option, conflicts with --command option (default subcommand)')
-                // Accept payload tokens as positional arguments for the default subcommand.
-                .argument('[command...]');
-            attachDefaultCmdAction(cli, cli, aliasKey);
+            cli.description('Execute command according to the --shell option, conflicts with --command option (default subcommand)');
+            // Options/arguments (positional payload, argv routing) are attached separately.
+            attachCmdOptions(cli);
+            attachCmdDefaultAction(cli, cli, aliasKey);
             // Parent-attached option alias (optional, unified naming).
             if (aliasSpec !== undefined) {
-                attachParentInvoker(cli, options, cli, plugin);
+                attachCmdParentInvoker(cli, options, plugin);
             }
             return undefined;
         },
@@ -14509,14 +14819,21 @@ const cmdPlugin = (options = {}) => {
 };
 
 /**
- * Ensure a directory exists.
+ * Ensure a directory exists (parents included).
+ *
+ * @param p - Directory path to create.
+ * @returns A `Promise\<string\>` resolving to the provided `p` value.
  */
 const ensureDir = async (p) => {
     await fs.ensureDir(p);
     return p;
 };
 /**
- * Write text content to a file, ensuring the parent directory exists.
+ * Write UTF-8 text content to a file, ensuring the parent directory exists.
+ *
+ * @param dest - Destination file path.
+ * @param data - File contents to write.
+ * @returns A `Promise\<void\>` which resolves when the file is written.
  */
 const writeFile$1 = async (dest, data) => {
     await ensureDir(path.dirname(dest));
@@ -14528,6 +14845,7 @@ const writeFile$1 = async (dest, data) => {
  * @param src - Source file path.
  * @param dest - Destination file path.
  * @param substitutions - Map of token literals to replacement strings.
+ * @returns A `Promise\<void\>` which resolves when the file has been copied.
  */
 const copyTextFile = async (src, dest, substitutions) => {
     const contents = await fs.readFile(src, 'utf-8');
@@ -14539,6 +14857,10 @@ const copyTextFile = async (src, dest, substitutions) => {
 /**
  * Ensure a set of lines exist (exact match) in a file. Creates the file
  * when missing. Returns whether it was created or changed.
+ *
+ * @param filePath - Target file path to create/update.
+ * @param lines - Lines which must be present (exact string match).
+ * @returns A `Promise\<object\>` describing whether the file was created and/or changed.
  */
 const ensureLines = async (filePath, lines) => {
     const exists = await fs.pathExists(filePath);
@@ -14566,11 +14888,23 @@ const ensureLines = async (filePath, lines) => {
     return { created: false, changed: false };
 };
 
-// Templates root used by the scaffolder
+/**
+ * Absolute path to the shipped templates directory.
+ *
+ * Used by the init scaffolder to locate files under `templates/` at runtime.
+ *
+ * @remarks
+ * This path is resolved relative to the current working directory. It assumes
+ * the `templates/` folder is present alongside the installed package (or in the
+ * repository when running from source).
+ */
 const TEMPLATES_ROOT = path.resolve('templates');
 
 /**
  * Plan the copy operations for configuration files.
+ *
+ * @param options - Planning options for config scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planConfigCopies = ({ format, withLocal, destRoot, }) => {
     const copies = [];
@@ -14614,10 +14948,14 @@ const planConfigCopies = ({ format, withLocal, destRoot, }) => {
 };
 /**
  * Plan the copy operations for the CLI skeleton.
+ *
+ * @param options - Planning options for CLI scaffolding.
+ * @returns An array of copy operations to perform.
  */
 const planCliCopies = ({ cliName, destRoot, }) => {
     const subs = { __CLI_NAME__: cliName };
     const base = path.join(destRoot, 'src', 'cli', cliName);
+    const helloBase = path.join(base, 'plugins', 'hello');
     return [
         {
             src: path.join(TEMPLATES_ROOT, 'cli', 'index.ts'),
@@ -14625,8 +14963,28 @@ const planCliCopies = ({ cliName, destRoot, }) => {
             subs,
         },
         {
-            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello.ts'),
-            dest: path.join(base, 'plugins', 'hello.ts'),
+            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello', 'index.ts'),
+            dest: path.join(helloBase, 'index.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello', 'options.ts'),
+            dest: path.join(helloBase, 'options.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello', 'defaultAction.ts'),
+            dest: path.join(helloBase, 'defaultAction.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello', 'strangerAction.ts'),
+            dest: path.join(helloBase, 'strangerAction.ts'),
+            subs,
+        },
+        {
+            src: path.join(TEMPLATES_ROOT, 'cli', 'plugins', 'hello', 'types.ts'),
+            dest: path.join(helloBase, 'types.ts'),
             subs,
         },
     ];
@@ -14635,6 +14993,8 @@ const planCliCopies = ({ cliName, destRoot, }) => {
 /**
  * Determine whether the current environment should be treated as non-interactive.
  * CI heuristics include: CI, GITHUB_ACTIONS, BUILDKITE, TEAMCITY_VERSION, TF_BUILD.
+ *
+ * @returns `true` when running in a CI-like environment or when stdin/stdout are not TTYs.
  */
 const isNonInteractive = () => {
     const ciLike = process.env.CI ||
@@ -14647,6 +15007,11 @@ const isNonInteractive = () => {
 /**
  * Prompt the user for a file collision decision.
  * Returns a single-character code representing overwrite/example/skip (or 'all' variants).
+ *
+ * @param filePath - Path of the colliding file (for display).
+ * @param logger - Logger used for user-facing messages.
+ * @param rl - Readline interface used to capture user input.
+ * @returns A single-character decision code.
  */
 const promptDecision = async (filePath, logger, rl) => {
     logger.log(`File exists: ${filePath}\nChoose: [o]verwrite, [e]xample, [s]kip, [O]verwrite All, [E]xample All, [S]kip All`);
@@ -14661,129 +15026,148 @@ const promptDecision = async (filePath, logger, rl) => {
 };
 
 /**
- * @packageDocumentation
- * Init plugin subpath. Scaffolds get‑dotenv configuration files and a simple
- * host‑based CLI skeleton with collision handling and CI‑safe defaults.
- */
-/**
- * Init plugin: scaffolds configuration files and a CLI skeleton for get-dotenv.
- * Supports collision detection, interactive prompts, and CI bypass.
+ * Attach the init plugin default action.
+ *
+ * @param cli - The `init` command mount (with args/options attached).
+ *
+ * @internal
  */
-const initPlugin = () => definePlugin({
-    ns: 'init',
-    setup(cli) {
-        cli
-            .description('Scaffold getdotenv config files and a host-based CLI skeleton.')
-            .argument('[dest]', 'destination path (default: ./)', '.')
-            .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
-            .option('--with-local', 'include .local config variant')
-            .option('--dynamic', 'include dynamic examples (JS/TS configs)')
-            .option('--cli-name <string>', 'CLI name for skeleton and tokens')
-            .option('--force', 'overwrite all existing files')
-            .option('--yes', 'skip all collisions (no overwrite)')
-            .action(async (destArg, opts, thisCommand) => {
-            // Inherit logger from merged root options (base).
-            const bag = readMergedOptions(thisCommand);
-            const logger = bag.logger;
-            const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
-            const cwd = process.cwd();
-            const destRoot = path.resolve(cwd, destRel);
-            const formatInput = opts.configFormat;
-            const formatRaw = typeof formatInput === 'string'
-                ? formatInput.toLowerCase()
-                : 'json';
-            const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw)
-                ? formatRaw
-                : 'json');
-            const withLocal = !!opts.withLocal;
-            // dynamic flag reserved for future template variants; present for UX compatibility
-            void opts.dynamic;
-            // CLI name default: --cli-name | basename(dest) | 'mycli'
-            const cliName = (typeof opts.cliName === 'string' && opts.cliName.length > 0
-                ? opts.cliName
-                : path.basename(destRoot) || 'mycli') || 'mycli';
-            // Precedence: --force > --yes > auto-detect(non-interactive => yes)
-            const force = !!opts.force;
-            const yes = !!opts.yes || (!force && isNonInteractive());
-            // Build copy plan
-            const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
-            const cliCopies = planCliCopies({ cliName, destRoot });
-            const copies = [...cfgCopies, ...cliCopies];
-            // Interactive state
-            let globalDecision;
-            const rl = createInterface({ input: stdin, output: stdout });
-            try {
-                for (const item of copies) {
-                    const exists = await fs.pathExists(item.dest);
-                    if (!exists) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Created ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    // Collision
-                    if (force) {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    if (yes) {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
-                        continue;
-                    }
-                    let decision = globalDecision;
-                    if (!decision) {
-                        const a = await promptDecision(item.dest, logger, rl);
-                        if (a === 'O') {
-                            globalDecision = 'overwrite';
-                            decision = 'overwrite';
-                        }
-                        else if (a === 'E') {
-                            globalDecision = 'example';
-                            decision = 'example';
-                        }
-                        else if (a === 'S') {
-                            globalDecision = 'skip';
-                            decision = 'skip';
-                        }
-                        else {
-                            decision =
-                                a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
-                        }
+function attachInitDefaultAction(cli) {
+    cli.action(async (destArg, opts, thisCommand) => {
+        // Inherit logger from merged root options (base).
+        const bag = readMergedOptions(thisCommand);
+        const logger = bag.logger;
+        const destRel = typeof destArg === 'string' && destArg.length > 0 ? destArg : '.';
+        const cwd = process.cwd();
+        const destRoot = path.resolve(cwd, destRel);
+        const formatInput = opts['configFormat'];
+        const formatRaw = typeof formatInput === 'string' ? formatInput.toLowerCase() : 'json';
+        const format = (['json', 'yaml', 'js', 'ts'].includes(formatRaw) ? formatRaw : 'json');
+        const withLocal = Boolean(opts['withLocal']);
+        // dynamic flag reserved for future template variants; present for UX compatibility
+        void opts['dynamic'];
+        // CLI name default: --cli-name | basename(dest) | 'mycli'
+        const cliNameInput = opts['cliName'];
+        const cliName = (typeof cliNameInput === 'string' && cliNameInput.length > 0
+            ? cliNameInput
+            : path.basename(destRoot) || 'mycli') || 'mycli';
+        // Precedence: --force > --yes > auto-detect(non-interactive => yes)
+        const force = Boolean(opts['force']);
+        const yes = Boolean(opts['yes']) || (!force && isNonInteractive());
+        // Build copy plan
+        const cfgCopies = planConfigCopies({ format, withLocal, destRoot });
+        const cliCopies = planCliCopies({ cliName, destRoot });
+        const copies = [...cfgCopies, ...cliCopies];
+        // Interactive state
+        let globalDecision;
+        const rl = createInterface({ input: stdin, output: stdout });
+        try {
+            for (const item of copies) {
+                const exists = await fs.pathExists(item.dest);
+                if (!exists) {
+                    const subs = item.subs ?? {};
+                    await copyTextFile(item.src, item.dest, subs);
+                    logger.log(`Created ${path.relative(cwd, item.dest)}`);
+                    continue;
+                }
+                // Collision
+                if (force) {
+                    const subs = item.subs ?? {};
+                    await copyTextFile(item.src, item.dest, subs);
+                    logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                    continue;
+                }
+                if (yes) {
+                    logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                    continue;
+                }
+                let decision = globalDecision;
+                if (!decision) {
+                    const a = await promptDecision(item.dest, logger, rl);
+                    if (a === 'O') {
+                        globalDecision = 'overwrite';
+                        decision = 'overwrite';
                     }
-                    if (decision === 'overwrite') {
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, item.dest, subs);
-                        logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
+                    else if (a === 'E') {
+                        globalDecision = 'example';
+                        decision = 'example';
                     }
-                    else if (decision === 'example') {
-                        const destEx = `${item.dest}.example`;
-                        const subs = item.subs ?? {};
-                        await copyTextFile(item.src, destEx, subs);
-                        logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
+                    else if (a === 'S') {
+                        globalDecision = 'skip';
+                        decision = 'skip';
                     }
                     else {
-                        logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
+                        decision = a === 'o' ? 'overwrite' : a === 'e' ? 'example' : 'skip';
                     }
                 }
-                // Ensure .gitignore includes local config patterns.
-                const giPath = path.join(destRoot, '.gitignore');
-                const { created, changed } = await ensureLines(giPath, [
-                    'getdotenv.config.local.*',
-                    '*.local',
-                ]);
-                if (created) {
-                    logger.log(`Created ${path.relative(cwd, giPath)}`);
+                if (decision === 'overwrite') {
+                    const subs = item.subs ?? {};
+                    await copyTextFile(item.src, item.dest, subs);
+                    logger.log(`Overwrote ${path.relative(cwd, item.dest)}`);
                 }
-                else if (changed) {
-                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
+                else if (decision === 'example') {
+                    const destEx = `${item.dest}.example`;
+                    const subs = item.subs ?? {};
+                    await copyTextFile(item.src, destEx, subs);
+                    logger.log(`Wrote example ${path.relative(cwd, destEx)}`);
+                }
+                else {
+                    logger.log(`Skipped ${path.relative(cwd, item.dest)}`);
                 }
             }
-            finally {
-                rl.close();
+            // Ensure .gitignore includes local config patterns.
+            const giPath = path.join(destRoot, '.gitignore');
+            const { created, changed } = await ensureLines(giPath, [
+                'getdotenv.config.local.*',
+                '*.local',
+            ]);
+            if (created) {
+                logger.log(`Created ${path.relative(cwd, giPath)}`);
             }
-        });
+            else if (changed) {
+                logger.log(`Updated ${path.relative(cwd, giPath)}`);
+            }
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+
+/**
+ * Attach options/arguments for the init plugin mount.
+ *
+ * @param cli - The `init` command mount.
+ *
+ * @internal
+ */
+function attachInitOptions(cli) {
+    return (cli
+        // Description is owned by the plugin index (src/plugins/init/index.ts).
+        .argument('[dest]', 'destination path (default: ./)', '.')
+        .option('--config-format <format>', 'config format: json|yaml|js|ts', 'json')
+        .option('--with-local', 'include .local config variant')
+        .option('--dynamic', 'include dynamic examples (JS/TS configs)')
+        .option('--cli-name <string>', 'CLI name for skeleton and tokens')
+        .option('--force', 'overwrite all existing files')
+        .option('--yes', 'skip all collisions (no overwrite)'));
+}
+
+/**
+ * @packageDocumentation
+ * Init plugin subpath. Scaffolds get‑dotenv configuration files and a simple
+ * host‑based CLI skeleton with collision handling and CI‑safe defaults.
+ */
+/**
+ * Init plugin: scaffolds configuration files and a CLI skeleton for get-dotenv.
+ * Supports collision detection, interactive prompts, and CI bypass.
+ */
+const initPlugin = () => definePlugin({
+    ns: 'init',
+    setup(cli) {
+        cli.description('Scaffold getdotenv config files and a host-based CLI skeleton.');
+        const initCmd = attachInitOptions(cli);
+        attachInitDefaultAction(initCmd);
         return undefined;
     },
 });