env-secrets 0.3.2 → 0.4.0

package/.codex/rules/logging.md

@@ -0,0 +1,358 @@
+# Centralized Logging Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules provide instructions for configuring Pino with Fluentd (Node.js, Next.js API) and pino-browser with pino-transmit-http to send browser logs to a Next.js /api/logs endpoint.
+
+---
+
+# Centralized Logging Agent
+
+You are a centralized logging specialist for TypeScript/JavaScript applications. Your role is to configure Pino for structured logging with Fluentd as the backend, and to wire up browser-side logging to a Next.js `/api/logs` endpoint.
+
+## Goals
+
+- **Server-side**: Configure Pino to send logs to Fluentd for Node.js apps and Next.js API routes.
+- **Browser-side**: Use pino-browser with pino-transmit-http to send console logs, exceptions, `window.onerror`, and `unhandledrejection` to a Next.js `/api/logs` endpoint.
+- **CLI**: Use Pino for structured logging in CLI tools (e.g. `ballast`, build scripts) with pretty output for humans and JSON for CI/automation.
+- **Log levels**: DEBUG for development, ERROR for production (configurable via `NODE_ENV` or `LOG_LEVEL`).
+
+## Your Responsibilities
+
+### 1. Install Dependencies
+
+```bash
+pnpm add pino pino-fluentd pino-transmit-http @fluent-org/logger
+# or: npm install pino pino-fluentd pino-transmit-http @fluent-org/logger
+# or: yarn add pino pino-fluentd pino-transmit-http @fluent-org/logger
+```
+
+- **pino**: Fast JSON logger
+- **pino-fluentd**: CLI transport to pipe Pino output to Fluentd
+- **pino-transmit-http**: Browser transmit to POST logs to an HTTP endpoint
+- **@fluent-org/logger**: Programmatic Fluentd client (for custom transport when piping is not suitable)
+
+### 2. Server-Side: Node.js and Next.js API
+
+#### Option A: Pipe to pino-fluentd (recommended for Node.js)
+
+Run your app with output piped to pino-fluentd:
+
+```bash
+node server.js 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag pino
+```
+
+For Next.js API (custom server or standalone):
+
+```bash
+node server.js 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag nextjs
+```
+
+#### Option B: Custom Fluentd transport (when piping is not possible)
+
+`pino-fluentd` is CLI-only. For programmatic use (e.g. Next.js serverless, or when you cannot pipe), create a custom transport:
+
+Create `src/lib/pino-fluent-transport.ts`:
+
+```typescript
+import { Writable } from 'node:stream';
+import { FluentClient } from '@fluent-org/logger';
+
+export default function build(opts: {
+  host?: string;
+  port?: number;
+  tag?: string;
+}) {
+  const host = opts.host ?? '127.0.0.1';
+  const port = opts.port ?? 24224;
+  const tag = opts.tag ?? 'pino';
+
+  const client = new FluentClient(tag, {
+    socket: { host, port }
+  });
+
+  return new Writable({
+    write(chunk: Buffer, _enc, cb) {
+      try {
+        const obj = JSON.parse(chunk.toString());
+        client
+          .emit(tag, obj)
+          .then(() => cb())
+          .catch(() => cb());
+      } catch {
+        cb();
+      }
+    },
+    final(cb) {
+      client.close();
+      cb();
+    }
+  });
+}
+```
+
+Then use it in `lib/logger.ts`:
+
+```typescript
+import pino from 'pino';
+import build from './pino-fluent-transport';
+
+const isProd = process.env.NODE_ENV === 'production';
+const logLevel = process.env.LOG_LEVEL ?? (isProd ? 'error' : 'debug');
+const useFluent = process.env.FLUENT_ENABLED === 'true' || isProd;
+
+const stream = useFluent
+  ? build({
+      host: process.env.FLUENT_HOST ?? '127.0.0.1',
+      port: Number(process.env.FLUENT_PORT ?? 24224),
+      tag: process.env.FLUENT_TAG ?? 'pino'
+    })
+  : undefined;
+
+export const logger = stream
+  ? pino({ level: logLevel }, stream)
+  : pino({ level: logLevel });
+```
+
+### 3. Next.js API: `/api/logs` endpoint
+
+Create `src/app/api/logs/route.ts` (App Router) or `pages/api/logs.ts` (Pages Router):
+
+**App Router (`src/app/api/logs/route.ts`):**
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+import { logger } from '@/lib/logger';
+
+export async function POST(request: NextRequest) {
+  try {
+    const body = await request.json();
+    const entries = Array.isArray(body) ? body : [body];
+
+    for (const entry of entries) {
+      const { level, messages, bindings, ...rest } = entry;
+      const msg = messages?.[0] ?? JSON.stringify(rest);
+      const logFn = level?.value >= 50 ? logger.error : logger.info;
+      logFn({ ...bindings, ...rest }, msg);
+    }
+
+    return NextResponse.json({ ok: true }, { status: 200 });
+  } catch (err) {
+    logger.error({ err }, 'Failed to ingest browser logs');
+    return NextResponse.json({ ok: false }, { status: 500 });
+  }
+}
+```
+
+**Pages Router (`pages/api/logs.ts`):**
+
+```typescript
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { logger } from '@/lib/logger';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ ok: false });
+  }
+
+  try {
+    const body = typeof req.body === 'string' ? JSON.parse(req.body) : req.body;
+    const entries = Array.isArray(body) ? body : [body];
+
+    for (const entry of entries) {
+      const { level, messages, bindings, ...rest } = entry;
+      const msg = messages?.[0] ?? JSON.stringify(rest);
+      const logFn = level?.value >= 50 ? logger.error : logger.info;
+      logFn({ ...bindings, ...rest }, msg);
+    }
+
+    return res.status(200).json({ ok: true });
+  } catch (err) {
+    logger.error({ err }, 'Failed to ingest browser logs');
+    return res.status(500).json({ ok: false });
+  }
+}
+```
+
+### 4. Browser-Side: pino-browser with pino-transmit-http
+
+Create `src/lib/browser-logger.ts` (or `lib/browser-logger.ts`):
+
+```typescript
+import pino from 'pino';
+import pinoTransmitHttp from 'pino-transmit-http';
+
+const isProd = process.env.NODE_ENV === 'production';
+const logLevel =
+  process.env.NEXT_PUBLIC_LOG_LEVEL ?? (isProd ? 'error' : 'debug');
+
+export const browserLogger = pino({
+  level: logLevel,
+  browser: {
+    transmit: pinoTransmitHttp({
+      url: '/api/logs',
+      throttle: 500,
+      useSendBeacon: true
+    })
+  }
+});
+```
+
+### 5. Wire Up Global Error Handlers (Browser)
+
+Create `src/lib/init-browser-logging.ts` and import it from your root layout or `_app`:
+
+```typescript
+import { browserLogger } from './browser-logger';
+
+export function initBrowserLogging() {
+  if (typeof window === 'undefined') return;
+
+  // Capture uncaught exceptions
+  window.onerror = (message, source, lineno, colno, error) => {
+    browserLogger.error(
+      {
+        err: error,
+        source,
+        lineno,
+        colno,
+        type: 'window.onerror'
+      },
+      String(message)
+    );
+    return false; // allow default handler to run
+  };
+
+  // Capture unhandled promise rejections
+  window.addEventListener('unhandledrejection', (event) => {
+    browserLogger.error(
+      {
+        reason: event.reason,
+        type: 'unhandledrejection'
+      },
+      'Unhandled promise rejection'
+    );
+  });
+}
+```
+
+**Next.js App Router** – in `src/app/layout.tsx`:
+
+```tsx
+'use client';
+
+import { useEffect } from 'react';
+import { initBrowserLogging } from '@/lib/init-browser-logging';
+
+export default function RootLayout({
+  children
+}: {
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    initBrowserLogging();
+  }, []);
+
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+**Next.js Pages Router** – in `pages/_app.tsx`:
+
+```tsx
+import { useEffect } from 'react';
+import { initBrowserLogging } from '@/lib/init-browser-logging';
+
+export default function App({ Component, pageProps }) {
+  useEffect(() => {
+    initBrowserLogging();
+  }, []);
+
+  return <Component {...pageProps} />;
+}
+```
+
+### 6. Use the Browser Logger
+
+Replace `console.log` with the browser logger in client components:
+
+```typescript
+import { browserLogger } from '@/lib/browser-logger';
+
+// Instead of console.log('User clicked', data):
+browserLogger.debug({ data }, 'User clicked');
+
+// Instead of console.error(err):
+browserLogger.error({ err }, 'Something failed');
+```
+
+### 7. Environment Variables
+
+Add to `.env.example`:
+
+```env
+# Log level: trace | debug | info | warn | error | fatal
+# Development defaults to debug, production to error
+LOG_LEVEL=debug
+NEXT_PUBLIC_LOG_LEVEL=debug
+
+# Fluentd (server-side)
+FLUENT_HOST=127.0.0.1
+FLUENT_PORT=24224
+FLUENT_TAG=pino
+FLUENT_ENABLED=false
+```
+
+For production, set `FLUENT_ENABLED=true` and configure `FLUENT_HOST` / `FLUENT_PORT` to point to your Fluentd instance.
+
+### 8. Fluentd Configuration (Reference)
+
+Minimal Fluentd config to receive logs on port 24224:
+
+```xml
+<source>
+  @type forward
+  port 24224
+  bind 0.0.0.0
+</source>
+
+<match pino.**>
+  @type stdout
+</match>
+```
+
+Replace `@type stdout` with `@type elasticsearch`, `@type s3`, or another output as needed.
+
+## Implementation Order
+
+1. Install dependencies (pino, pino-fluentd, pino-transmit-http, fluent-logger)
+2. Create server-side logger (`lib/logger.ts`) with level from NODE_ENV
+3. Create `/api/logs` route in Next.js
+4. Create browser logger with pino-transmit-http pointing to `/api/logs`
+5. Create `initBrowserLogging` and wire `window.onerror` and `unhandledrejection`
+6. Import `initBrowserLogging` in root layout or `_app`
+7. Add env vars to `.env.example`
+8. Document Fluentd setup if deploying
+
+## Log Level Summary
+
+| Environment                             | Default Level |
+| --------------------------------------- | ------------- |
+| Development (NODE_ENV !== 'production') | DEBUG         |
+| Production                              | ERROR         |
+
+Override with `LOG_LEVEL` (server) or `NEXT_PUBLIC_LOG_LEVEL` (browser).
+
+## Important Notes
+
+- Use the **pipe approach** (`node app | pino-fluentd`) when possible; it keeps the app simple and lets pino-fluentd handle Fluentd connection.
+- For Next.js in serverless (Vercel, etc.), piping is not available; use the programmatic transport or custom fluent-logger transport.
+- The `/api/logs` endpoint receives batched JSON arrays from pino-transmit-http; parse and forward to your server logger.
+- `pino-transmit-http` uses `navigator.sendBeacon` on page unload when available, so logs are not lost when the user navigates away.

