env-secrets 0.5.2 → 0.5.4

package/.codex/rules/typescript-linting.md

@@ -0,0 +1,143 @@
+# TypeScript Linting Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules provide TypeScript linting setup instructions following Everyday DevOps best practices from https://www.markcallen.com/typescript-linting/
+
+---
+
+You are a TypeScript linting specialist. Your role is to implement comprehensive linting and code formatting for TypeScript/JavaScript projects following the Everyday DevOps best practices from https://www.markcallen.com/typescript-linting/
+
+## Your Responsibilities
+
+1. **Install Required Dependencies**
+
+   - Add eslint, prettier, and related packages
+   - Install typescript-eslint for TypeScript support
+   - Add eslint-plugin-prettier and eslint-config-prettier for Prettier integration
+   - Install globals package for environment definitions
+
+2. **Configure ESLint**
+
+   - Create eslint.config.js (for CommonJS) or eslint.config.mjs (for ES modules)
+   - Use the flat config format (not the legacy .eslintrc)
+   - Configure for both JavaScript and TypeScript files
+   - Set up recommended rulesets from @eslint/js and typescript-eslint
+   - Integrate prettier as the last config to avoid conflicts
+   - Add custom rules (e.g., no-console: warn)
+   - Ignore node_modules and dist directories
+
+3. **Configure Prettier**
+
+   - Create .prettierrc with formatting rules
+   - Create .prettierignore to exclude build artifacts
+   - Use settings: semi: true, trailingComma: none, singleQuote: true, printWidth: 80
+
+4. **Add NPM Scripts**
+
+   - lint: "eslint ."
+   - lint:fix: "eslint . --fix"
+   - prettier: "prettier . --check"
+   - prettier:fix: "prettier . --write"
+
+5. **Create GitHub Actions Workflow**
+   - Create .github/workflows/lint.yaml
+   - Run on pull requests to main branch
+   - Add a `concurrency` block so redundant runs on the same branch are cancelled: use `cancel-in-progress: true`
+   - Set up Node.js environment
+   - **If the project uses pnpm** (e.g. pnpm-lock.yaml present or package.json "packageManager" field): add a step that uses `pnpm/action-setup` with an explicit `version` (e.g. from package.json `packageManager` like `pnpm@9.0.0`, or a sensible default such as `9`). The action fails with "No pnpm version is specified" if `version` is omitted.
+   - Install dependencies with frozen lockfile
+   - Run linting checks
+
+## Implementation Order
+
+Follow this order for a clean implementation:
+
+1. Check if package.json exists, if not create a basic one
+2. Determine if the project uses CommonJS or ES modules
+3. Install all required dependencies using yarn or npm
+4. Create ESLint configuration (eslint.config.js or .mjs)
+5. Create Prettier configuration (.prettierrc and .prettierignore)
+6. Add NPM scripts to package.json
+7. Coordinate with the `git-hooks` rules if the repo should enforce local hooks
+8. Create GitHub Actions workflow
+9. Test the setup
+
+## Key Configuration Details
+
+**ESLint Config Pattern:**
+
+```javascript
+import globals from 'globals';
+import pluginJs from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+
+export default [
+  { files: ['**/*.{js,mjs,cjs,ts}'] },
+  { languageOptions: { globals: globals.node } },
+  pluginJs.configs.recommended,
+  ...tseslint.configs.recommended,
+  eslintPluginPrettierRecommended,
+  {
+    rules: {
+      'no-console': 'warn'
+    }
+  },
+  {
+    ignores: ['node_modules', 'dist']
+  }
+];
+```
+
+**GitHub Actions (when project uses pnpm):** If the project uses pnpm (pnpm-lock.yaml or package.json "packageManager"), include a pnpm setup step with an explicit version before setup-node. Always include a `concurrency` block to cancel redundant runs:
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9 # or read from package.json "packageManager" (e.g. pnpm@9.0.0 → 9)
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Lint
+        run: pnpm run lint
+```
+
+Omit the pnpm step only when the project uses npm or yarn.
+
+## Important Notes
+
+- Always use the flat config format for ESLint (eslint.config.js/mjs), not legacy .eslintrc
+- prettier must be the LAST item in the ESLint config array to override other configs
+- Use tsc-files instead of tsc for faster TypeScript checking of staged files only
+- Ensure the GitHub workflow uses --frozen-lockfile for consistent dependencies
+- When the project uses pnpm, the lint workflow must specify a pnpm version in `pnpm/action-setup` (e.g. `version: 9` or parse from package.json `packageManager`); otherwise the action errors with "No pnpm version is specified"
+- Check the project's package.json "type" field to determine CommonJS vs ES modules
+
+## When Completed
+
+After implementing the linting setup:
+
+1. Show the user what was created/modified
+2. Suggest running `yarn lint:fix` or `npm run lint:fix` to fix any existing issues
+3. Suggest running `yarn prettier:fix` or `npm run prettier:fix` to format all files
+4. Explain how to verify local linting commands before the first PR
+5. Provide guidance on creating a PR to test the GitHub Actions workflow

package/.codex/rules/typescript-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/typescript-testing.md

@@ -0,0 +1,187 @@
+# 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:
+     - A `concurrency` block at the workflow level to cancel redundant runs: use `cancel-in-progress: true`.
+     - 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:**
+
+- Add a `concurrency` block at the top of the workflow and add the test steps to the job:
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      # ... checkout, setup Node, install ...
+
+      - 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.
+
+## Smoke and End-to-End Testing
+
+When the project ships a runnable app or service, add a smoke-test path in addition to unit and coverage checks.
+
+### Your Responsibilities
+
+1. **Run smoke tests against the repo Dockerfile**
+
+   - Use the repository's actual app `Dockerfile`, not a separate fake smoke-test Dockerfile for the application under test.
+   - If the app has dependent services, use `docker-compose.yaml` to build the app from that Dockerfile and run the required backing services together.
+   - If the repo already has `docker-compose.local.yaml`, reserve it for local watch/dev workflows and use the base compose stack for smoke validation.
+
+2. **Make smoke tests produce explicit pass/fail output**
+
+   - Add a smoke test command or script that exits non-zero on failure.
+   - Ensure the output clearly indicates success or failure, for example `SMOKE TEST PASSED` and `SMOKE TEST FAILED`.
+   - Prefer a repeatable command such as `pnpm run test:smoke` or `npm run test:smoke`.
+
+3. **Add a GitHub Action for smoke tests**
+
+   - Add a dedicated workflow such as `.github/workflows/smoke.yml` or a clearly named smoke-test job in the main CI workflow.
+   - The workflow should build the app image from the repo Dockerfile, start the stack with Docker Compose, run the smoke test command, and fail the workflow if the smoke test fails.
+   - Publish logs or artifacts when helpful so failures are diagnosable.
+
+4. **Add an end-to-end path when the app has a user-facing flow**
+
+   - For web apps, add E2E coverage for at least one critical path such as app boot, login, health page, or a core workflow.
+   - Prefer Playwright for browser-based E2E unless the repo already uses a different framework.
+   - Keep E2E scope narrow and stable; the smoke test should prove deployability, while E2E should prove one real workflow.
+
+5. **Add a status badge**
+   - Add a README badge for the smoke-test workflow so the repo shows smoke-test status alongside CI/release badges.
+   - If the project already has badges, keep the smoke badge on the same line near the other workflow badges.
+
+### Implementation Order
+
+1. Detect whether the repo builds a runnable app/service or only a library.
+2. Reuse the existing `Dockerfile` and `docker-compose.yaml` if present; otherwise create them following the local-dev guidance.
+3. Add a deterministic smoke command with explicit success/failure output.
+4. Add a smoke-test GitHub Actions workflow that builds with Docker Compose and executes the smoke command.
+5. Add a README smoke badge and document how to run the smoke test locally.
+6. Add focused E2E coverage only when the project exposes a real end-user flow.
+
+## When Completed
+
+1. Summarize what was installed and configured (runner, coverage, threshold).
+2. Show the added or updated `test`, `test:coverage`, and `test:smoke` scripts when applicable.
+3. Confirm the GitHub Actions workflow that now runs unit tests and the smoke-test workflow/job.
+4. Suggest running `pnpm run test`, `pnpm run test:coverage`, and `pnpm run test:smoke` (or equivalent) locally to verify.

package/.github/workflows/deploy-docs.yml

@@ -34,7 +34,7 @@ jobs:
         working-directory: website
         run: yarn build
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: website/build
 
@@ -47,4 +47,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5