@karmaniverous/aws-secrets-manager-tools 0.1.0

package/dist/cli/aws-secrets-manager-tools/index.js

@@ -0,0 +1,889 @@
+#!/usr/bin/env node
+import { createCli } from '@karmaniverous/get-dotenv/cli';
+import { cmdPlugin, batchPlugin, awsPlugin, initPlugin } from '@karmaniverous/get-dotenv/plugins';
+import { readMergedOptions, z, definePlugin } from '@karmaniverous/get-dotenv/cliHost';
+import { SecretsManagerClient, GetSecretValueCommand, PutSecretValueCommand, CreateSecretCommand, DeleteSecretCommand } from '@aws-sdk/client-secrets-manager';
+import { dotenvExpand, getDotenvCliOptions2Options, editDotenvFile } from '@karmaniverous/get-dotenv';
+import { omit, pick } from 'radash';
+import { Buffer } from 'node:buffer';
+
+/**
+ * Requirements addressed:
+ * - `push` should create only when the secret doesn't exist (not on any error).
+ */
+const getAwsErrorCode = (err) => {
+    if (!err || typeof err !== 'object')
+        return;
+    const e = err;
+    const code = e.name ?? e.code ?? e.Code;
+    return typeof code === 'string' ? code : undefined;
+};
+const isAwsErrorCode = (err, code) => getAwsErrorCode(err) === code;
+const isResourceNotFoundError = (err) => isAwsErrorCode(err, 'ResourceNotFoundException');
+
+/**
+ * Requirements addressed:
+ * - Optional AWS X-Ray capture support.
+ * - Default behavior “auto”: only attempt capture when AWS_XRAY_DAEMON_ADDRESS
+ *   is set.
+ * - Avoid importing/enabling X-Ray when the daemon address is not set (the
+ *   X-Ray SDK will throw otherwise).
+ */
+const shouldEnableXray = (mode, daemonAddress) => {
+    if (mode === 'off')
+        return false;
+    if (mode === 'on')
+        return true;
+    return Boolean(daemonAddress);
+};
+const captureAwsSdkV3Client = async (client, { mode = 'auto', logger = console, daemonAddress = process.env.AWS_XRAY_DAEMON_ADDRESS, } = {}) => {
+    if (!shouldEnableXray(mode, daemonAddress))
+        return client;
+    if (!daemonAddress) {
+        throw new Error('X-Ray capture requested but AWS_XRAY_DAEMON_ADDRESS is not set.');
+    }
+    // Guarded dynamic import: some X-Ray SDK integrations throw when daemon
+    // configuration is missing, so do not import unless we are capturing.
+    let mod;
+    try {
+        mod = (await import('aws-xray-sdk'));
+    }
+    catch {
+        throw new Error("X-Ray capture is enabled but 'aws-xray-sdk' is not installed. Install it or set xray to 'off'.");
+    }
+    const AWSXRay = (mod.default ?? mod);
+    if (typeof AWSXRay.captureAWSv3Client !== 'function') {
+        logger.debug('aws-xray-sdk does not expose captureAWSv3Client', AWSXRay);
+        throw new Error('aws-xray-sdk missing captureAWSv3Client export.');
+    }
+    logger.debug('Enabling AWS X-Ray capture for AWS SDK v3 client.');
+    return AWSXRay.captureAWSv3Client(client);
+};
+
+/**
+ * Requirements addressed:
+ * - Provide a public tools-style wrapper `AwsSecretsManagerTools`.
+ * - Package consumers should not need to construct SecretsManagerClient; they
+ *   should use `AwsSecretsManagerTools.init(...)` and optionally import AWS SDK
+ *   Commands for advanced operations.
+ * - Expose the fully configured SDK client via `tools.client`.
+ * - Support optional AWS X-Ray capture:
+ *   - Default “auto”: enable only when AWS_XRAY_DAEMON_ADDRESS is set.
+ *   - In “auto”, if the daemon address is set but aws-xray-sdk is missing,
+ *     throw with a clear message.
+ * - Enforce a minimal logger contract (debug/info/warn/error); do not attempt
+ *   to polyfill or proxy unknown loggers.
+ * - Secret values are JSON object maps of env vars.
+ */
+const assertLogger = (candidate) => {
+    if (!candidate || typeof candidate !== 'object') {
+        throw new Error('logger must be an object with debug, info, warn, and error methods');
+    }
+    const logger = candidate;
+    if (typeof logger.debug !== 'function' ||
+        typeof logger.info !== 'function' ||
+        typeof logger.warn !== 'function' ||
+        typeof logger.error !== 'function') {
+        throw new Error('logger must implement debug, info, warn, and error methods; wrap/proxy your logger if needed');
+    }
+    return logger;
+};
+const parseEnvSecretMap = (secretString) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(secretString);
+    }
+    catch {
+        throw new Error('SecretString is not valid JSON.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Secret JSON must be an object map.');
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (v === null) {
+            out[k] = undefined;
+            continue;
+        }
+        if (typeof v === 'string') {
+            out[k] = v;
+            continue;
+        }
+        throw new Error(`Secret JSON value for '${k}' must be a string or null.`);
+    }
+    return out;
+};
+const toSecretString = (value) => JSON.stringify(value);
+/**
+ * Tools-style AWS Secrets Manager wrapper for env-map secrets.
+ *
+ * The secret payload is always a JSON object map of environment variables:
+ * `Record<string, string | undefined>`.
+ *
+ * Consumers should typically use the convenience methods on this class, and
+ * use {@link AwsSecretsManagerTools.client} as an escape hatch when they need
+ * AWS SDK operations not wrapped here.
+ */
+class AwsSecretsManagerTools {
+    /**
+     * The effective SDK client (captured when X-Ray is enabled).
+     *
+     * Import AWS SDK `*Command` classes as needed and call `tools.client.send(...)`.
+     */
+    client;
+    /**
+     * The effective client config used to construct the base client.
+     *
+     * Note: this may contain functions/providers (e.g., credential providers).
+     */
+    clientConfig;
+    /** The logger used by this wrapper and (when applicable) by the AWS client. */
+    logger;
+    /** Materialized X-Ray state (mode + enabled + daemonAddress when relevant). */
+    xray;
+    constructor({ client, clientConfig, logger, xray, }) {
+        this.client = client;
+        this.clientConfig = clientConfig;
+        this.logger = logger;
+        this.xray = xray;
+    }
+    /**
+     * Initialize an `AwsSecretsManagerTools` instance.
+     *
+     * This factory owns all setup (including optional X-Ray capture) so consumers
+     * do not need to construct a base Secrets Manager client themselves.
+     *
+     * @throws If `clientConfig.logger` is provided but does not implement
+     * `debug`, `info`, `warn`, and `error`.
+     * @throws If X-Ray capture is enabled (via `xray: 'on'` or `xray: 'auto'`
+     * with `AWS_XRAY_DAEMON_ADDRESS` set) but `aws-xray-sdk` is not installed.
+     * @throws If X-Ray capture is requested but `AWS_XRAY_DAEMON_ADDRESS` is not set.
+     */
+    static async init({ clientConfig = {}, xray: xrayMode = 'auto', } = {}) {
+        const logger = assertLogger(clientConfig.logger ?? console);
+        const effectiveClientConfig = {
+            ...clientConfig,
+            logger,
+        };
+        const base = new SecretsManagerClient(effectiveClientConfig);
+        const daemonAddress = process.env.AWS_XRAY_DAEMON_ADDRESS;
+        const enabled = shouldEnableXray(xrayMode, daemonAddress);
+        const xrayState = {
+            mode: xrayMode,
+            enabled,
+            ...(enabled && daemonAddress ? { daemonAddress } : {}),
+        };
+        const effectiveClient = enabled
+            ? await captureAwsSdkV3Client(base, {
+                mode: xrayMode,
+                logger,
+                daemonAddress,
+            })
+            : base;
+        return new AwsSecretsManagerTools({
+            client: effectiveClient,
+            clientConfig: effectiveClientConfig,
+            logger,
+            xray: xrayState,
+        });
+    }
+    /**
+     * Read a Secrets Manager secret and parse it as an env-map secret.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `versionId`: Optional version id to read.
+     *
+     * @throws If the secret is missing, binary, invalid JSON, or not an object map.
+     */
+    async readEnvSecret(opts) {
+        const { secretId, versionId } = opts;
+        if (!secretId)
+            throw new Error('secretId is required');
+        this.logger.debug(`Getting secret value...`, { secretId, versionId });
+        const res = (await this.client.send(new GetSecretValueCommand({
+            SecretId: secretId,
+            ...(versionId ? { VersionId: versionId } : {}),
+        })));
+        if (!res.SecretString) {
+            throw new Error('SecretString is missing (binary secrets not supported).');
+        }
+        return parseEnvSecretMap(res.SecretString);
+    }
+    /**
+     * Write a new version value for an existing secret.
+     *
+     * This does not create the secret if it does not exist.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `value`: Env-map payload to store (JSON object map).
+     *   - `versionId`: Optional client request token (idempotency).
+     */
+    async updateEnvSecret(opts) {
+        const { secretId, value, versionId } = opts;
+        if (!secretId)
+            throw new Error('secretId is required');
+        this.logger.debug(`Putting secret value...`, { secretId, versionId });
+        await this.client.send(new PutSecretValueCommand({
+            SecretId: secretId,
+            SecretString: toSecretString(value),
+            ...(versionId ? { ClientRequestToken: versionId } : {}),
+        }));
+    }
+    /**
+     * Create a new secret containing an env-map.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name (or ARN in some contexts).
+     *   - `value`: Env-map payload to store (JSON object map).
+     *   - `description`: Optional AWS secret description.
+     *   - `forceOverwriteReplicaSecret`: See AWS CreateSecret behavior for replicas.
+     *   - `versionId`: Optional client request token (idempotency).
+     */
+    async createEnvSecret(opts) {
+        const { secretId, value, description, forceOverwriteReplicaSecret, versionId, } = opts;
+        if (!secretId)
+            throw new Error('secretId is required');
+        this.logger.debug(`Creating secret...`, { secretId, versionId });
+        await this.client.send(new CreateSecretCommand({
+            Name: secretId,
+            SecretString: toSecretString(value),
+            ...(versionId ? { ClientRequestToken: versionId } : {}),
+            ...(description ? { Description: description } : {}),
+            ...(typeof forceOverwriteReplicaSecret === 'boolean'
+                ? { ForceOverwriteReplicaSecret: forceOverwriteReplicaSecret }
+                : {}),
+        }));
+    }
+    /**
+     * Put a secret value, creating the secret only when it does not exist.
+     *
+     * This creates only when the update fails with `ResourceNotFoundException`;
+     * other errors are re-thrown.
+     *
+     * @returns `'updated'` if updated; `'created'` if the secret was created.
+     * @throws Re-throws any non-ResourceNotFound AWS errors.
+     */
+    async upsertEnvSecret({ secretId, value, }) {
+        try {
+            await this.updateEnvSecret({ secretId, value });
+            return 'updated';
+        }
+        catch (err) {
+            if (!isResourceNotFoundError(err))
+                throw err;
+            await this.createEnvSecret({ secretId, value });
+            return 'created';
+        }
+    }
+    /**
+     * Delete a secret.
+     *
+     * By default, deletion is recoverable (AWS default recovery window) unless
+     * `forceDeleteWithoutRecovery` is set.
+     *
+     * @param opts - Options:
+     *   - `secretId`: Secret name or ARN.
+     *   - `recoveryWindowInDays`: Explicit recovery window to use.
+     *   - `forceDeleteWithoutRecovery`: Dangerous: delete without recovery.
+     *
+     * @throws If both `recoveryWindowInDays` and `forceDeleteWithoutRecovery` are provided.
+     */
+    async deleteSecret(opts) {
+        const { secretId, recoveryWindowInDays, forceDeleteWithoutRecovery } = opts;
+        if (!secretId)
+            throw new Error('secretId is required');
+        if (typeof recoveryWindowInDays !== 'undefined' &&
+            typeof forceDeleteWithoutRecovery !== 'undefined') {
+            throw new Error('recoveryWindowInDays and forceDeleteWithoutRecovery are mutually exclusive');
+        }
+        this.logger.debug(`Deleting secret...`, {
+            secretId,
+            recoveryWindowInDays,
+            forceDeleteWithoutRecovery,
+        });
+        await this.client.send(new DeleteSecretCommand({
+            SecretId: secretId,
+            ...(typeof recoveryWindowInDays === 'number'
+                ? { RecoveryWindowInDays: recoveryWindowInDays }
+                : {}),
+            ...(typeof forceDeleteWithoutRecovery === 'boolean'
+                ? { ForceDeleteWithoutRecovery: forceDeleteWithoutRecovery }
+                : {}),
+        }));
+    }
+}
+
+/**
+ * Requirements addressed:
+ * - Secret name expansion expands against `{ ...process.env, ...ctx.dotenv }`.
+ * - include/exclude ignore unknown keys; use radash (no lodash).
+ */
+const buildExpansionEnv = (ctxDotenv) => ({
+    ...process.env,
+    ...ctxDotenv,
+});
+const expandSecretName = (raw, envRef) => dotenvExpand(raw, envRef) ?? raw;
+const applyIncludeExclude = (env, { include, exclude, }) => {
+    let out = env;
+    if (exclude?.length)
+        out = omit(out, exclude);
+    if (include?.length)
+        out = pick(out, include);
+    return out;
+};
+
+/**
+ * Requirements addressed:
+ * - Enforce AWS Secrets Manager SecretString size limits (65,536 bytes).
+ * - Provide safe parsing helpers for CLI-mapped inputs.
+ * - Render config-derived defaults in dynamic option help text.
+ * - Access aws plugin ctx state via runtime narrowing (no casts).
+ */
+const silentLogger = {
+    debug: () => {
+        // no-op
+    },
+    info: () => {
+        // no-op
+    },
+    warn: () => {
+        // no-op
+    },
+    error: () => {
+        // no-op
+    },
+};
+const requireString = (v, msg) => {
+    if (typeof v !== 'string' || !v)
+        throw new Error(msg);
+    return v;
+};
+const toNumber = (v) => {
+    if (typeof v === 'undefined')
+        return;
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim())
+        return Number(v);
+    return;
+};
+const assertBytesWithinSecretsManagerLimit = (value) => {
+    const s = JSON.stringify(value);
+    const bytes = Buffer.byteLength(s, 'utf8');
+    if (bytes > 65_536) {
+        throw new Error(`SecretString size ${String(bytes)} bytes exceeds 65536 bytes; narrow selection with --from/--include/--exclude.`);
+    }
+};
+const describeDefault = (v) => {
+    if (Array.isArray(v))
+        return v.length ? v.join(' ') : 'none';
+    if (typeof v === 'string' && v.trim())
+        return v;
+    return 'none';
+};
+const isRecord = (v) => typeof v === 'object' && v !== null;
+const getAwsRegion = (ctx) => {
+    if (!isRecord(ctx.plugins))
+        return;
+    const aws = ctx.plugins['aws'];
+    if (!isRecord(aws))
+        return;
+    const region = aws['region'];
+    return typeof region === 'string' ? region : undefined;
+};
+const describeConfigKeyListDefaults = ({ cfgInclude, cfgExclude, }) => {
+    // Avoid throwing in help rendering: show an explicit invalid marker.
+    if (cfgInclude?.length && cfgExclude?.length) {
+        const msg = '(invalid: both set in config)';
+        return { includeDefault: msg, excludeDefault: msg };
+    }
+    return {
+        includeDefault: describeDefault(cfgExclude?.length ? undefined : cfgInclude),
+        excludeDefault: describeDefault(cfgInclude?.length ? undefined : cfgExclude),
+    };
+};
+
+/**
+ * Requirements addressed:
+ * - Provide `aws secrets delete`.
+ * - Require `--force` for delete-without-recovery; otherwise use recoverable
+ *   deletion and do not set RecoveryWindowInDays unless explicitly provided.
+ * - For config-backed plugin options, use plugin dynamic options to show
+ *   composed defaults in help output.
+ */
+const registerDeleteCommand = ({ cli, plugin, }) => {
+    const del = cli
+        .ns('delete')
+        .description('Delete a Secrets Manager secret (recoverable by default).');
+    const delRecoveryOpt = del
+        .createOption('--recovery-window-days <number>', 'recovery window in days (omit to use AWS default)')
+        .conflicts('force');
+    const delForceOpt = del
+        .createOption('--force', 'force delete without recovery (DANGEROUS)')
+        .conflicts('recoveryWindowDays')
+        .default(false);
+    del
+        .addOption(plugin.createPluginDynamicOption(del, '-s, --secret-name <string>', (_helpCfg, pluginCfg) => `secret name (supports $VAR expansion) (default: ${pluginCfg.secretName ?? '$STACK_NAME'})`))
+        .addOption(delRecoveryOpt)
+        .addOption(delForceOpt)
+        .action(async (opts) => {
+        const bag = readMergedOptions(del);
+        const sdkLogger = bag.debug ? console : silentLogger;
+        const logger = console;
+        const ctx = cli.getCtx();
+        const cfg = plugin.readConfig(del);
+        const envRef = buildExpansionEnv(ctx.dotenv);
+        const secretNameRaw = opts.secretName ?? cfg.secretName ?? '$STACK_NAME';
+        const secretId = expandSecretName(secretNameRaw, envRef);
+        if (!secretId)
+            throw new Error('secret-name is required.');
+        const recoveryWindowInDays = toNumber(opts.recoveryWindowDays);
+        const region = getAwsRegion(ctx);
+        const tools = await AwsSecretsManagerTools.init({
+            clientConfig: region
+                ? { region, logger: sdkLogger }
+                : { logger: sdkLogger },
+        });
+        logger.info(`Deleting secret '${secretId}' from AWS Secrets Manager...`);
+        await tools.deleteSecret({
+            secretId,
+            ...(opts.force
+                ? { forceDeleteWithoutRecovery: true }
+                : typeof recoveryWindowInDays === 'number'
+                    ? { recoveryWindowInDays }
+                    : {}),
+        });
+        logger.info('Done.');
+    });
+};
+
+/**
+ * Requirements addressed:
+ * - `push` selects a subset of `ctx.dotenv` keys using `ctx.dotenvProvenance`,
+ *   matching only the effective provenance entry (last entry for a key).
+ * - `push` supports repeatable `--from <selector...>` with grammar:
+ *   - file:<scope>:<privacy> (scope: global|env|*; privacy: public|private|*)
+ *   - config:<configScope>:<scope>:<privacy> (configScope: packaged|project|*)
+ *   - dynamic:<dynamicSource> (dynamicSource: config|programmatic|dynamicPath|*)
+ *   - vars
+ * - `pull` uses `--to <scope>:<privacy>` (scope: global|env; privacy: public|private).
+ * - No path-based selector matching is supported.
+ * - Provenance entry shapes are sourced from get-dotenv’s public ctx types.
+ */
+const isOneOf = (v, allowed) => allowed.includes(v);
+const parseParts = (raw) => raw
+    .split(':')
+    .map((p) => p.trim())
+    .filter(Boolean);
+const parseFromSelector = (raw) => {
+    const parts = parseParts(raw);
+    const kind = parts[0];
+    if (parts.length === 1 && kind === 'vars')
+        return { kind: 'vars' };
+    if (kind === 'file') {
+        if (parts.length !== 3)
+            throw new Error(`Invalid --from selector: ${raw}`);
+        const scope = parts[1];
+        const privacy = parts[2];
+        if (!isOneOf(scope, ['global', 'env', '*']) ||
+            !isOneOf(privacy, ['public', 'private', '*'])) {
+            throw new Error(`Invalid --from selector: ${raw}`);
+        }
+        return { kind: 'file', scope, privacy };
+    }
+    if (kind === 'config') {
+        if (parts.length !== 4)
+            throw new Error(`Invalid --from selector: ${raw}`);
+        const configScope = parts[1];
+        const scope = parts[2];
+        const privacy = parts[3];
+        if (!isOneOf(configScope, ['packaged', 'project', '*']) ||
+            !isOneOf(scope, ['global', 'env', '*']) ||
+            !isOneOf(privacy, ['public', 'private', '*'])) {
+            throw new Error(`Invalid --from selector: ${raw}`);
+        }
+        return { kind: 'config', configScope, scope, privacy };
+    }
+    if (kind === 'dynamic') {
+        if (parts.length !== 2)
+            throw new Error(`Invalid --from selector: ${raw}`);
+        const dynamicSource = parts[1];
+        if (!isOneOf(dynamicSource, [
+            'config',
+            'programmatic',
+            'dynamicPath',
+            '*',
+        ])) {
+            throw new Error(`Invalid --from selector: ${raw}`);
+        }
+        return { kind: 'dynamic', dynamicSource };
+    }
+    throw new Error(`Invalid --from selector: ${raw}`);
+};
+const parseToSelector = (raw) => {
+    const parts = parseParts(raw);
+    if (parts.length !== 2)
+        throw new Error(`Invalid --to selector: ${raw}`);
+    const scope = parts[0];
+    const privacy = parts[1];
+    if (!isOneOf(scope, ['global', 'env']) ||
+        !isOneOf(privacy, ['public', 'private'])) {
+        throw new Error(`Invalid --to selector: ${raw}`);
+    }
+    return { scope, privacy };
+};
+const wildcardMatch = (v, sel) => sel === '*' || v === sel;
+const getEffectiveProvenanceEntry = (entries) => entries && entries.length ? entries[entries.length - 1] : undefined;
+const matchesFromSelector = (entry, sel) => {
+    switch (entry.kind) {
+        case 'vars':
+            return sel.kind === 'vars';
+        case 'dynamic':
+            return (sel.kind === 'dynamic' &&
+                wildcardMatch(entry.dynamicSource, sel.dynamicSource));
+        case 'file':
+            return (sel.kind === 'file' &&
+                wildcardMatch(entry.scope, sel.scope) &&
+                wildcardMatch(entry.privacy, sel.privacy));
+        case 'config':
+            return (sel.kind === 'config' &&
+                wildcardMatch(entry.configScope, sel.configScope) &&
+                wildcardMatch(entry.scope, sel.scope) &&
+                wildcardMatch(entry.privacy, sel.privacy));
+    }
+};
+/**
+ * Select env values for a secret payload using provenance selectors.
+ *
+ * Notes:
+ * - Iterates keys from provenance (not from dotenv), so keys lacking provenance
+ *   are excluded by default.
+ * - Uses only the effective entry (last entry) for matching.
+ * - Excludes keys whose effective value is undefined, or whose effective entry
+ *   has `op: 'unset'`.
+ */
+const selectEnvByProvenance = (dotenv, provenance, selectors) => {
+    const out = {};
+    for (const [key, entries] of Object.entries(provenance)) {
+        const value = dotenv[key];
+        if (typeof value === 'undefined')
+            continue;
+        const effective = getEffectiveProvenanceEntry(entries);
+        if (!effective)
+            continue;
+        if (effective.op === 'unset')
+            continue;
+        if (selectors.some((s) => matchesFromSelector(effective, s))) {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+
+/**
+ * Requirements addressed:
+ * - Support safe plugin defaults from get-dotenv config under `plugins['aws/secrets']`
+ *   using a schema-typed config (no casts required at call sites).
+ * - CLI flags override config defaults.
+ * - include/exclude are mutually exclusive; unknown keys are ignored at filter time.
+ */
+const secretsPluginConfigSchema = z.object({
+    /**
+     * Default secret name for all `aws secrets` subcommands.
+     *
+     * Supports `$VAR` expansion at action time against `{ ...process.env, ...ctx.dotenv }`.
+     */
+    secretName: z.string().optional(),
+    /**
+     * Default template extension used by `aws secrets pull` when the destination
+     * dotenv file is missing (e.g. `.env.local.template` -\> `.env.local`).
+     */
+    templateExtension: z.string().optional(),
+    /**
+     * Defaults for `aws secrets push`.
+     */
+    push: z
+        .object({
+        /**
+         * Default provenance selectors for determining which loaded keys are
+         * included in the secret payload.
+         *
+         * When omitted, the CLI default is `file:env:private`.
+         */
+        from: z.array(z.string()).optional(),
+        /**
+         * Default include list applied after provenance selection.
+         *
+         * Mutually exclusive with `push.exclude`.
+         */
+        include: z.array(z.string()).optional(),
+        /**
+         * Default exclude list applied after provenance selection.
+         *
+         * Mutually exclusive with `push.include`.
+         */
+        exclude: z.array(z.string()).optional(),
+    })
+        .optional(),
+    /**
+     * Defaults for `aws secrets pull`.
+     */
+    pull: z
+        .object({
+        /**
+         * Default destination selector for `aws secrets pull`.
+         *
+         * Format: `(global|env):(public|private)`, e.g. `env:private`.
+         */
+        to: z.string().optional(),
+        /**
+         * Default include list applied to pulled keys before editing the target
+         * dotenv file.
+         *
+         * Mutually exclusive with `pull.exclude`.
+         */
+        include: z.array(z.string()).optional(),
+        /**
+         * Default exclude list applied to pulled keys before editing the target
+         * dotenv file.
+         *
+         * Mutually exclusive with `pull.include`.
+         */
+        exclude: z.array(z.string()).optional(),
+    })
+        .optional(),
+});
+const resolveIncludeExclude = ({ cliInclude, cliExclude, cfgInclude, cfgExclude, }) => {
+    // CLI overrides config: if either include/exclude is provided on CLI, ignore
+    // config’s include/exclude entirely.
+    const include = cliInclude ?? (cliExclude ? undefined : cfgInclude);
+    const exclude = cliExclude ?? (cliInclude ? undefined : cfgExclude);
+    if (include?.length && exclude?.length) {
+        throw new Error('--exclude and --include are mutually exclusive.');
+    }
+    return { include, exclude };
+};
+
+/**
+ * Requirements addressed:
+ * - Provide `aws secrets pull`.
+ * - For config-backed plugin options, use plugin dynamic options to show
+ *   composed defaults in help output.
+ * - Use get-dotenv precedence semantics for deterministic dotenv editing.
+ * - Replace scope/privacy flags with `--to <scope>:<privacy>`.
+ */
+const registerPullCommand = ({ cli, plugin, }) => {
+    const pull = cli
+        .ns('pull')
+        .description('Update local dotenv from a Secrets Manager secret (env-map).');
+    pull
+        .addOption(plugin.createPluginDynamicOption(pull, '-s, --secret-name <string>', (_helpCfg, pluginCfg) => `secret name (supports $VAR expansion) (default: ${pluginCfg.secretName ?? '$STACK_NAME'})`))
+        .addOption(plugin.createPluginDynamicOption(pull, '-t, --template-extension <string>', (_helpCfg, pluginCfg) => {
+        const def = pluginCfg.templateExtension ?? 'template';
+        return `dotenv template extension used when target file is missing (default: ${def})`;
+    }))
+        .addOption(plugin.createPluginDynamicOption(pull, '--to <scope:privacy>', (_helpCfg, pluginCfg) => {
+        const def = pluginCfg.pull?.to ?? 'env:private';
+        return `destination dotenv selector (global|env):(public|private) (default: ${def})`;
+    }))
+        .addOption(plugin
+        .createPluginDynamicOption(pull, '-e, --exclude <strings...>', (_helpCfg, pluginCfg) => {
+        const { excludeDefault } = describeConfigKeyListDefaults({
+            cfgInclude: pluginCfg.pull?.include,
+            cfgExclude: pluginCfg.pull?.exclude,
+        });
+        return `space-delimited list of keys to exclude from the pulled secret (default: ${excludeDefault})`;
+    })
+        .conflicts('include'))
+        .addOption(plugin
+        .createPluginDynamicOption(pull, '-i, --include <strings...>', (_helpCfg, pluginCfg) => {
+        const { includeDefault } = describeConfigKeyListDefaults({
+            cfgInclude: pluginCfg.pull?.include,
+            cfgExclude: pluginCfg.pull?.exclude,
+        });
+        return `space-delimited list of keys to include from the pulled secret (default: ${includeDefault})`;
+    })
+        .conflicts('exclude'))
+        .action(async (opts, command) => {
+        const logger = console;
+        const ctx = cli.getCtx();
+        const bag = readMergedOptions(command);
+        const rootOpts = getDotenvCliOptions2Options(bag);
+        const cfg = plugin.readConfig(pull);
+        const sdkLogger = bag.debug ? console : silentLogger;
+        const paths = rootOpts.paths ?? ['./'];
+        const dotenvToken = rootOpts.dotenvToken ?? '.env';
+        const privateToken = rootOpts.privateToken ?? 'local';
+        const toRaw = opts.to ?? cfg.pull?.to ?? 'env:private';
+        const to = parseToSelector(toRaw);
+        const envRef = buildExpansionEnv(ctx.dotenv);
+        const secretNameRaw = opts.secretName ?? cfg.secretName ?? '$STACK_NAME';
+        const secretId = expandSecretName(secretNameRaw, envRef);
+        if (!secretId)
+            throw new Error('secret-name is required.');
+        const region = getAwsRegion(ctx);
+        const tools = await AwsSecretsManagerTools.init({
+            clientConfig: region
+                ? { region, logger: sdkLogger }
+                : { logger: sdkLogger },
+        });
+        logger.info(`Pulling secret '${secretId}' from AWS Secrets Manager...`);
+        const rawSecrets = await tools.readEnvSecret({ secretId });
+        const { include, exclude } = resolveIncludeExclude({
+            cliInclude: opts.include,
+            cliExclude: opts.exclude,
+            cfgInclude: cfg.pull?.include,
+            cfgExclude: cfg.pull?.exclude,
+        });
+        const secrets = applyIncludeExclude(rawSecrets, { include, exclude });
+        const templateExtension = opts.templateExtension ?? cfg.templateExtension ?? 'template';
+        const editCommon = {
+            paths,
+            dotenvToken,
+            privateToken,
+            privacy: to.privacy,
+            templateExtension,
+        };
+        const res = to.scope === 'env'
+            ? await editDotenvFile(secrets, {
+                ...editCommon,
+                scope: 'env',
+                env: requireString(bag.env ?? bag.defaultEnv, 'env is required (use --env or defaultEnv).'),
+            })
+            : await editDotenvFile(secrets, {
+                ...editCommon,
+                scope: 'global',
+            });
+        logger.info(`Updated ${res.path}`);
+    });
+};
+
+/**
+ * Requirements addressed:
+ * - Provide `aws secrets push`.
+ * - `push` selects payload keys using effective provenance entry only and
+ *   repeatable `--from <selector>` selectors (default: file:env:private).
+ * - Enforce AWS Secrets Manager SecretString size limit (65,536 bytes).
+ * - Dynamic options must be registered on the command to drive typing + help.
+ */
+const registerPushCommand = ({ cli, plugin, }) => {
+    const push = cli
+        .ns('push')
+        .description('Create or update a Secrets Manager secret from selected loaded keys.');
+    push
+        .addOption(plugin.createPluginDynamicOption(push, '-s, --secret-name <string>', (_helpCfg, pluginCfg) => `secret name (supports $VAR expansion) (default: ${pluginCfg.secretName ?? '$STACK_NAME'})`))
+        // Repeatable: `--from <selector>` may be specified multiple times.
+        .addOption(plugin
+        .createPluginDynamicOption(push, '--from <selector>', (_helpCfg, pluginCfg) => {
+        const def = pluginCfg.push?.from?.length
+            ? pluginCfg.push.from
+            : ['file:env:private'];
+        return `provenance selectors for secret payload keys (default: ${describeDefault(def)})`;
+    })
+        .argParser((value, previous) => [
+        ...(previous ?? []),
+        value,
+    ])
+        .default(Array()))
+        .addOption(plugin
+        .createPluginDynamicOption(push, '-e, --exclude <strings...>', (_helpCfg, pluginCfg) => {
+        const { excludeDefault } = describeConfigKeyListDefaults({
+            cfgInclude: pluginCfg.push?.include,
+            cfgExclude: pluginCfg.push?.exclude,
+        });
+        return `space-delimited list of environment variables to exclude (default: ${excludeDefault})`;
+    })
+        .conflicts('include'))
+        .addOption(plugin
+        .createPluginDynamicOption(push, '-i, --include <strings...>', (_helpCfg, pluginCfg) => {
+        const { includeDefault } = describeConfigKeyListDefaults({
+            cfgInclude: pluginCfg.push?.include,
+            cfgExclude: pluginCfg.push?.exclude,
+        });
+        return `space-delimited list of environment variables to include (default: ${includeDefault})`;
+    })
+        .conflicts('exclude'))
+        .action(async (opts) => {
+        const ctx = cli.getCtx();
+        const cfg = plugin.readConfig(push);
+        const bag = readMergedOptions(push);
+        const sdkLogger = bag.debug ? console : silentLogger;
+        const logger = console;
+        const fromRaw = opts.from?.length
+            ? opts.from
+            : cfg.push?.from?.length
+                ? cfg.push.from
+                : ['file:env:private'];
+        const fromSelectors = fromRaw.map(parseFromSelector);
+        const { include, exclude } = resolveIncludeExclude({
+            cliInclude: opts.include,
+            cliExclude: opts.exclude,
+            cfgInclude: cfg.push?.include,
+            cfgExclude: cfg.push?.exclude,
+        });
+        const envRef = buildExpansionEnv(ctx.dotenv);
+        const secretNameRaw = opts.secretName ?? cfg.secretName ?? '$STACK_NAME';
+        const secretId = expandSecretName(secretNameRaw, envRef);
+        if (!secretId)
+            throw new Error('secret-name is required.');
+        const selected = selectEnvByProvenance(ctx.dotenv, ctx.dotenvProvenance, fromSelectors);
+        const secrets = applyIncludeExclude(selected, { include, exclude });
+        assertBytesWithinSecretsManagerLimit(secrets);
+        const region = getAwsRegion(ctx);
+        const tools = await AwsSecretsManagerTools.init({
+            clientConfig: region
+                ? { region, logger: sdkLogger }
+                : { logger: sdkLogger },
+        });
+        logger.info(`Pushing secret '${secretId}' to AWS Secrets Manager...`);
+        const mode = await tools.upsertEnvSecret({ secretId, value: secrets });
+        logger.info(mode === 'created' ? 'Created.' : 'Updated.');
+    });
+};
+
+/**
+ * Requirements addressed:
+ * - Provide get-dotenv plugin mounted as `aws secrets` with commands:
+ *   - `aws secrets pull`
+ *   - `aws secrets push`
+ *   - `aws secrets delete`
+ * - Keep the plugin adapter thin: command registration is decomposed into
+ *   dedicated modules; core behavior lives outside this file.
+ * - For config-backed plugin options, register dynamic options on the command
+ *   so help reflects composed defaults and option parsing is typed.
+ */
+/**
+ * get-dotenv plugin that provides `aws secrets pull|push|delete`.
+ *
+ * Intended usage: mount under `awsPlugin().use(secretsPlugin())`.
+ */
+const secretsPlugin = () => {
+    const plugin = definePlugin({
+        ns: 'secrets',
+        configSchema: secretsPluginConfigSchema,
+        setup(cli) {
+            cli.description('AWS Secrets Manager helpers (env-map secrets).');
+            registerPullCommand({ cli, plugin });
+            registerPushCommand({ cli, plugin });
+            registerDeleteCommand({ cli, plugin });
+        },
+    });
+    return plugin;
+};
+
+/**
+ * Requirements addressed:
+ * - Replace sample CLI with a get-dotenv CLI alias `aws-secrets-manager-tools`.
+ * - Duplicate default get-dotenv CLI composition, but omit awsWhoamiPlugin.
+ * - Mount secrets plugin under aws: `awsPlugin().use(secretsPlugin())`.
+ */
+await createCli({
+    alias: 'aws-secrets-manager-tools',
+    compose: (program) => program
+        .use(cmdPlugin({ asDefault: true, optionAlias: '-c, --cmd <command...>' }))
+        .use(batchPlugin())
+        .use(awsPlugin().use(secretsPlugin()))
+        .use(initPlugin()),
+})();