@karmaniverous/get-dotenv 6.1.0 → 6.2.0

package/dist/cli.mjs

@@ -38,26 +38,58 @@ import { versions, env } from 'process';
  * 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$2.record(z$2.string(), z$2.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$2.object({
+    /** Default environment name when `env` is not provided. */
     defaultEnv: z$2.string().optional(),
+    /** Base dotenv filename token (default `.env`). */
     dotenvToken: z$2.string().optional(),
+    /** Path to a dynamic variables module (JS/TS) to load and apply. */
     dynamicPath: z$2.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$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Selected environment name for this invocation (for env-scoped files and overlays). */
     env: z$2.string().optional(),
+    /** When true, skip applying dynamic variables. */
     excludeDynamic: z$2.boolean().optional(),
+    /** When true, skip environment-scoped dotenv files. */
     excludeEnv: z$2.boolean().optional(),
+    /** When true, skip global dotenv files. */
     excludeGlobal: z$2.boolean().optional(),
+    /** When true, skip private dotenv files. */
     excludePrivate: z$2.boolean().optional(),
+    /** When true, skip public dotenv files. */
     excludePublic: z$2.boolean().optional(),
+    /** When true, merge the final composed environment into `process.env`. */
     loadProcess: z$2.boolean().optional(),
+    /** When true, log the final environment map via `logger`. */
     log: z$2.boolean().optional(),
+    /** Logger used when `log` is enabled (console-compatible). */
     logger: z$2.unknown().default(console),
+    /** Optional output dotenv file path to write after composition. */
     outputPath: z$2.string().optional(),
+    /** Dotenv search paths (ordered). */
     paths: z$2.array(z$2.string()).optional(),
+    /** Private token suffix for private dotenv files (default `local`). */
     privateToken: z$2.string().optional(),
+    /** Explicit variables to overlay onto the composed dotenv map. */
     vars: processEnvSchema.optional(),
 });
 /**
@@ -65,6 +97,14 @@ const getDotenvOptionsSchemaRaw = z$2.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;
 
 /**
@@ -74,27 +114,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$2.boolean().optional(),
+    /** Fail on validation errors (schema/requiredKeys). */
     strict: z$2.boolean().optional(),
+    /** Capture child process stdio (useful for CI/tests). */
     capture: z$2.boolean().optional(),
+    /** Emit child env diagnostics (boolean or selected keys). */
     trace: z$2.union([z$2.boolean(), z$2.array(z$2.string())]).optional(),
+    /** Enable presentation-time redaction in trace/log output. */
     redact: z$2.boolean().optional(),
+    /** Enable entropy warnings in trace/log output. */
     warnEntropy: z$2.boolean().optional(),
+    /** Entropy threshold (bits/char) for warnings. */
     entropyThreshold: z$2.number().optional(),
+    /** Minimum value length to consider for entropy warnings. */
     entropyMinLength: z$2.number().optional(),
+    /** Regex patterns (strings) to suppress entropy warnings by key. */
     entropyWhitelist: z$2.array(z$2.string()).optional(),
+    /** Additional key-match patterns (strings) for redaction. */
     redactPatterns: z$2.array(z$2.string()).optional(),
+    /** Dotenv search paths provided as a single delimited string. */
     paths: z$2.string().optional(),
+    /** Delimiter string used to split `paths`. */
     pathsDelimiter: z$2.string().optional(),
+    /** Regex pattern used to split `paths` (takes precedence over delimiter). */
     pathsDelimiterPattern: z$2.string().optional(),
+    /** Scripts table in a permissive shape at parse time (validated elsewhere). */
     scripts: z$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Shell selection (`false` for shell-off, string for explicit shell). */
     shell: z$2.union([z$2.boolean(), z$2.string()]).optional(),
+    /** Extra variables expressed as a single delimited string of assignments. */
     vars: z$2.string().optional(),
+    /** Assignment operator used when parsing `vars`. */
     varsAssignor: z$2.string().optional(),
+    /** Regex pattern used as the assignment operator for `vars` parsing. */
     varsAssignorPattern: z$2.string().optional(),
+    /** Delimiter string used to split `vars`. */
     varsDelimiter: z$2.string().optional(),
+    /** Regex pattern used to split `vars` (takes precedence over delimiter). */
     varsDelimiterPattern: z$2.string().optional(),
 });
 
