env-secrets 0.4.0 → 0.5.0

package/AGENTS.md

@@ -133,6 +133,9 @@ yarn test:unit:coverage # Run tests with coverage
 4. Ensure all CI checks pass
 5. Submit a pull request with a clear description
 6. Always request a GitHub Copilot review on every new pull request
+7. After requesting Copilot review, wait 5 minutes and check for review comments
+8. If no Copilot review is present yet, wait another 5 minutes and check again
+9. Create a plan to address Copilot feedback, but evaluate each suggestion critically and do not accept recommendations blindly
 
 ## Development Environment
 

package/README.md

@@ -103,7 +103,7 @@ env-secrets aws -s my-app-secrets -r us-east-1 -- node app.js
 - `-o, --output <file>` (optional): Output secrets to a file instead of injecting into environment variables. File will be created with 0400 permissions and will not overwrite existing files
 - `-- <program-to-run>`: The program to run with the injected environment variables (only used when `-o` is not specified)
 
-For `aws secret` management subcommands (`create`, `update`, `list`, `get`, `delete`), use:
+For `aws secret` management subcommands (`create`, `update`, `append`, `remove`, `upsert`/`import`, `list`, `get`, `delete`), use:
 
 - `-r, --region <region>` to target a specific region
 - `-p, --profile <profile>` to select credentials profile
