@karmaniverous/get-dotenv 4.5.2 → 5.0.0-0

package/dist/plugins-aws.mjs

@@ -0,0 +1,616 @@
+import { execa, execaCommand } from 'execa';
+import { z } from 'zod';
+
+// Minimal tokenizer for shell-off execution:
+// Splits by whitespace while preserving quoted segments (single or double quotes).
+const tokenize = (command) => {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const c = command.charAt(i);
+        if (quote) {
+            if (c === quote) {
+                // Support doubled quotes inside a quoted segment (Windows/PowerShell style):
+                // "" -> " and '' -> '
+                const next = command.charAt(i + 1);
+                if (next === quote) {
+                    cur += quote;
+                    i += 1; // skip the second quote
+                }
+                else {
+                    // end of quoted segment
+                    quote = null;
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+        else {
+            if (c === '"' || c === "'") {
+                quote = c;
+            }
+            else if (/\s/.test(c)) {
+                if (cur) {
+                    out.push(cur);
+                    cur = '';
+                }
+            }
+            else {
+                cur += c;
+            }
+        }
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+};
+
+const dbg = (...args) => {
+    if (process.env.GETDOTENV_DEBUG) {
+        // Use stderr to avoid interfering with stdout assertions
+        console.error('[getdotenv:run]', ...args);
+    }
+};
+// Strip repeated symmetric outer quotes (single or double) until stable.
+// This is safe for argv arrays passed to execa (no quoting needed) and avoids
+// passing quote characters through to Node (e.g., for `node -e "<code>"`).
+// Handles stacked quotes from shells like PowerShell: """code""" -> code.
+const stripOuterQuotes = (s) => {
+    let out = s;
+    // Repeatedly trim only when the entire string is wrapped in matching quotes.
+    // Stop as soon as the ends are asymmetric or no quotes remain.
+    while (out.length >= 2) {
+        const a = out.charAt(0);
+        const b = out.charAt(out.length - 1);
+        const symmetric = (a === '"' && b === '"') || (a === "'" && b === "'");
+        if (!symmetric)
+            break;
+        out = out.slice(1, -1);
+    }
+    return out;
+};
+// Extract exitCode/stdout/stderr from execa result or error in a tolerant way.
+const pickResult = (r) => {
+    const exit = r.exitCode;
+    const stdoutVal = r.stdout;
+    const stderrVal = r.stderr;
+    return {
+        exitCode: typeof exit === 'number' ? exit : Number.NaN,
+        stdout: typeof stdoutVal === 'string' ? stdoutVal : '',
+        stderr: typeof stderrVal === 'string' ? stderrVal : '',
+    };
+};
+// Convert NodeJS.ProcessEnv (string | undefined values) to the shape execa
+// expects (Readonly<Partial<Record<string, string>>>), dropping undefineds.
+const sanitizeEnv = (env) => {
+    if (!env)
+        return undefined;
+    const entries = Object.entries(env).filter((e) => typeof e[1] === 'string');
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+};
+/**
+ * Execute a command and capture stdout/stderr (buffered).
+ * - Preserves plain vs shell behavior and argv/string normalization.
+ * - Never re-emits stdout/stderr to parent; returns captured buffers.
+ * - Supports optional timeout (ms).
+ */
+const runCommandResult = async (command, shell, opts = {}) => {
+    const envSan = sanitizeEnv(opts.env);
+    {
+        let file;
+        let args = [];
+        if (Array.isArray(command)) {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        else {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        if (!file)
+            return { exitCode: 0, stdout: '', stderr: '' };
+        dbg('exec:capture (plain)', { file, args });
+        try {
+            const result = await execa(file, args, {
+                ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
+                ...(envSan !== undefined ? { env: envSan } : {}),
+                stdio: 'pipe',
+                ...(opts.timeoutMs !== undefined
+                    ? { timeout: opts.timeoutMs, killSignal: 'SIGKILL' }
+                    : {}),
+            });
+            const ok = pickResult(result);
+            dbg('exit:capture (plain)', { exitCode: ok.exitCode });
+            return ok;
+        }
+        catch (err) {
+            const out = pickResult(err);
+            dbg('exit:capture:error (plain)', { exitCode: out.exitCode });
+            return out;
+        }
+    }
+};
+const runCommand = async (command, shell, opts) => {
+    if (shell === false) {
+        let file;
+        let args = [];
+        if (Array.isArray(command)) {
+            file = command[0];
+            args = command.slice(1).map(stripOuterQuotes);
+        }
+        else {
+            const tokens = tokenize(command);
+            file = tokens[0];
+            args = tokens.slice(1);
+        }
+        if (!file)
+            return 0;
+        dbg('exec (plain)', { file, args, stdio: opts.stdio });
+        // Build options without injecting undefined properties (exactOptionalPropertyTypes).
+        const envSan = sanitizeEnv(opts.env);
+        const plainOpts = {};
+        if (opts.cwd !== undefined)
+            plainOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            plainOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            plainOpts.stdio = opts.stdio;
+        const result = await execa(file, args, plainOpts);
+        if (opts.stdio === 'pipe' && result.stdout) {
+            process.stdout.write(result.stdout + (result.stdout.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg('exit (plain)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+    else {
+        const commandStr = Array.isArray(command) ? command.join(' ') : command;
+        dbg('exec (shell)', {
+            shell: typeof shell === 'string' ? shell : 'custom',
+            stdio: opts.stdio,
+            command: commandStr,
+        });
+        const envSan = sanitizeEnv(opts.env);
+        const shellOpts = { shell };
+        if (opts.cwd !== undefined)
+            shellOpts.cwd = opts.cwd;
+        if (envSan !== undefined)
+            shellOpts.env = envSan;
+        if (opts.stdio !== undefined)
+            shellOpts.stdio = opts.stdio;
+        const result = await execaCommand(commandStr, shellOpts);
+        const out = result?.stdout;
+        if (opts.stdio === 'pipe' && out) {
+            process.stdout.write(out + (out.endsWith('\n') ? '' : '\n'));
+        }
+        const exit = result?.exitCode;
+        dbg('exit (shell)', { exitCode: exit });
+        return typeof exit === 'number' ? exit : Number.NaN;
+    }
+};
+
+/**
+ * Define a GetDotenv CLI plugin with compositional helpers.
+ *
+ * @example
+ * const parent = definePlugin(\{ id: 'p', setup(cli) \{ /* ... *\/ \} \})
+ *   .use(childA)
+ *   .use(childB);
+ */
+const definePlugin = (spec) => {
+    const { children = [], ...rest } = spec;
+    const plugin = {
+        ...rest,
+        children: [...children],
+        use(child) {
+            this.children.push(child);
+            return this;
+        },
+    };
+    return plugin;
+};
+
+/**
+ * Batch services (neutral): resolve command and shell settings.
+ * Shared by the generator path and the batch plugin to avoid circular deps.
+ */
+/**
+ * Resolve a command string from the {@link Scripts} table.
+ * A script may be expressed as a string or an object with a `cmd` property.
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @returns Resolved command string (falls back to the provided command).
+ */
+/**
+ * Resolve the shell setting for a given command:
+ * - If the script entry is an object, prefer its `shell` override.
+ * - Otherwise use the provided `shell` (string | boolean).
+ *
+ * @param scripts - Optional scripts table.
+ * @param command - User-provided command name or string.
+ * @param shell - Global shell preference (string | boolean).
+ */
+const resolveShell = (scripts, command, shell) => scripts && typeof scripts[command] === 'object'
+    ? (scripts[command].shell ?? false)
+    : (shell ?? false);
+
+const DEFAULT_TIMEOUT_MS = 15_000;
+const trim = (s) => (typeof s === 'string' ? s.trim() : '');
+const unquote = (s) => s.length >= 2 &&
+    ((s.startsWith('"') && s.endsWith('"')) ||
+        (s.startsWith("'") && s.endsWith("'")))
+    ? s.slice(1, -1)
+    : s;
+const parseExportCredentialsJson = (txt) => {
+    try {
+        const obj = JSON.parse(txt);
+        const src = obj.Credentials ?? obj;
+        const ak = src.AccessKeyId;
+        const sk = src.SecretAccessKey;
+        const tk = src.SessionToken;
+        if (ak && sk)
+            return {
+                accessKeyId: ak,
+                secretAccessKey: sk,
+                ...(tk ? { sessionToken: tk } : {}),
+            };
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+};
+const parseExportCredentialsEnv = (txt) => {
+    const lines = txt.split(/\r?\n/);
+    let id;
+    let secret;
+    let token;
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        // POSIX: export AWS_ACCESS_KEY_ID=..., export AWS_SECRET_ACCESS_KEY=..., export AWS_SESSION_TOKEN=...
+        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);
+        }
+        if (!m)
+            continue;
+        const k = m[1];
+        const valRaw = m[2];
+        if (typeof valRaw !== 'string')
+            continue;
+        let v = unquote(valRaw.trim());
+        // Drop trailing semicolons if present (some shells)
+        v = v.replace(/;$/, '');
+        if (k === 'AWS_ACCESS_KEY_ID')
+            id = v;
+        else if (k === 'AWS_SECRET_ACCESS_KEY')
+            secret = v;
+        else if (k === 'AWS_SESSION_TOKEN')
+            token = v;
+    }
+    if (id && secret)
+        return {
+            accessKeyId: id,
+            secretAccessKey: secret,
+            ...(token ? { sessionToken: token } : {}),
+        };
+    return undefined;
+};
+const getAwsConfigure = async (key, profile, timeoutMs = DEFAULT_TIMEOUT_MS) => {
+    const r = await runCommandResult(['aws', 'configure', 'get', key, '--profile', profile], false, {
+        env: process.env,
+        timeoutMs,
+    });
+    // Guard for mocked undefined in tests; keep narrow lint scope.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!r || typeof r.exitCode !== 'number')
+        return undefined;
+    if (r.exitCode === 0) {
+        const v = trim(r.stdout);
+        return v.length > 0 ? v : undefined;
+    }
+    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);
+        if (creds)
+            return creds;
+    }
+    return undefined;
+};
+const resolveAwsContext = async ({ dotenv, cfg, }) => {
+    const profileKey = cfg.profileKey ?? 'AWS_LOCAL_PROFILE';
+    const profileFallbackKey = cfg.profileFallbackKey ?? 'AWS_PROFILE';
+    const regionKey = cfg.regionKey ?? 'AWS_REGION';
+    const profile = cfg.profile ??
+        dotenv[profileKey] ??
+        dotenv[profileFallbackKey] ??
+        undefined;
+    let region = cfg.region ?? dotenv[regionKey] ?? undefined;
+    // Short-circuit when strategy is disabled.
+    if (cfg.strategy === 'none') {
+        // If region is still missing and we have a profile, try best-effort region resolve.
+        if (!region && profile)
+            region = await getAwsConfigure('region', profile);
+        if (!region && cfg.defaultRegion)
+            region = cfg.defaultRegion;
+        const out = {};
+        if (profile !== undefined)
+            out.profile = profile;
+        if (region !== undefined)
+            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) {
+        // 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;
+            if (looksSSO && cfg.loginOnDemand) {
+                // Best-effort login, then retry export once.
+                await runCommandResult(['aws', 'sso', 'login', '--profile', profile], false, {
+                    env: process.env,
+                    timeoutMs: DEFAULT_TIMEOUT_MS,
+                });
+                credentials = await exportCredentials(profile);
+            }
+        }
+        // Static fallback if still missing.
+        if (!credentials) {
+            const id = await getAwsConfigure('aws_access_key_id', profile);
+            const secret = await getAwsConfigure('aws_secret_access_key', profile);
+            const token = await getAwsConfigure('aws_session_token', profile);
+            if (id && secret) {
+                credentials = {
+                    accessKeyId: id,
+                    secretAccessKey: secret,
+                    ...(token ? { sessionToken: token } : {}),
+                };
+            }
+        }
+    }
+    // Final region resolution
+    if (!region && profile)
+        region = await getAwsConfigure('region', profile);
+    if (!region && cfg.defaultRegion)
+        region = cfg.defaultRegion;
+    const out = {};
+    if (profile !== undefined)
+        out.profile = profile;
+    if (region !== undefined)
+        out.region = region;
+    if (credentials)
+        out.credentials = credentials;
+    return out;
+};
+
+const AwsPluginConfigSchema = z.object({
+    profile: z.string().optional(),
+    region: z.string().optional(),
+    defaultRegion: z.string().optional(),
+    profileKey: z.string().default('AWS_LOCAL_PROFILE').optional(),
+    profileFallbackKey: z.string().default('AWS_PROFILE').optional(),
+    regionKey: z.string().default('AWS_REGION').optional(),
+    strategy: z.enum(['cli-export', 'none']).default('cli-export').optional(),
+    loginOnDemand: z.boolean().default(false).optional(),
+    setEnv: z.boolean().default(true).optional(),
+    addCtx: z.boolean().default(true).optional(),
+});
+
+const awsPlugin = () => definePlugin({
+    id: 'aws',
+    // Host validates this slice when the loader path is active.
+    configSchema: AwsPluginConfigSchema,
+    setup(cli) {
+        // Subcommand: aws
+        cli
+            .ns('aws')
+            .description('Establish an AWS session and optionally forward to the AWS CLI')
+            .configureHelp({ showGlobalOptions: true })
+            .enablePositionalOptions()
+            .passThroughOptions()
+            .allowUnknownOption(true)
+            // Boolean toggles
+            .option('--login-on-demand', 'attempt aws sso login on-demand')
+            .option('--no-login-on-demand', 'disable sso login on-demand')
+            .option('--set-env', 'write resolved values into process.env')
+            .option('--no-set-env', 'do not write resolved values into process.env')
+            .option('--add-ctx', 'mirror results under ctx.plugins.aws')
+            .option('--no-add-ctx', 'do not mirror results under ctx.plugins.aws')
+            // Strings / enums
+            .option('--profile <string>', 'AWS profile name')
+            .option('--region <string>', 'AWS region')
+            .option('--default-region <string>', 'fallback region')
+            .option('--strategy <string>', 'credential acquisition strategy: cli-export|none')
+            // Advanced key overrides
+            .option('--profile-key <string>', 'dotenv/config key for local profile')
+            .option('--profile-fallback-key <string>', 'fallback dotenv/config key for profile')
+            .option('--region-key <string>', 'dotenv/config key for region')
+            // Accept any extra operands so Commander does not error when tokens appear after "--".
+            .argument('[args...]')
+            .action(async (args, opts, thisCommand) => {
+            const self = thisCommand;
+            const parent = (self.parent ?? null);
+            // Access merged root CLI options (installed by passOptions())
+            const rootOpts = (parent?.getDotenvCliOptions ?? {});
+            const capture = process.env.GETDOTENV_STDIO === 'pipe' ||
+                Boolean(rootOpts?.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 = (ctx?.pluginConfigs?.['aws'] ??
+                {});
+            const overlay = {};
+            // Map boolean toggles (respect explicit --no-*)
+            if (Object.prototype.hasOwnProperty.call(opts, 'loginOnDemand'))
+                overlay.loginOnDemand = Boolean(opts.loginOnDemand);
+            if (Object.prototype.hasOwnProperty.call(opts, 'setEnv'))
+                overlay.setEnv = Boolean(opts.setEnv);
+            if (Object.prototype.hasOwnProperty.call(opts, 'addCtx'))
+                overlay.addCtx = Boolean(opts.addCtx);
+            // Strings/enums
+            if (typeof opts.profile === 'string')
+                overlay.profile = opts.profile;
+            if (typeof opts.region === 'string')
+                overlay.region = opts.region;
+            if (typeof opts.defaultRegion === 'string')
+                overlay.defaultRegion = opts.defaultRegion;
+            if (typeof opts.strategy === 'string')
+                overlay.strategy =
+                    opts.strategy;
+            // Advanced key overrides
+            if (typeof opts.profileKey === 'string')
+                overlay.profileKey = opts.profileKey;
+            if (typeof opts.profileFallbackKey === 'string')
+                overlay.profileFallbackKey = opts.profileFallbackKey;
+            if (typeof opts.regionKey === 'string')
+                overlay.regionKey = opts.regionKey;
+            const cfg = {
+                ...cfgBase,
+                ...overlay,
+            };
+            // Resolve current context with overrides
+            const out = await resolveAwsContext({
+                dotenv: ctx?.dotenv ?? {},
+                cfg,
+            });
+            // Apply env/ctx mirrors per toggles
+            if (cfg.setEnv !== false) {
+                if (out.region) {
+                    process.env.AWS_REGION = out.region;
+                    if (!process.env.AWS_DEFAULT_REGION)
+                        process.env.AWS_DEFAULT_REGION = out.region;
+                }
+                if (out.credentials) {
+                    process.env.AWS_ACCESS_KEY_ID = out.credentials.accessKeyId;
+                    process.env.AWS_SECRET_ACCESS_KEY =
+                        out.credentials.secretAccessKey;
+                    if (out.credentials.sessionToken !== undefined) {
+                        process.env.AWS_SESSION_TOKEN = out.credentials.sessionToken;
+                    }
+                }
+            }
+            if (cfg.addCtx !== false) {
+                if (ctx) {
+                    ctx.plugins ??= {};
+                    ctx.plugins['aws'] = {
+                        ...(out.profile ? { profile: out.profile } : {}),
+                        ...(out.region ? { region: out.region } : {}),
+                        ...(out.credentials ? { credentials: out.credentials } : {}),
+                    };
+                }
+            }
+            // Forward when positional args are present; otherwise session-only.
+            if (Array.isArray(args) && args.length > 0) {
+                const argv = ['aws', ...args];
+                const shellSetting = resolveShell(rootOpts?.scripts, 'aws', rootOpts?.shell);
+                const ctxDotenv = (ctx?.dotenv ?? {});
+                const exit = await runCommand(argv, shellSetting, {
+                    env: { ...process.env, ...ctxDotenv },
+                    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) {
+                    const log = console;
+                    log.log('[aws] session established', {
+                        profile: out.profile,
+                        region: out.region,
+                        hasCreds: Boolean(out.credentials),
+                    });
+                }
+                if (!underTests)
+                    process.exit(0);
+                return;
+            }
+        });
+    },
+    async afterResolve(_cli, ctx) {
+        const log = console;
+        const cfgRaw = (ctx.pluginConfigs?.['aws'] ?? {});
+        const cfg = (cfgRaw || {});
+        const out = await resolveAwsContext({
+            dotenv: ctx.dotenv,
+            cfg,
+        });
+        const { profile, region, credentials } = out;
+        if (cfg.setEnv !== false) {
+            if (region) {
+                process.env.AWS_REGION = region;
+                if (!process.env.AWS_DEFAULT_REGION)
+                    process.env.AWS_DEFAULT_REGION = region;
+            }
+            if (credentials) {
+                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;
+                }
+            }
+        }
+        if (cfg.addCtx !== false) {
+            ctx.plugins ??= {};
+            ctx.plugins['aws'] = {
+                ...(profile ? { profile } : {}),
+                ...(region ? { region } : {}),
+                ...(credentials ? { credentials } : {}),
+            };
+        }
+        // Optional: low-noise breadcrumb for diagnostics
+        if (process.env.GETDOTENV_DEBUG) {
+            log.log('[aws] afterResolve', {
+                profile,
+                region,
+                hasCreds: Boolean(credentials),
+            });
+        }
+    },
+});
+
+export { awsPlugin };