@@ -118,17 +186,34 @@ const envStringMap = z$2.record(z$2.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$2.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$2.record(z$2.string(), z$2.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
+    /** Scripts table used by cmd/batch resolution (validation intentionally permissive here). */
+    scripts: z$2.record(z$2.string(), z$2.unknown()).optional(),
+    /** Keys required to be present in the final composed environment. */
     requiredKeys: z$2.array(z$2.string()).optional(),
+    /** Validation schema (JS/TS only; JSON/YAML loader rejects). */
     schema: z$2.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$2.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$2.record(z$2.string(), z$2.unknown()).optional(),
 });
 /**
@@ -1018,13 +1103,21 @@ function traceChildEnv(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',
@@ -1038,12 +1131,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: '=',
@@ -1590,6 +1678,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' };
@@ -1604,6 +1700,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 = {};
@@ -2063,6 +2167,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.
@@ -3016,18 +3130,49 @@ function applyRootVisibility(program, visibility) {
 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
@@ -3038,7 +3183,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('"')) ||
@@ -3073,6 +3218,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.
@@ -3086,12 +3232,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];
@@ -3116,7 +3267,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,
@@ -3131,30 +3282,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.
@@ -3186,31 +3350,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);
             }
         }
@@ -3228,6 +3388,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);
@@ -3244,16 +3417,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
+ */
+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
  */
-const AwsPluginConfigSchema = z$2.object({
+/** @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$2.object({
+    /** Preferred AWS profile name (overrides dotenv-derived profile keys when set). */
     profile: z$2.string().optional(),
+    /** Preferred AWS region (overrides dotenv-derived region key when set). */
     region: z$2.string().optional(),
+    /** Fallback region when region cannot be resolved from config/dotenv/AWS CLI. */
     defaultRegion: z$2.string().optional(),
+    /** Dotenv/config key for local profile lookup (default `AWS_LOCAL_PROFILE`). */
     profileKey: z$2.string().default('AWS_LOCAL_PROFILE').optional(),
+    /** Dotenv/config fallback key for profile lookup (default `AWS_PROFILE`). */
     profileFallbackKey: z$2.string().default('AWS_PROFILE').optional(),
+    /** Dotenv/config key for region lookup (default `AWS_REGION`). */
     regionKey: z$2.string().default('AWS_REGION').optional(),
+    /** Credential acquisition strategy (`cli-export` to resolve via AWS CLI, or `none` to skip). */
     strategy: z$2.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$2.boolean().default(false).optional(),
 });
 
@@ -3270,129 +3661,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;
 };
 
@@ -13854,21 +14132,79 @@ 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
+ */
+/** @hidden */
+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;
     },
 });
@@ -13976,7 +14312,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;
@@ -14085,11 +14421,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];
@@ -14190,24 +14552,71 @@ 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
+ */
+/** @hidden */
+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).
  */
 const ScriptSchema = z$2.union([
     z$2.string(),
     z$2.object({
+        /** Command string to execute. */
         cmd: z$2.string(),
+        /** Optional shell override for this script entry. */
         shell: z$2.union([z$2.string(), z$2.boolean()]).optional(),
     }),
 ]);
 /**
  * Zod schema for batch plugin configuration.
  */
-const BatchConfigSchema = z$2.object({
+const batchPluginConfigSchema = z$2.object({
+    /** Optional scripts table scoped to the batch plugin. */
     scripts: z$2.record(z$2.string(), ScriptSchema).optional(),
+    /** Optional default shell for batch execution (overridden by per-script shell when present). */
     shell: z$2.union([z$2.string(), z$2.boolean()]).optional(),
+    /** Root path for discovery, relative to CWD (or package root when pkgCwd is true). */
     rootPath: z$2.string().optional(),
+    /** Space-delimited glob patterns used to discover directories. */
     globs: z$2.string().optional(),
+    /** When true, resolve the batch root from the nearest package directory. */
     pkgCwd: z$2.boolean().optional(),
 });
 
@@ -14229,45 +14638,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;
         },
     });
@@ -14361,14 +14740,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];
@@ -14401,11 +14777,30 @@ 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
+ */
+/** @hidden */
+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 {
@@ -14516,8 +14911,9 @@ const attachParentInvoker = (cli, options, _cmd, plugin) => {
 /**
  * Zod schema for cmd plugin configuration.
  */
-const CmdConfigSchema = z$2
+const cmdPluginConfigSchema = z$2
     .object({
+    /** When true, expand the alias value before execution (default behavior when omitted). */
     expand: z$2.boolean().optional(),
 })
     .strict();
@@ -14536,7 +14932,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}
@@ -14548,14 +14944,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;
         },
@@ -14700,6 +15095,7 @@ const planConfigCopies = ({ format, withLocal, destRoot, }) => {
 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'),
@@ -14707,8 +15103,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,
         },
     ];
@@ -14750,129 +15166,149 @@ 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 (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 (changed) {
-                    logger.log(`Updated ${path.relative(cwd, giPath)}`);
+                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
+ */
+/** @hidden */
+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;
     },
 });