env-secrets 0.4.0 → 0.5.1

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)
@@ -500,7 +539,7 @@ npm run test:e2e
 npm run test:e2e:coverage
 
 # Run specific e2e test
-yarn build && npx jest --config jest.e2e.config.js __e2e__/index.test.ts -t "test name"
+yarn build && npx jest --config jest.e2e.config.js __e2e__/aws-get-secrets-args.test.ts -t "test name"
 ```
 
 #### E2E Test Features

package/__e2e__/README.md

@@ -75,7 +75,7 @@ npm run test:e2e:coverage
 
 ```bash
 npm run build
-npx jest --config jest.e2e.config.js __e2e__/index.test.ts
+npx jest --config jest.e2e.config.js __e2e__/aws-get-secrets-args.test.ts
 ```
 
 ### Run Tests with Debug Output

package/__e2e__/aws-cli-help.test.ts

@@ -0,0 +1,23 @@
+import { cli } from './utils/test-utils';
+
+describe('CLI Help Commands', () => {
+  test('should show general help', async () => {
+    const result = await cli(['-h']);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('env-secrets');
+    expect(result.stdout).toContain('pull secrets from vaults');
+  });
+
+  test('should show AWS command help', async () => {
+    const result = await cli(['aws', '-h']);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain('get secrets from AWS secrets manager');
+    expect(result.stdout).toContain('--secret');
+  });
+
+  test('should show version', async () => {
+    const result = await cli(['--version']);
+    expect(result.code).toBe(0);
+    expect(result.stdout).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});

package/__e2e__/aws-exec-args.test.ts

@@ -0,0 +1,44 @@
+import { cliWithEnv } from './utils/test-utils';
+import { registerAwsE2eContext } from './utils/aws-e2e-context';
+
+describe('AWS Program Execution CLI Args', () => {
+  const { createTestSecret, getLocalStackEnv } = registerAwsE2eContext();
+
+  test('should execute program with injected environment variables', async () => {
+    const secret = await createTestSecret({
+      name: `test-secret-exec-${Date.now()}`,
+      value:
+        '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+      description: 'Secret for program execution test'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName, 'echo', '$API_KEY'],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+
+    const envVars = JSON.parse(result.stdout.trim()) as Record<string, string>;
+    expect(envVars.API_KEY).toBe('secret123');
+    expect(envVars.DATABASE_URL).toBe('postgres://localhost:5432/test');
+  });
+
+  test('should handle program execution errors gracefully', async () => {
+    const secret = await createTestSecret({
+      name: `test-secret-error-${Date.now()}`,
+      value: '{"API_KEY": "secret123"}',
+      description: 'Secret for error handling test'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName, 'nonexistent-command'],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+
+    const envVars = JSON.parse(result.stdout.trim()) as Record<string, string>;
+    expect(envVars.API_KEY).toBe('secret123');
+  });
+});

package/__e2e__/aws-get-secrets-args.test.ts

@@ -0,0 +1,156 @@
+import { cliWithEnv } from './utils/test-utils';
+import { registerAwsE2eContext } from './utils/aws-e2e-context';
+
+describe('AWS Get Secret CLI Args', () => {
+  const { createTestSecret, getLocalStackEnv } = registerAwsE2eContext();
+
+  test('should retrieve basic JSON secret', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-basic',
+      value:
+        '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+      description: 'Basic test secret with API key and database URL'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should retrieve simple string secret', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-simple',
+      value: 'simple-string-value',
+      description: 'Simple string secret'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should retrieve complex JSON secret', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-complex',
+      value:
+        '{"NESTED": {"KEY": "value"}, "ARRAY": [1, 2, 3], "BOOLEAN": true, "NUMBER": 42}',
+      description: 'Complex JSON secret'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should retrieve secret with special characters', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-special-chars',
+      value:
+        '{"PASSWORD": "p@ssw0rd!#$%", "URL": "https://api.example.com/v1?key=value&other=test"}',
+      description: 'Secret with special characters'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should handle non-existent secret', async () => {
+    const result = await cliWithEnv(
+      ['aws', '-s', 'non-existent-secret'],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toContain('non-existent-secret not found');
+  });
+
+  test('should work with custom region', async () => {
+    const secret = await createTestSecret(
+      {
+        name: `test-secret-region-${Date.now()}`,
+        value:
+          '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+        description: 'Basic test secret for us-west-2'
+      },
+      'us-west-2'
+    );
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName, '-r', 'us-west-2'],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should retrieve secret using default profile', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-profile',
+      value:
+        '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+      description: 'Secret for profile test'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should retrieve secret using custom profile', async () => {
+    const secret = await createTestSecret({
+      name: 'test-secret-profile-custom',
+      value:
+        '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+      description: 'Secret for custom profile test'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName, '-p', 'env-secrets-test'],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  test('should handle invalid AWS credentials', async () => {
+    const result = await cliWithEnv(
+      ['aws', '-s', 'test-secret-basic'],
+      getLocalStackEnv({
+        AWS_ACCESS_KEY_ID: 'invalid',
+        AWS_SECRET_ACCESS_KEY: 'invalid'
+      })
+    );
+
+    expect(result.code).toBe(0);
+  });
+
+  test('should handle missing secret parameter', async () => {
+    const result = await cliWithEnv(['aws'], getLocalStackEnv());
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('Missing required option --secret');
+  });
+});

package/__e2e__/aws-output-file-args.test.ts

@@ -0,0 +1,65 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import {
+  cliWithEnv,
+  createTempFile,
+  cleanupTempFile
+} from './utils/test-utils';
+import { registerAwsE2eContext } from './utils/aws-e2e-context';
+
+describe('AWS Output File CLI Args', () => {
+  const { createTestSecret, getLocalStackEnv } = registerAwsE2eContext();
+
+  test('should write secrets to file', async () => {
+    const secret = await createTestSecret({
+      name: `test-secret-file-${Date.now()}`,
+      value:
+        '{"API_KEY": "secret123", "DATABASE_URL": "postgres://localhost:5432/test"}',
+      description: 'Secret for file output test'
+    });
+
+    const tempFile = path.join(
+      os.tmpdir(),
+      `env-secrets-test-${Date.now()}.env`
+    );
+
+    const result = await cliWithEnv(
+      ['aws', '-s', secret.prefixedName, '-o', tempFile],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(0);
+    expect(result.stdout).toContain(`Secrets written to ${tempFile}`);
+
+    const fileContent = fs.readFileSync(tempFile, 'utf8');
+    expect(fileContent).toContain('API_KEY=secret123');
+    expect(fileContent).toContain(
+      'DATABASE_URL=postgres://localhost:5432/test'
+    );
+
+    cleanupTempFile(tempFile);
+  });
+
+  test('should not overwrite existing file', async () => {
+    const tempFile = createTempFile('existing content');
+
+    try {
+      const result = await cliWithEnv(
+        ['aws', '-s', 'test-secret-basic', '-o', tempFile],
+        getLocalStackEnv()
+      );
+
+      expect(result.code).toBe(1);
+      expect(result.stderr).toContain(
+        'already exists and will not be overwritten'
+      );
+
+      const fileContent = fs.readFileSync(tempFile, 'utf8');
+      expect(fileContent).toBe('existing content');
+    } finally {
+      cleanupTempFile(tempFile);
+    }
+  });
+});

package/__e2e__/aws-secret-lifecycle.test.ts

@@ -0,0 +1,257 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+import {
+  cliWithEnv,
+  cliWithEnvAndStdin,
+  cleanupTempFile
+} from './utils/test-utils';
+import { registerAwsE2eContext } from './utils/aws-e2e-context';
+
+describe('AWS Secret Subcommand Lifecycle Args', () => {
+  const { createTestSecret, getLocalStackEnv } = registerAwsE2eContext();
+
+  test('should create, list, get, and delete a secret', async () => {
+    const secretName = `e2e-managed-secret-${Date.now()}`;
+
+    const createResult = await cliWithEnv(
+      ['aws', 'secret', 'create', '-n', secretName, '-v', 'initial-value'],
+      getLocalStackEnv()
+    );
+
+    expect(createResult.code).toBe(0);
+    expect(createResult.stdout).toContain(secretName);
+
+    const listResult = await cliWithEnv(
+      ['aws', 'secret', 'list', '--prefix', 'e2e-managed-secret-'],
+      getLocalStackEnv()
+    );
+    expect(listResult.code).toBe(0);
+    expect(listResult.stdout).toContain(secretName);
+
+    const getResult = await cliWithEnv(
+      ['aws', 'secret', 'get', '-n', secretName],
+      getLocalStackEnv()
+    );
+    expect(getResult.code).toBe(0);
+    expect(getResult.stdout).toContain(secretName);
+    expect(getResult.stdout).not.toContain('initial-value');
+
+    const deleteResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'delete',
+        '-n',
+        secretName,
+        '--force-delete-without-recovery',
+        '--yes'
+      ],
+      getLocalStackEnv()
+    );
+    expect(deleteResult.code).toBe(0);
+  });
+
+  test('should update secret value from stdin', async () => {
+    const secret = await createTestSecret({
+      name: `managed-secret-stdin-${Date.now()}`,
+      value: 'initial-value',
+      description: 'Secret for stdin update test'
+    });
+
+    const updateResult = await cliWithEnvAndStdin(
+      ['aws', 'secret', 'update', '-n', secret.prefixedName, '--value-stdin'],
+      getLocalStackEnv(),
+      'stdin-updated-value'
+    );
+
+    expect(updateResult.code).toBe(0);
+    expect(updateResult.stderr).toBe('');
+
+    const deleteResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'delete',
+        '-n',
+        secret.prefixedName,
+        '--force-delete-without-recovery',
+        '--yes'
+      ],
+      getLocalStackEnv()
+    );
+    expect(deleteResult.code).toBe(0);
+  });
+
+  test('should create from a single-line env file and retrieve via aws -s', async () => {
+    const secretName = `managed-secret-create-single-file-${Date.now()}`;
+    const tempFile = path.join(
+      os.tmpdir(),
+      `env-secrets-create-single-${Date.now()}.env`
+    );
+    fs.writeFileSync(tempFile, 'GITHUB_PAT=github_pat_single_line');
+
+    const createResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'create',
+        '--file',
+        tempFile,
+        '--name',
+        secretName,
+        '--output',
+        'json'
+      ],
+      getLocalStackEnv()
+    );
+    expect(createResult.code).toBe(0);
+
+    const retrieveResult = await cliWithEnv(
+      ['aws', '-s', secretName, 'echo', '$GITHUB_PAT'],
+      getLocalStackEnv()
+    );
+    expect(retrieveResult.code).toBe(0);
+    const envVars = JSON.parse(retrieveResult.stdout.trim()) as Record<
+      string,
+      string
+    >;
+    expect(envVars.GITHUB_PAT).toBe('github_pat_single_line');
+
+    const deleteResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'delete',
+        '-n',
+        secretName,
+        '--force-delete-without-recovery',
+        '--yes'
+      ],
+      getLocalStackEnv()
+    );
+    expect(deleteResult.code).toBe(0);
+    cleanupTempFile(tempFile);
+  });
+
+  test('should create from a multi-line env file and retrieve via aws -s', async () => {
+    const secretName = `managed-secret-create-multi-file-${Date.now()}`;
+    const tempFile = path.join(
+      os.tmpdir(),
+      `env-secrets-create-multi-${Date.now()}.env`
+    );
+    fs.writeFileSync(
+      tempFile,
+      ['GITHUB_PAT=github_pat_multi_line', 'API_URL=https://example.com'].join(
+        '\n'
+      )
+    );
+
+    const createResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'create',
+        '--file',
+        tempFile,
+        '--name',
+        secretName,
+        '--output',
+        'json'
+      ],
+      getLocalStackEnv()
+    );
+    expect(createResult.code).toBe(0);
+
+    const retrieveResult = await cliWithEnv(
+      ['aws', '-s', secretName, 'echo', '$GITHUB_PAT'],
+      getLocalStackEnv()
+    );
+    expect(retrieveResult.code).toBe(0);
+    const envVars = JSON.parse(retrieveResult.stdout.trim()) as Record<
+      string,
+      string
+    >;
+    expect(envVars.GITHUB_PAT).toBe('github_pat_multi_line');
+    expect(envVars.API_URL).toBe('https://example.com');
+
+    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()}`,
+      value: 'value',
+      description: 'Secret for delete confirmation test'
+    });
+
+    const result = await cliWithEnv(
+      ['aws', 'secret', 'delete', '-n', secret.prefixedName],
+      getLocalStackEnv()
+    );
+
+    expect(result.code).toBe(1);
+    expect(result.stderr).toContain('requires --yes confirmation');
+  });
+
+  test('should honor region flag for secret list across multiple regions', async () => {
+    const secret = await createTestSecret(
+      {
+        name: `managed-secret-multi-region-${Date.now()}`,
+        value: '{"region":"us-west-2"}',
+        description: 'Secret used for region isolation test'
+      },
+      'us-west-2'
+    );
+
+    const westResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'list',
+        '--prefix',
+        secret.prefixedName,
+        '-r',
+        'us-west-2',
+        '--output',
+        'json'
+      ],
+      getLocalStackEnv()
+    );
+    expect(westResult.code).toBe(0);
+    const westRows = JSON.parse(westResult.stdout) as Array<{ name: string }>;
+    expect(westRows.some((row) => row.name === secret.prefixedName)).toBe(true);
+
+    const eastResult = await cliWithEnv(
+      [
+        'aws',
+        'secret',
+        'list',
+        '--prefix',
+        secret.prefixedName,
+        '-r',
+        'us-east-1',
+        '--output',
+        'json'
+      ],
+      getLocalStackEnv()
+    );
+    expect(eastResult.code).toBe(0);
+    const eastRows = JSON.parse(eastResult.stdout) as Array<{ name: string }>;
+    expect(eastRows).toEqual([]);
+  });
+});