@karmaniverous/get-dotenv 6.0.0 → 6.1.1

package/dist/plugins-aws.mjs

@@ -151,6 +151,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.
@@ -386,14 +390,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:
  *
- * @param absPath - absolute path to source file
- * @param cacheDirName - cache subfolder under .tsbuild
+ * - `.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.
+ *
+ * @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();
@@ -465,6 +475,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 = {};
@@ -476,6 +490,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 = {};
@@ -690,6 +708,11 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
  * 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)
@@ -709,6 +732,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)))
@@ -1799,6 +1828,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);
@@ -2395,23 +2428,57 @@ const buildSpawnEnv = (base, overlay) => {
  * 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
@@ -2422,7 +2489,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('"')) ||
@@ -2431,6 +2498,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 {
@@ -2454,6 +2524,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/);
@@ -2464,12 +2538,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];
@@ -2494,7 +2573,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,
@@ -2509,36 +2588,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';
@@ -2563,31 +2656,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);
             }
         }
@@ -2605,6 +2694,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);
@@ -2620,10 +2722,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.object({
+const awsPluginConfigSchema = z.object({
     profile: z.string().optional(),
     region: z.string().optional(),
     defaultRegion: z.string().optional(),
@@ -2647,129 +2952,16 @@ const AwsPluginConfigSchema = z.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;
 };