@karmaniverous/get-dotenv 6.1.0 → 6.2.0

package/dist/plugins-aws.mjs

@@ -20,26 +20,58 @@ import { Option, Command } from '@commander-js/extra-typings';
  * Minimal process env representation used by options and helpers.
  * Values may be `undefined` to indicate "unset".
  */
+/**
+ * Schema for an env-like record.
+ *
+ * Keys are environment variable names and values are either strings or `undefined`
+ * (to represent “unset”).
+ *
+ * @public
+ */
 const processEnvSchema = z.record(z.string(), z.string().optional());
 // RAW: all fields optional — undefined means "inherit" from lower layers.
+/**
+ * Programmatic options schema (raw).
+ *
+ * This schema is the canonical runtime source of truth for the `getDotenv()` programmatic API.
+ * All fields are optional; `undefined` generally means “inherit default/lower layer”.
+ *
+ * @public
+ */
 const getDotenvOptionsSchemaRaw = z.object({
+    /** Default environment name when `env` is not provided. */
     defaultEnv: z.string().optional(),
+    /** Base dotenv filename token (default `.env`). */
     dotenvToken: z.string().optional(),
+    /** Path to a dynamic variables module (JS/TS) to load and apply. */
     dynamicPath: z.string().optional(),
-    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    /** Dynamic map is intentionally wide for now; refine once sources are normalized. */
     dynamic: z.record(z.string(), z.unknown()).optional(),
+    /** Selected environment name for this invocation (for env-scoped files and overlays). */
     env: z.string().optional(),
+    /** When true, skip applying dynamic variables. */
     excludeDynamic: z.boolean().optional(),
+    /** When true, skip environment-scoped dotenv files. */
     excludeEnv: z.boolean().optional(),
+    /** When true, skip global dotenv files. */
     excludeGlobal: z.boolean().optional(),
+    /** When true, skip private dotenv files. */
     excludePrivate: z.boolean().optional(),
+    /** When true, skip public dotenv files. */
     excludePublic: z.boolean().optional(),
+    /** When true, merge the final composed environment into `process.env`. */
     loadProcess: z.boolean().optional(),
+    /** When true, log the final environment map via `logger`. */
     log: z.boolean().optional(),
+    /** Logger used when `log` is enabled (console-compatible). */
     logger: z.unknown().default(console),
+    /** Optional output dotenv file path to write after composition. */
     outputPath: z.string().optional(),
+    /** Dotenv search paths (ordered). */
     paths: z.array(z.string()).optional(),
+    /** Private token suffix for private dotenv files (default `local`). */
     privateToken: z.string().optional(),
+    /** Explicit variables to overlay onto the composed dotenv map. */
     vars: processEnvSchema.optional(),
 });
 /**
@@ -47,6 +79,14 @@ const getDotenvOptionsSchemaRaw = z.object({
  * For now, this mirrors the RAW schema; future stages may materialize defaults
  * and narrow shapes as resolution is wired into the host.
  */
+/**
+ * Programmatic options schema (resolved).
+ *
+ * Today this mirrors {@link getDotenvOptionsSchemaRaw}, but is kept as a distinct export
+ * so future resolution steps can narrow or materialize defaults without breaking the API.
+ *
+ * @public
+ */
 const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
 
 /**
@@ -56,27 +96,55 @@ const getDotenvOptionsSchemaResolved = getDotenvOptionsSchemaRaw;
  * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
  * CLI resolution pipeline.
  */
+/**
+ * CLI options schema (raw).
+ *
+ * Extends the programmatic options schema with CLI-only flags and stringly inputs
+ * which are normalized later by the host resolution pipeline.
+ *
+ * @public
+ */
 const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
     // CLI-specific fields (stringly inputs before preprocessing)
+    /** Enable verbose debug output (host-specific). */
     debug: z.boolean().optional(),
+    /** Fail on validation errors (schema/requiredKeys). */
     strict: z.boolean().optional(),
+    /** Capture child process stdio (useful for CI/tests). */
     capture: z.boolean().optional(),
+    /** Emit child env diagnostics (boolean or selected keys). */
     trace: z.union([z.boolean(), z.array(z.string())]).optional(),
+    /** Enable presentation-time redaction in trace/log output. */
     redact: z.boolean().optional(),