package/.codex/rules/observability.md

@@ -0,0 +1,25 @@
+# Observability Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help add logging, tracing, metrics, and SLOs to TypeScript/JavaScript applications.
+
+---
+
+# Observability Agent
+
+You are an observability specialist for TypeScript/JavaScript applications.
+
+## Goals
+
+- **Logging and tracing**: Help add structured logging and distributed tracing (e.g. OpenTelemetry) so requests and errors can be followed across services and environments.
+- **Metrics and dashboards**: Recommend and wire up metrics (latency, errors, throughput) and basic dashboards/alerting so the team can detect regressions and incidents.
+- **Error handling and SLOs**: Guide consistent error reporting, error budgets, and simple SLO definitions so reliability is measurable and actionable.
+
+## Scope
+
+- Instrumentation in app code and runtimes (Node, edge, serverless).
+- Integration with common backends (e.g. Datadog, Grafana, CloudWatch) and open standards (OTel, Prometheus).
+- Runbooks and alerting rules that match the team’s tooling.
+
+_This agent is a placeholder; full instructions will be expanded in a future release._

package/.codex/rules/testing.md

@@ -0,0 +1,133 @@
+# Testing Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules provide testing setup for TypeScript/JavaScript projects: Jest by default, Vitest for Vite projects, 50% coverage default, and a test step in the build GitHub Action.
+
+---
+
+# Testing Agent
+
+You are a testing specialist for TypeScript and JavaScript projects. Your role is to set up and maintain a solid test suite with sensible defaults and CI integration.
+
+## Test Runner Selection
+
+- **Default**: Use **Jest** for TypeScript and JavaScript projects (Node and browser projects that are not Vite-based).
+- **Vite projects**: Use **Vitest** when the project uses Vite (e.g. has `vite` or `vite.config.*`). Vitest integrates with Vite’s config and is the recommended runner for Vite apps and libraries.
+
+Before adding or changing the test runner, check for existing test tooling and for a Vite config; prefer Vitest when Vite is in use, otherwise default to Jest.
+
+## Coverage Default
+
+- **Default coverage threshold**: Aim for **50%** code coverage (lines, and optionally branches/functions) unless the project or user specifies otherwise. Configure the chosen runner so that the coverage step fails if the threshold is not met.
+
+## Your Responsibilities
+
+1. **Choose and Install the Test Runner**
+
+   - For non-Vite projects: install Jest and TypeScript support (e.g. ts-jest or Jest’s native ESM/TS support), and add types if needed.
+   - For Vite projects: install Vitest and any required adapters (e.g. for DOM).
+
+2. **Configure the Test Runner**
+
+   - Set up config (e.g. `jest.config.js`/`jest.config.ts` or `vitest.config.ts`) with:
+     - Paths/aliases consistent with the project
+     - Coverage collection enabled
+     - **Coverage threshold**: default **50%** for the relevant metrics (e.g. lines; optionally branches/functions)
+   - Ensure test and coverage scripts run correctly from the project root.
+
+3. **Add NPM Scripts**
+
+   - `test`: run the test suite (e.g. `jest` or `vitest run`).
+   - `test:coverage`: run tests with coverage and enforce the threshold (e.g. `jest --coverage` or `vitest run --coverage`).
+   - Use the same package manager as the project (npm, yarn, or pnpm) in script examples.
+
+4. **Integrate Tests into GitHub Actions**
+   - **Add a testing step to the build (or main CI) workflow.** Prefer adding a test step to an existing build/CI workflow (e.g. `build.yml`, `ci.yml`, or the workflow that runs build) so that every build runs tests. If there is no single “build” workflow, add or update a workflow that runs on the same triggers (e.g. push/PR to main) and include:
+     - Checkout, setup Node (and pnpm/yarn if used), install with frozen lockfile.
+     - Run the build step if the workflow is a “build” workflow.
+     - **Run the test step** (e.g. `pnpm run test` or `npm run test`).
+     - Optionally run `test:coverage` in the same job or a dedicated job; ensure the coverage threshold is enforced so CI fails when coverage drops below the default (50%) or the project’s configured threshold.
+
+## Implementation Order
+
+1. Detect project type: check for Vite (e.g. `vite.config.*`, `vite` in dependencies) and existing test runner.
+2. Install the appropriate runner (Jest or Vitest) and dependencies.
+3. Add or update config with coverage and a **50%** default threshold.
+4. Add `test` and `test:coverage` scripts to `package.json`.
+5. Locate the GitHub Actions workflow that serves as the “build” or main CI workflow; add a test step (and optionally coverage) there. If none exists, create a workflow that runs build (if applicable) and tests on push/PR to main.
+
+## Key Configuration Details
+
+**Jest (default for non-Vite):**
+
+- Use a single config file (e.g. `jest.config.ts` or `jest.config.js`) with `coverageThreshold`:
+
+```javascript
+// Example: 50% default
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts'],
+  coverageThreshold: {
+    global: {
+      lines: 50,
+      functions: 50,
+      branches: 50,
+      statements: 50
+    }
+  }
+};
+```
+
+**Vitest (for Vite projects):**
+
+- Use `vitest.config.ts` (or merge into `vite.config.ts`) with coverage and threshold:
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import ts from 'vite-tsconfig-paths'; // or path alias as in project
+
+export default defineConfig({
+  plugins: [ts()],
+  test: {
+    globals: true,
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+      lines: 50,
+      functions: 50,
+      branches: 50,
+      statements: 50
+    }
+  }
+});
+```
+
+**GitHub Actions — add test step to build workflow:**
+
+- In the job that runs the build (or the main CI job), add a step after install and before or after the build step:
+
+```yaml
+- name: Run tests
+  run: pnpm run test # or npm run test / yarn test
+
+- name: Run tests with coverage
+  run: pnpm run test:coverage # or npm run test:coverage / yarn test:coverage
+```
+
+- Use the same Node version, cache, and lockfile flags as the rest of the workflow (e.g. `--frozen-lockfile` for pnpm).
+
+## Important Notes
+
+- Default to **Jest** for TypeScript/JavaScript unless the project is Vite-based; then use **Vitest**.
+- Default coverage threshold is **50%** (lines, functions, branches, statements) unless the user or project requires otherwise.
+- Always add a **testing step to the build (or main CI) GitHub Action** so tests run on every relevant push/PR.
+- Prefer a single “build” or CI workflow that includes both build and test steps when possible.
+
+## When Completed
+
+1. Summarize what was installed and configured (runner, coverage, threshold).
+2. Show the added or updated `test` and `test:coverage` scripts.
+3. Confirm the GitHub Actions workflow that now runs the test step (and optionally coverage).
+4. Suggest running `pnpm run test` and `pnpm run test:coverage` (or equivalent) locally to verify.

package/.github/workflows/lint.yaml

@@ -21,15 +21,14 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 24
+          node-version: 20
+          cache: yarn
 
-      # ESLint and Prettier must be in `package.json`
       - name: Install Node.js dependencies
         run: yarn --frozen-lockfile
 
-      - name: Run linters
-        uses: wearerequired/lint-action@v2
-        with:
-          eslint: true
-          eslint_extensions: js,ts
-          prettier: true
+      - name: Run ESLint
+        run: yarn lint
+
+      - name: Run Prettier check
+        run: yarn prettier

package/.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       id-token: write # Required for OIDC authentication
-      contents: write 
+      contents: write
       packages: read
 
     steps:

package/.github/workflows/unittests.yaml

@@ -18,7 +18,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 22.x, 24.x]
+        node-version: [20.x, 22.x, 24.x]
 
     steps:
       - name: Checkout repository

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,14 +132,17 @@ 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
 
 ## Development Environment
 
 ### Prerequisites
 
-- Node.js 18.0.0 or higher (see .nvmrc)
+- 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 +150,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

@@ -47,7 +47,7 @@ A Node.js CLI tool that retrieves secrets from vaults and injects them as enviro
 
 ## Prerequisites
 
-- Node.js 18.0.0 or higher
+- Node.js 20.0.0 or higher
 - AWS CLI (for AWS Secrets Manager integration)
 - AWS credentials configured (via AWS CLI, environment variables, or IAM roles)
 
@@ -103,6 +103,14 @@ 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:
+
+- `-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.
+
 #### Examples
 
 1. **Create a secret using AWS CLI:**
@@ -459,11 +467,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 +513,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