@@ -111,6 +111,9 @@ For `aws secret` management subcommands (`create`, `update`, `list`, `get`, `del
 
 These options are honored consistently on `aws secret` subcommands.
 
+`env-secrets aws -s` is for fetching/injecting secret values into a child process.  
+`env-secrets aws secret ...` is for lifecycle management commands (`create`, `update`, `append`, `remove`, `upsert`/`import`, `list`, `get`, `delete`).
+
 #### Examples
 
 1. **Create a secret using AWS CLI:**
@@ -217,6 +220,42 @@ env-secrets aws -s my-secret -r us-east-1 -o secrets.env
 # Error: File secrets.env already exists and will not be overwritten
 ```
 
+10. **Load secrets into your current shell session:**
+
+```bash
+# Write export statements to a file
+env-secrets aws -s my-secret -r us-east-1 -o secrets.env
+
+# Load into current shell
+source secrets.env
+```
+
+Note: `env-secrets aws -s ... -- <command>` injects secrets into the spawned child process only.  
+To affect your current shell, use file output and `source` it.
+
+11. **Upsert secrets from a local env file:**
+
+```bash
+# Supported line formats:
+# export NAME=secret1
+# NAME=secret1
+env-secrets aws secret upsert --file .env --name app/dev --output json
+
+# Creates/updates a single secret named app/dev
+# with SecretString like:
+# {"NAME":"secret1"}
+```
+
+12. **Append/remove keys on an existing JSON secret:**
+
+```bash
+# Add or overwrite one key
+env-secrets aws secret append -n app/dev --key JIRA_EMAIL_TOKEN -v blah --output json
+
+# Remove one or more keys
+env-secrets aws secret remove -n app/dev --key API_KEY --key OLD_TOKEN --output json
+```
+
 ## Security Considerations
 
 - 🔐 **Credential Management**: The tool respects AWS credential precedence (environment variables, IAM roles, profiles)

package/__e2e__/index.test.ts

@@ -8,7 +8,8 @@ import {
   createTestProfile,
   restoreTestProfile,
   TestSecret,
-  CreatedSecret
+  CreatedSecret,
+  execAwslocalCommand
 } from './utils/test-utils';
 import { debugLog } from './utils/debug-logger';
 import * as fs from 'fs';
@@ -417,6 +418,97 @@ describe('End-to-End Tests', () => {
         expect(deleteResult.code).toBe(0);
       });
 
+      test('should append and remove keys on a JSON secret', async () => {
+        const secretName = `managed-secret-append-remove-${Date.now()}`;
+        const tempFile = path.join(
+          os.tmpdir(),
+          `env-secrets-append-remove-${Date.now()}.env`
+        );
+        fs.writeFileSync(tempFile, 'API_KEY=first');
+
+        const createResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'upsert',
+            '--file',
+            tempFile,
+            '--name',
+            secretName,
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(createResult.code).toBe(0);
+
+        const appendResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'append',
+            '-n',
+            secretName,
+            '--key',
+            'JIRA_EMAIL_TOKEN',
+            '-v',
+            'blah',
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(appendResult.code).toBe(0);
+
+        const afterAppend = await execAwslocalCommand(
+          `awslocal secretsmanager get-secret-value --secret-id "${secretName}" --region us-east-1 --query SecretString --output text`,
+          getLocalStackEnv()
+        );
+        expect(JSON.parse(afterAppend.stdout.trim())).toEqual({
+          API_KEY: 'first',
+          JIRA_EMAIL_TOKEN: 'blah'
+        });
+
+        const removeResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'remove',
+            '-n',
+            secretName,
+            '--key',
+            'API_KEY',
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(removeResult.code).toBe(0);
+
+        const afterRemove = await execAwslocalCommand(
+          `awslocal secretsmanager get-secret-value --secret-id "${secretName}" --region us-east-1 --query SecretString --output text`,
+          getLocalStackEnv()
+        );
+        expect(JSON.parse(afterRemove.stdout.trim())).toEqual({
+          JIRA_EMAIL_TOKEN: 'blah'
+        });
+
+        const deleteResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'delete',
+            '-n',
+            secretName,
+            '--force-delete-without-recovery',
+            '--yes'
+          ],
+          getLocalStackEnv()
+        );
+        expect(deleteResult.code).toBe(0);
+        cleanupTempFile(tempFile);
+      });
+
       test('should require confirmation for delete', async () => {
         const secret = await createTestSecret({
           name: `managed-secret-confirm-${Date.now()}`,
@@ -485,6 +577,102 @@ describe('End-to-End Tests', () => {
         }>;
         expect(eastRows).toEqual([]);
       });
+
+      test('should upsert secrets from env file', async () => {
+        const secretName = `e2e-upsert-${Date.now()}`;
+        const tempFile = path.join(
+          os.tmpdir(),
+          `env-secrets-upsert-${Date.now()}.env`
+        );
+
+        fs.writeFileSync(
+          tempFile,
+          ['# sample', 'export API_KEY=first', 'DB_URL = postgres://one'].join(
+            '\n'
+          )
+        );
+
+        const firstRun = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'upsert',
+            '--file',
+            tempFile,
+            '--name',
+            secretName,
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(firstRun.code).toBe(0);
+        const firstJson = JSON.parse(firstRun.stdout) as {
+          summary: { created: number; updated: number; skipped: number };
+        };
+        expect(firstJson.summary.created).toBe(1);
+        expect(firstJson.summary.updated).toBe(0);
+
+        const firstSecret = await execAwslocalCommand(
+          `awslocal secretsmanager get-secret-value --secret-id "${secretName}" --region us-east-1 --query SecretString --output text`,
+          getLocalStackEnv()
+        );
+        expect(JSON.parse(firstSecret.stdout.trim())).toEqual({
+          API_KEY: 'first',
+          DB_URL: 'postgres://one'
+        });
+
+        fs.writeFileSync(
+          tempFile,
+          ['export API_KEY=second', 'DB_URL=postgres://two'].join('\n')
+        );
+
+        const secondRun = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'import',
+            '--file',
+            tempFile,
+            '--name',
+            secretName,
+            '--output',
+            'json'
+          ],
+          getLocalStackEnv()
+        );
+        expect(secondRun.code).toBe(0);
+        const secondJson = JSON.parse(secondRun.stdout) as {
+          summary: { created: number; updated: number; skipped: number };
+        };
+        expect(secondJson.summary.created).toBe(0);
+        expect(secondJson.summary.updated).toBe(1);
+        expect(secondJson.summary.skipped).toBe(0);
+
+        const secondSecret = await execAwslocalCommand(
+          `awslocal secretsmanager get-secret-value --secret-id "${secretName}" --region us-east-1 --query SecretString --output text`,
+          getLocalStackEnv()
+        );
+        expect(JSON.parse(secondSecret.stdout.trim())).toEqual({
+          API_KEY: 'second',
+          DB_URL: 'postgres://two'
+        });
+
+        const deleteResult = await cliWithEnv(
+          [
+            'aws',
+            'secret',
+            'delete',
+            '-n',
+            secretName,
+            '--force-delete-without-recovery',
+            '--yes'
+          ],
+          getLocalStackEnv()
+        );
+        expect(deleteResult.code).toBe(0);
+        cleanupTempFile(tempFile);
+      });
     });
   });
 });

package/__tests__/cli/helpers.test.ts