+    /** Enable entropy warnings in trace/log output. */
     warnEntropy: z.boolean().optional(),
+    /** Entropy threshold (bits/char) for warnings. */
     entropyThreshold: z.number().optional(),
+    /** Minimum value length to consider for entropy warnings. */
     entropyMinLength: z.number().optional(),
+    /** Regex patterns (strings) to suppress entropy warnings by key. */
     entropyWhitelist: z.array(z.string()).optional(),
+    /** Additional key-match patterns (strings) for redaction. */
     redactPatterns: z.array(z.string()).optional(),
+    /** Dotenv search paths provided as a single delimited string. */
     paths: z.string().optional(),
+    /** Delimiter string used to split `paths`. */
     pathsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
     pathsDelimiterPattern: z.string().optional(),
+    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
     scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Shell selection (`false` for shell-off, string for explicit shell). */
     shell: z.union([z.boolean(), z.string()]).optional(),
+    /** Extra variables expressed as a single delimited string of assignments. */
     vars: z.string().optional(),
+    /** Assignment operator used when parsing `vars`. */
     varsAssignor: z.string().optional(),
+    /** Regex pattern used as the assignment operator for `vars` parsing. */
     varsAssignorPattern: z.string().optional(),
+    /** Delimiter string used to split `vars`. */
     varsDelimiter: z.string().optional(),
+    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
     varsDelimiterPattern: z.string().optional(),
 });
 
@@ -100,17 +168,34 @@ const envStringMap = z.record(z.string(), stringMap);
  * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
  * Validates allowed top‑level keys without performing path normalization.
  */
+/**
+ * Config schema for discovered get-dotenv configuration documents (raw).
+ *
+ * This schema validates the allowed top-level keys for configuration files.
+ * It does not normalize paths or coerce types beyond Zod’s parsing.
+ *
+ * @public
+ */
 const getDotenvConfigSchemaRaw = z.object({
+    /** Root option defaults applied by the host (CLI-like, collapsed families). */
     rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
+    /** Help-time visibility map for root flags (false hides). */
     rootOptionVisibility: visibilityMap.optional(),
-    scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
+    scripts: z.record(z.string(), z.unknown()).optional(),
+    /** Keys required to be present in the final composed environment. */
     requiredKeys: z.array(z.string()).optional(),
+    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
     schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
+    /** Public global variables (string-only). */
     vars: stringMap.optional(), // public, global
+    /** Public per-environment variables (string-only). */
     envVars: envStringMap.optional(), // public, per-env
     // Dynamic in config (JS/TS only). JSON/YAML loader will reject if set.
+    /** Dynamic variable definitions (JS/TS only). */
     dynamic: z.unknown().optional(),
     // Per-plugin config bag; validated by plugins/host when used.
+    /** Per-plugin config slices keyed by realized mount path (for example, `aws/whoami`). */
     plugins: z.record(z.string(), z.unknown()).optional(),
 });
 /**
@@ -862,13 +947,21 @@ const redactObject = (obj, opts) => {
  * Base root CLI defaults (shared; kept untyped here to avoid cross-layer deps).
  * Used as the bottom layer for CLI option resolution.
  */
