env-secrets 0.3.3 → 0.5.0

package/AGENTS.md

@@ -51,7 +51,7 @@ Always run quaity checks after creating or modifing files
 ### Testing Strategy
 
 Always run unit tests after creating or modifying files.  
-Always run end to end tests before pushing code to a remote git repository.
+Always start Docker Compose LocalStack and run end to end tests before pushing code to a remote git repository.
 
 - **Unit Tests**: Jest framework, located in `__tests__/`
 - **E2E Tests**: Located in `__e2e__/`
@@ -60,6 +60,7 @@ Always run end to end tests before pushing code to a remote git repository.
   - `yarn test` - runs all tests
   - `yarn test:unit` - runs unit tests only
   - `yarn test:e2e` - builds and runs e2e tests
+  - `docker compose up -d localstack` - start LocalStack for e2e tests
 
 ## Project Structure
 
@@ -120,8 +121,9 @@ yarn test:unit:coverage # Run tests with coverage
 
 1. Run `yarn prettier:fix && yarn lint` to ensure code quality
 2. Run `yarn test` to ensure all tests pass
-3. Update tests for new features or bug fixes
-4. Update documentation if needed
+3. Run `docker compose up -d localstack` and then `yarn test:e2e` before pushing
+4. Update tests for new features or bug fixes
+5. Update documentation if needed
 
 ### Pull Request Process
 
@@ -130,6 +132,10 @@ yarn test:unit:coverage # Run tests with coverage
 3. Add tests for new functionality
 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
 
@@ -138,6 +144,8 @@ yarn test:unit:coverage # Run tests with coverage
 - Node.js 20.0.0 or higher (see .nvmrc)
 - Yarn package manager
 - AWS CLI (for testing AWS integration)
+- Homebrew (macOS/Linux) with `awscli-local` installed:
+  - `brew install awscli-local`
 
 ### Setup
 
@@ -145,5 +153,6 @@ yarn test:unit:coverage # Run tests with coverage
 git clone https://github.com/markcallen/env-secrets.git
 cd env-secrets
 yarn install
+brew install awscli-local
 yarn build
 ```

package/README.md

@@ -103,6 +103,17 @@ 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`, `append`, `remove`, `upsert`/`import`, `list`, `get`, `delete`), use:
+
+- `-r, --region <region>` to target a specific region
+- `-p, --profile <profile>` to select credentials profile
+- `--output <format>` for `json` or `table`
+
+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:**
@@ -209,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)
@@ -459,11 +506,8 @@ The end-to-end tests use LocalStack to emulate AWS Secrets Manager and test the
 1. **Install awslocal** (required for e2e tests):
 
    ```bash
-   # Using pip (recommended)
-   pip install awscli-local
-
-   # Or using npm
-   npm install -g awscli-local
+   # macOS/Linux (recommended)
+   brew install awscli-local
    ```
 
 2. **Start LocalStack**:
@@ -508,15 +552,15 @@ The end-to-end test suite includes:
 - **Program Execution**: Tests for executing programs with injected environment variables
 - **Error Handling**: Tests for various error scenarios and edge cases
 - **AWS Profile Support**: Tests for both default and custom AWS profiles
-- **Region Support**: Tests for different AWS regions
+- **Region Support**: Tests for different AWS regions, including multi-region `aws secret list` isolation checks
 
 #### Troubleshooting E2E Tests
 
 **awslocal not found**:
 
 ```bash
-# Install awslocal
-pip install awscli-local
+# Install awslocal (macOS/Linux)
+brew install awscli-local
 
 # Verify installation
 awslocal --version

package/__e2e__/README.md

@@ -33,11 +33,8 @@ localstack start
 The tests require `awslocal` to be installed, which is a wrapper around AWS CLI that automatically points to LocalStack:
 
 ```bash
-# Install awslocal using pip (recommended)
-pip install awscli-local
-
-# Or using npm
-npm install -g awscli-local
+# Install awslocal (macOS/Linux recommended)
+brew install awscli-local
 
 # Verify installation
 awslocal --version

package/__e2e__/index.test.ts

@@ -2,12 +2,14 @@ import {
   LocalStackHelper,
   cli,
   cliWithEnv,
+  cliWithEnvAndStdin,
   createTempFile,
   cleanupTempFile,
   createTestProfile,
   restoreTestProfile,
   TestSecret,
-  CreatedSecret
+  CreatedSecret,
+  execAwslocalCommand
 } from './utils/test-utils';
 import { debugLog } from './utils/debug-logger';
 import * as fs from 'fs';
@@ -332,7 +334,344 @@ describe('End-to-End Tests', () => {
         const result = await cliWithEnv(['aws'], getLocalStackEnv());
 
         expect(result.code).toBe(1);
-        expect(result.stderr).toContain('required option');
+        expect(result.stderr).toContain('Missing required option --secret');
+      });
+    });
+
+    describe('AWS Secret Management Commands', () => {
+      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 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()}`,
+          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([]);
+      });
+
+      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/__e2e__/utils/test-utils.ts

@@ -1,4 +1,4 @@
-import { exec } from 'child_process';
+import { exec, spawn } from 'child_process';
 import { promisify } from 'util';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -506,6 +506,66 @@ export async function cliWithEnv(
   });
 }
 
+export async function cliWithEnvAndStdin(
+  args: string[],
+  env: Record<string, string>,
+  stdin: string,
+  cwd = '.'
+): Promise<CliResult> {
+  return await new Promise((resolve) => {
+    const cleanEnv = { ...process.env };
+    delete cleanEnv.AWS_PROFILE;
+    delete cleanEnv.AWS_DEFAULT_PROFILE;
+    delete cleanEnv.AWS_SESSION_TOKEN;
+    delete cleanEnv.AWS_SECURITY_TOKEN;
+    delete cleanEnv.AWS_ROLE_ARN;
+    delete cleanEnv.AWS_ROLE_SESSION_NAME;
+    delete cleanEnv.AWS_WEB_IDENTITY_TOKEN_FILE;
+    delete cleanEnv.AWS_WEB_IDENTITY_TOKEN;
+
+    const defaultEnv = {
+      AWS_ENDPOINT_URL: process.env.LOCALSTACK_URL || 'http://localhost:4566',
+      AWS_ACCESS_KEY_ID: 'test',
+      AWS_SECRET_ACCESS_KEY: 'test',
+      AWS_DEFAULT_REGION: 'us-east-1',
+      AWS_REGION: 'us-east-1',
+      NODE_ENV: 'test'
+    };
+
+    const envVars = { ...cleanEnv, ...defaultEnv, ...env };
+    const child = spawn('node', [path.resolve('./dist/index'), ...args], {
+      cwd,
+      env: envVars,
+      stdio: 'pipe'
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let error: Error | null = null;
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on('error', (err) => {
+      error = err;
+    });
+    child.on('close', (code) => {
+      resolve({
+        code: code ?? (error ? 1 : 0),
+        error,
+        stdout,
+        stderr
+      });
+    });
+
+    child.stdin.write(stdin);
+    child.stdin.end();
+  });
+}
+
 export function createTempFile(content: string) {
   const tempDir = os.tmpdir();
   const tempFile = path.join(tempDir, `env-secrets-test-${Date.now()}.env`);