@@ -1,7 +1,11 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import { PassThrough } from 'node:stream';
 
 import {
   asOutputFormat,
+  parseEnvSecrets,
   parseRecoveryDays,
   printData,
   readStdin,
@@ -73,7 +77,29 @@ describe('cli/helpers', () => {
 
   it('rejects when both --value and --value-stdin are used', async () => {
     await expect(resolveSecretValue('inline', true)).rejects.toThrow(
-      'Use either --value or --value-stdin, not both.'
+      'Use only one secret value source: --value, --value-stdin, or --file.'
+    );
+  });
+
+  it('rejects when --file and --value-stdin are used together', async () => {
+    await expect(
+      resolveSecretValue(undefined, true, './secret.txt')
+    ).rejects.toThrow(
+      'Use only one secret value source: --value, --value-stdin, or --file.'
+    );
+  });
+
+  it('rejects when --value and --file are used together', async () => {
+    await expect(
+      resolveSecretValue('inline', false, './secret.txt')
+    ).rejects.toThrow(
+      'Use only one secret value source: --value, --value-stdin, or --file.'
+    );
+  });
+
+  it('treats explicit empty --value as provided for mutual exclusion', async () => {
+    await expect(resolveSecretValue('', false, './secret.txt')).rejects.toThrow(
+      'Use only one secret value source: --value, --value-stdin, or --file.'
     );
   });
 
@@ -94,6 +120,68 @@ describe('cli/helpers', () => {
     });
   });
 
+  it('reads secret value from file and strips one trailing newline', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'env-secrets-test-'));
+    const file = join(dir, 'secret.txt');
+    writeFileSync(file, 'file-secret\n');
+
+    await expect(resolveSecretValue(undefined, false, file)).resolves.toBe(
+      'file-secret'
+    );
+
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('parses env secrets from KEY=value and export KEY=value formats', () => {
+    const parsed = parseEnvSecrets(
+      [
+        '# comment',
+        'export API_KEY=secret1',
+        'DATABASE_URL=postgres://db',
+        ''
+      ].join('\n')
+    );
+
+    expect(parsed.entries).toEqual([
+      { key: 'API_KEY', value: 'secret1', line: 2 },
+      { key: 'DATABASE_URL', value: 'postgres://db', line: 3 }
+    ]);
+    expect(parsed.skipped).toEqual([]);
+  });
+
+  it('handles whitespace around equals in env file', () => {
+    const parsed = parseEnvSecrets('  export   NAME =  secret1  ');
+
+    expect(parsed.entries).toEqual([
+      { key: 'NAME', value: 'secret1', line: 1 }
+    ]);
+  });
+
+  it('skips duplicate keys when parsing env file', () => {
+    const parsed = parseEnvSecrets(['A=1', 'A=2'].join('\n'));
+
+    expect(parsed.entries).toEqual([{ key: 'A', value: '1', line: 1 }]);
+    expect(parsed.skipped).toEqual([
+      { key: 'A', line: 2, reason: 'duplicate key' }
+    ]);
+  });
+
+  it('throws clear error for malformed env lines', () => {
+    expect(() => parseEnvSecrets('NOT_A_VALID_LINE')).toThrow(
+      'Malformed env line 1'
+    );
+    expect(() => parseEnvSecrets('BAD=secret')).not.toThrow();
+  });
+
+  it('does not include raw line content in malformed env errors', () => {
+    expect(() => parseEnvSecrets('export SECRET_ONLY')).toThrow(
+      'Expected KEY=value or export KEY=value.'
+    );
+    expect(() => parseEnvSecrets('export SECRET_ONLY')).not.toThrow(
+      /SECRET_ONLY/
+    );
+  });
+
   it('prefers explicit aws scope options over global options', () => {
     const command = {
       optsWithGlobals: () => ({

package/__tests__/vaults/secretsmanager-admin.test.ts

@@ -12,6 +12,7 @@ jest.mock('@aws-sdk/client-secrets-manager', () => {
     })),
     CreateSecretCommand: jest.fn().mockImplementation((input) => ({ input })),
     UpdateSecretCommand: jest.fn().mockImplementation((input) => ({ input })),
+    GetSecretValueCommand: jest.fn().mockImplementation((input) => ({ input })),
     ListSecretsCommand: jest.fn().mockImplementation((input) => ({ input })),
     DescribeSecretCommand: jest.fn().mockImplementation((input) => ({ input })),
     DeleteSecretCommand: jest.fn().mockImplementation((input) => ({ input }))
@@ -37,6 +38,8 @@ import {
   listSecrets,
   getSecretMetadata,
   deleteSecret,
+  secretExists,
+  getSecretString,
   validateSecretName
 } from '../../src/vaults/secretsmanager-admin';
 
@@ -278,6 +281,46 @@ describe('secretsmanager-admin', () => {
     expect(Object.keys(result)).not.toContain('secretString');
   });
 
+  it('returns true when secret exists', async () => {
+    mockSecretsManagerSend.mockResolvedValueOnce({
+      Name: 'app/existing'
+    });
+
+    await expect(
+      secretExists({ name: 'app/existing', region: 'us-east-1' })
+    ).resolves.toBe(true);
+  });
+
+  it('returns false when secret does not exist', async () => {
+    mockSecretsManagerSend.mockRejectedValueOnce({
+      name: 'ResourceNotFoundException'
+    });
+
+    await expect(
+      secretExists({ name: 'app/missing', region: 'us-east-1' })
+    ).resolves.toBe(false);
+  });
+
+  it('gets current secret string value', async () => {
+    mockSecretsManagerSend.mockResolvedValueOnce({
+      SecretString: '{"API_KEY":"abc"}'
+    });
+
+    await expect(
+      getSecretString({ name: 'app/existing', region: 'us-east-1' })
+    ).resolves.toBe('{"API_KEY":"abc"}');
+  });
+
+  it('rejects binary/non-string secrets for append/remove workflows', async () => {
+    mockSecretsManagerSend.mockResolvedValueOnce({
+      SecretBinary: new Uint8Array([1, 2, 3])
+    });
+
+    await expect(
+      getSecretString({ name: 'app/existing', region: 'us-east-1' })
+    ).rejects.toThrow('cannot be edited with append/remove');
+  });
+
   it('deletes secret with recovery options', async () => {
     const mockCredentials = jest.fn().mockResolvedValue({
       accessKeyId: 'default',

package/dist/cli/helpers.js

@@ -9,7 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveAwsScope = exports.resolveSecretValue = exports.readStdin = exports.parseRecoveryDays = exports.printData = exports.renderTable = exports.asOutputFormat = void 0;
+exports.resolveAwsScope = exports.parseEnvSecretsFile = exports.parseEnvSecrets = exports.resolveSecretValue = exports.readStdin = exports.parseRecoveryDays = exports.printData = exports.renderTable = exports.asOutputFormat = void 0;
+const promises_1 = require("node:fs/promises");
 const asOutputFormat = (value) => {
     if (value !== 'json' && value !== 'table') {
         throw new Error(`Invalid output format "${value}". Use "json" or "table".`);
@@ -81,9 +82,14 @@ const readStdin = (stdin = process.stdin) => __awaiter(void 0, void 0, void 0, f
     });
 });
 exports.readStdin = readStdin;
-const resolveSecretValue = (value, valueStdin) => __awaiter(void 0, void 0, void 0, function* () {
-    if (value && valueStdin) {
-        throw new Error('Use either --value or --value-stdin, not both.');
+const resolveSecretValue = (value, valueStdin, valueFile) => __awaiter(void 0, void 0, void 0, function* () {
+    const providedSources = [
+        value !== undefined,
+        valueStdin === true,
+        valueFile !== undefined
+    ].filter(Boolean).length;
+    if (providedSources > 1) {
+        throw new Error('Use only one secret value source: --value, --value-stdin, or --file.');
     }
     if (valueStdin) {
         if (process.stdin.isTTY) {
@@ -91,9 +97,65 @@ const resolveSecretValue = (value, valueStdin) => __awaiter(void 0, void 0, void
         }
         return yield (0, exports.readStdin)();
     }
+    if (valueFile) {
+        const content = yield (0, promises_1.readFile)(valueFile, 'utf8');
+        return content.replace(/\r?\n$/, '');
+    }
     return value;
 });
 exports.resolveSecretValue = resolveSecretValue;
+const parseEnvLine = (line, lineNumber) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+        return undefined;
+    }
+    const candidate = trimmed.startsWith('export ')
+        ? trimmed.slice('export '.length).trimStart()
+        : trimmed;
+    const separatorIndex = candidate.indexOf('=');
+    if (separatorIndex <= 0) {
+        throw new Error(`Malformed env line ${lineNumber}. Expected KEY=value or export KEY=value.`);
+    }
+    const key = candidate.slice(0, separatorIndex).trim();
+    const value = candidate.slice(separatorIndex + 1).trim();
+    if (!key) {
+        throw new Error(`Malformed env line ${lineNumber}. Expected KEY=value or export KEY=value.`);
+    }
+    return { key, value };
+};
+const parseEnvSecrets = (content) => {
+    const seenKeys = new Set();
+    const entries = [];
+    const skipped = [];
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const parsed = parseEnvLine(lines[index], index + 1);
+        if (!parsed) {
+            continue;
+        }
+        if (seenKeys.has(parsed.key)) {
+            skipped.push({
+                key: parsed.key,
+                line: index + 1,
+                reason: 'duplicate key'
+            });
+            continue;
+        }
+        seenKeys.add(parsed.key);
+        entries.push({
+            key: parsed.key,
+            value: parsed.value,
+            line: index + 1
+        });
+    }
+    return { entries, skipped };
+};
+exports.parseEnvSecrets = parseEnvSecrets;
+const parseEnvSecretsFile = (path) => __awaiter(void 0, void 0, void 0, function* () {
+    const content = yield (0, promises_1.readFile)(path, 'utf8');
+    return (0, exports.parseEnvSecrets)(content);
+});
+exports.parseEnvSecretsFile = parseEnvSecretsFile;
 const resolveAwsScope = (options, command) => {
     var _a;
     const globalOptions = ((_a = command === null || command === void 0 ? void 0 : command.optsWithGlobals) === null || _a === void 0 ? void 0 : _a.call(command)) || {};