+const baseScripts = {
+    'git-status': {
+        cmd: 'git branch --show-current && git status -s -u',
+        shell: true,
+    },
+};
 /**
- * Default values for root CLI options used by the host and helpers as the
- * baseline layer during option resolution.
+ * Default values for root CLI options used by the host and helpers as the baseline layer during option resolution.
  *
- * These defaults correspond to the "stringly" root surface (see `RootOptionsShape`)
- * and are merged by precedence with create-time overrides and any discovered
- * configuration `rootOptionDefaults` before CLI flags are applied.
+ * These defaults correspond to the “stringly” root surface (see `RootOptionsShape`) and are merged by precedence with:
+ * - create-time overrides
+ * - any discovered configuration `rootOptionDefaults`
+ * - and finally CLI flags at runtime
+ *
+ * @public
  */
 const baseRootOptionDefaults = {
     dotenvToken: '.env',
@@ -882,12 +975,7 @@ const baseRootOptionDefaults = {
     paths: './',
     pathsDelimiter: ' ',
     privateToken: 'local',
-    scripts: {
-        'git-status': {
-            cmd: 'git branch --show-current && git status -s -u',
-            shell: true,
-        },
-    },
+    scripts: baseScripts,
     shell: true,
     vars: '',
     varsAssignor: '=',
@@ -1434,6 +1522,14 @@ async function _execNormalized(command, shell, opts = {}) {
         return out;
     }
 }
+/**
+ * Execute a command and capture stdout/stderr (buffered).
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/timeout).
+ * @returns A promise resolving to the captured result.
+ */
 async function runCommandResult(command, shell, opts = {}) {
     // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
     const coreOpts = { stdio: 'pipe' };
@@ -1448,6 +1544,14 @@ async function runCommandResult(command, shell, opts = {}) {
     }
     return _execNormalized(command, shell, coreOpts);
 }
+/**
+ * Execute a command and return its exit code.
+ *
+ * @param command - Command string (shell) or argv array (shell-off supported).
+ * @param shell - Shell setting (false for plain execution).
+ * @param opts - Execution options (cwd/env/stdio).
+ * @returns A promise resolving to the process exit code.
+ */
 async function runCommand(command, shell, opts) {
     // Build opts without injecting undefined (exactOptionalPropertyTypes-safe)
     const callOpts = {};
@@ -1907,6 +2011,16 @@ function evaluateDynamicOptions(root, resolved) {
     visit(root);
 }
 
+/**
+ * Initialize a {@link GetDotenvCli} instance with help configuration and safe defaults.
+ *
+ * @remarks
+ * This is a low-level initializer used by the host constructor to keep `GetDotenvCli.ts`
+ * small and to centralize help/output behavior.
+ *
+ * @param cli - The CLI instance to initialize.
+ * @param headerGetter - Callback returning an optional help header string.
+ */
 function initializeInstance(cli, headerGetter) {
     // Configure grouped help: show only base options in default "Options";
     // subcommands show all of their own options.
@@ -2436,18 +2550,49 @@ const buildSpawnEnv = (base, overlay) => {
 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
@@ -2458,7 +2603,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('"')) ||
@@ -2493,6 +2638,7 @@ 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.
@@ -2506,12 +2652,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];
@@ -2536,7 +2687,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,
@@ -2551,30 +2702,43 @@ 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.
@@ -2606,31 +2770,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);
             }
         }
@@ -2648,6 +2808,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);
@@ -2664,16 +2837,234 @@ const resolveAwsContext = async ({ dotenv, cfg, }) => {
 };
 
 /**
- * Zod schema for AWS plugin configuration.
+ * 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
  */
-const AwsPluginConfigSchema = z.object({
+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
+ */
+/** @hidden */
+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);
+    });
+}
+
+/**
+ * AWS plugin configuration schema.
+ *
+ * @remarks
+ * This Zod schema is used by the host to validate the `plugins.aws` config slice.
+ *
+ * @public
+ * @hidden
+ */
+const awsPluginConfigSchema = z.object({
+    /** Preferred AWS profile name (overrides dotenv-derived profile keys when set). */
     profile: z.string().optional(),
+    /** Preferred AWS region (overrides dotenv-derived region key when set). */
     region: z.string().optional(),
+    /** Fallback region when region cannot be resolved from config/dotenv/AWS CLI. */
     defaultRegion: z.string().optional(),
+    /** Dotenv/config key for local profile lookup (default `AWS_LOCAL_PROFILE`). */
     profileKey: z.string().default('AWS_LOCAL_PROFILE').optional(),
+    /** Dotenv/config fallback key for profile lookup (default `AWS_PROFILE`). */
     profileFallbackKey: z.string().default('AWS_PROFILE').optional(),
+    /** Dotenv/config key for region lookup (default `AWS_REGION`). */
     regionKey: z.string().default('AWS_REGION').optional(),
+    /** Credential acquisition strategy (`cli-export` to resolve via AWS CLI, or `none` to skip). */
     strategy: z.enum(['cli-export', 'none']).default('cli-export').optional(),
+    /** When true, attempt `aws sso login` on-demand when credential export fails for an SSO profile. */
     loginOnDemand: z.boolean().default(false).optional(),
 });
 
@@ -2690,129 +3081,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;
 };