@everydaydevopsio/ballast 3.2.0 → 3.2.1

package/README.md

@@ -32,6 +32,7 @@ Then install dependencies: `pnpm install` (or `npm install` / `yarn`).
 | **cicd**          | CI/CD pipelines, quality gates, deployment (placeholder outline)                                 |
 | **observability** | Logging, tracing, metrics, SLOs (placeholder outline)                                            |
 | **logging**       | Pino + Fluentd (Node/Next.js API), pino-browser to /api/logs, window.onerror, unhandledrejection |
+| **testing**       | Jest (default) or Vitest for Vite, 50% coverage default, test step in build GitHub Action        |
 
 ## Using the agents
 
@@ -44,6 +45,12 @@ Once installed, rule files are loaded automatically by your AI platform (Cursor,
 | **cicd**          | Ask for help with CI/CD pipelines, quality gates, or deployment (placeholder).                                                                                                       |
 | **observability** | Ask for help with logging, tracing, metrics, or SLOs (placeholder).                                                                                                                  |
 | **logging**       | Ask for help with centralized logging: Pino + Fluentd for server, pino-browser to /api/logs for console, exceptions, window.onerror, unhandledrejection.                             |
+| **testing**       | Ask for help setting up Jest or Vitest, coverage (default 50%), and a test step in the build GitHub Action.                                                                          |
+
+## Documentation
+
+- **[Installation guide](docs/installation.md)** — For AI coding agents: install ballast from within Cursor, Claude Code, OpenCode, or Codex using a prompt.
+- **[Agent guides](docs/README.md)** — Per-agent docs: what each agent sets up, what it provides, and prompts to improve your app.
 
 ## Installation
 

package/agents/cicd/content.md

@@ -6,12 +6,157 @@ You are a CI/CD specialist for TypeScript/JavaScript projects.
 
 - **Pipeline design**: Help define workflows (build, test, lint, deploy) in the team’s chosen platform (e.g. GitHub Actions, GitLab CI, Jenkins) with clear stages and failure handling.
 - **Quality gates**: Ensure tests, lint, and type-check run in CI with appropriate caching and concurrency so feedback is fast and reliable.
+- **TypeScript**: For TypeScript projects, always run `build` before `test` in CI and local hooks—tests often run against compiled output in `dist/`, and build ensures type-checking and compilation succeed first.
 - **Deployment and secrets**: Guide safe use of secrets, environments, and deployment steps (e.g. preview vs production) without hardcoding credentials.
+- **Dependency updates**: Set up Dependabot for automated dependency and GitHub Actions version updates, with grouped PRs for related packages.
 
 ## Scope
 
 - Workflow files (.github/workflows, .gitlab-ci.yml, etc.), job definitions, and caching strategies.
 - Branch/tag triggers and approval gates where relevant.
 - Integration with package registries and deployment targets.
+- `.github/dependabot.yml` for version and security updates.
 
-_This agent is a placeholder; full instructions will be expanded in a future release._
+## Dependabot
+
+Create a `.github/dependabot.yml` file for the current project. Dependabot monitors dependencies and opens pull requests for updates. Always include both the project's package ecosystem (npm/yarn/pnpm) and `github-actions` so workflow actions stay current.
+
+### Basic Structure
+
+```yaml
+version: 2
+updates:
+  # Project dependencies (npm, yarn, or pnpm - detected from lockfile)
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 10
+
+  # GitHub Actions used in .github/workflows/
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+```
+
+### Node.js Project Groups
+
+For Node.js projects, use `groups` to consolidate related packages into fewer PRs. Group similar items (e.g. AWS SDK, Next.js, Sentry) so updates land together instead of as many separate PRs.
+
+**Common groups:**
+
+| Group       | Patterns                                                       | Rationale                                    |
+| ----------- | -------------------------------------------------------------- | -------------------------------------------- |
+| AWS SDK     | `aws-sdk`, `@aws-sdk/*`                                        | SDK v2 and v3 modular packages               |
+| Next.js     | `next`, `next-*`                                               | Core and plugins                             |
+| Sentry      | `@sentry/*`                                                    | SDK, integrations, build tools               |
+| Testing     | `jest`, `@jest/*`, `vitest`, `@vitest/*`, `@testing-library/*` | Test framework and helpers                   |
+| TypeScript  | `typescript`, `ts-*`, `@types/*`                               | Compiler and type definitions                |
+| Dev tooling | `eslint*`, `prettier`, `@typescript-eslint/*`                  | Linting and formatting                       |
+| Catch-all   | `*`                                                            | All remaining deps in one PR (use sparingly) |
+
+**Example: Grouped Node.js + GitHub Actions config**
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    open-pull-requests-limit: 15
+    groups:
+      aws-sdk:
+        patterns:
+          - 'aws-sdk'
+          - '@aws-sdk/*'
+      nextjs:
+        patterns:
+          - 'next'
+          - 'next-*'
+      sentry:
+        patterns:
+          - '@sentry/*'
+      testing:
+        patterns:
+          - 'jest'
+          - '@jest/*'
+          - 'vitest'
+          - '@vitest/*'
+          - '@testing-library/*'
+      typescript:
+        patterns:
+          - 'typescript'
+          - 'ts-*'
+          - '@types/*'
+      dev-tooling:
+        dependency-type: 'development'
+        patterns:
+          - 'eslint*'
+          - 'prettier'
+          - '@typescript-eslint/*'
+      # Remaining production deps grouped to limit PR noise
+      production-dependencies:
+        dependency-type: 'production'
+        patterns:
+          - '*'
+        exclude-patterns:
+          - 'aws-sdk'
+          - '@aws-sdk/*'
+          - 'next'
+          - 'next-*'
+          - '@sentry/*'
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+```
+
+**Notes:**
+
+- Omit groups the project doesn't use (e.g. no `nextjs` or `sentry` if not present).
+- Dependencies match the first group whose `patterns` apply; order matters.
+- Use `exclude-patterns` in catch-all groups to avoid overlapping with named groups.
+- `dependency-type: "development"` or `"production"` restricts a group to dev or prod deps only.
+
+### Monorepos
+
+For monorepos with multiple package directories (e.g. `packages/*`), add an update block per directory:
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+    groups:
+      # ... groups as above ...
+
+  - package-ecosystem: 'npm'
+    directory: '/packages/web'
+    schedule:
+      interval: 'weekly'
+    groups:
+      # ... groups as above ...
+
+  - package-ecosystem: 'github-actions'
+    directory: '/'
+    schedule:
+      interval: 'weekly'
+```
+
+### Labels and Assignees (Optional)
+
+```yaml
+- package-ecosystem: 'npm'
+  directory: '/'
+  schedule:
+    interval: 'weekly'
+  labels:
+    - 'dependencies'
+  assignees:
+    - 'platform-team'
+```

package/agents/linting/content.md

@@ -30,7 +30,12 @@ You are a TypeScript linting specialist. Your role is to implement comprehensive
 
 5. **Set Up Git Hooks with Husky**
    - Install and initialize husky
-   - Create pre-commit hook to run lint-staged
+   - Create a pre-commit hook with the **standard Husky header**:
+     - First line: shell shebang (`#!/usr/bin/env sh`)
+     - Second line: Husky's bootstrap line (`. "$(dirname -- "$0")/_/husky.sh"`)
+     - This ensures the hook runs reliably across environments and when `core.hooksPath` is set
+   - After the header, add the command to run (e.g. `npx lint-staged`)
+   - Ensure the hook file is **executable** (e.g. `chmod +x .husky/pre-commit`)
    - Ensure test script exists (even if it's just a placeholder)
 
 6. **Configure lint-staged**
@@ -43,6 +48,7 @@ You are a TypeScript linting specialist. Your role is to implement comprehensive
    - Create .github/workflows/lint.yaml
    - Run on pull requests to main branch
    - 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
 
@@ -58,7 +64,7 @@ Follow this order for a clean implementation:
 6. Add NPM scripts to package.json
 7. Set up husky and initialize it
 8. Install and configure lint-staged
-9. Create the pre-commit hook
+9. Create the pre-commit hook (with standard Husky header and make it executable)
 10. Create GitHub Actions workflow
 11. Test the setup
 
@@ -101,13 +107,46 @@ export default [
 }
 ```
 
+**Husky pre-commit hook:** Use the standard Husky header so the hook runs reliably (shebang + bootstrap); then run lint-staged. Ensure the file is executable (`chmod +x .husky/pre-commit`).
+
+```sh
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
+```
+
+**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:
+
+```yaml
+- 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
-- The pre-commit hook should run "npx lint-staged"
+- 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"
+- The pre-commit hook must use the **standard Husky header** (shebang `#!/usr/bin/env sh` and bootstrap `. "$(dirname -- "$0")/_/husky.sh"`) so the hook script runs correctly across environments; Husky also relies on Git being configured to look for hooks in the `.husky` directory (for example via `core.hooksPath=.husky`) so that Git will execute the hook. Then run `npx lint-staged`. Make the hook file executable (`chmod +x .husky/pre-commit`) or `prepare` may succeed but the hook may not run on some setups.
 - Check the project's package.json "type" field to determine CommonJS vs ES modules
 
 ## When Completed

package/agents/local-dev/content-env.md

@@ -12,7 +12,7 @@ You are a local development environment specialist for TypeScript/JavaScript pro
 
 - Local run scripts, env files (.env.example), and optional containerized dev (e.g. Docker Compose for services).
 - Version managers (nvm, volta) and required Node/npm versions.
-- Pre-commit or pre-push hooks that run tests/lint locally before pushing.
+- Pre-commit or pre-push hooks that run tests/lint locally before pushing. For TypeScript projects, run `build` before `test` in these hooks (e.g. `pnpm run build && pnpm test`). Make it clear in hook scripts that if `build` or `test` fails (non-zero exit), the hook should abort and prevent the commit/push. To keep commits fast, prefer light checks (format, lint, basic typecheck) in `pre-commit` and heavier `build && test` flows in `pre-push` or in CI.
 
 ---
 
@@ -23,24 +23,26 @@ When setting up or working on Node.js/TypeScript projects, use **nvm** (Node Ver
 ### Your Responsibilities
 
 1. **Create or update `.nvmrc`**
-   - If the project has no `.nvmrc`, create one specifying the Node version.
-   - Default to `lts/*` if no version is already specified (e.g. in `package.json` engines, existing `.nvmrc`, or CI config).
+   - If the project has no `.nvmrc`, create one with the **current Node LTS** version (e.g. `24`). Check [Node.js Releases](https://nodejs.org/en/about/releases/) for the current Active LTS; as of this writing it is Node 24 (Krypton).
    - If a specific version is already used elsewhere, match it (e.g. `22`, `20`, `lts/hydrogen`).
+   - For **package.json** `engines` and **README** prerequisites/support text, use the **previous LTS** (one LTS back) as the minimum supported version (e.g. `22`) so the project documents support for both current and previous LTS. Example `engines`: `"node": ">=22"`. In the README, state e.g. "Node.js 22 (LTS) or 24 (Active LTS)" or "Use the version in `.nvmrc` (Node 24). Supported: Node 22+."
 
 2. **Use `.nvmrc` in the project**
    - Instruct developers to run `nvm use` (or `nvm install` if the version is not yet installed) when entering the project directory.
    - Consider adding shell integration (e.g. `direnv` with `use nvm`, or `.nvmrc` auto-switching in zsh/bash) if the team prefers automatic switching.
 
 3. **Update the README**
-   - Add a "Prerequisites" or "Getting started" subsection that instructs new contributors to:
+   - Add a "Prerequisites" or "Getting started" subsection that states supported Node version (previous LTS and current LTS, e.g. "Node.js 22 (LTS) or 24 (Active LTS)") and instructs new contributors to:
      1. Install nvm (e.g. `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash` or the latest from https://github.com/nvm-sh/nvm).
      2. Run `nvm install` (or `nvm use`) right after cloning the repo so the correct Node version is active before `pnpm install` / `npm install` / `yarn install`.
+   - In **package.json**, add or update `engines` with the previous LTS as minimum, e.g. `"engines": { "node": ">=22" }`.
 
 ### Example README Addition
 
 ````markdown
 ## Prerequisites
 
+- **Node.js**: Use the version in `.nvmrc`. Supported: Node 22 (LTS) or 24 (Active LTS). Run `nvm install` (or `nvm use`) after cloning so the correct Node version is active before `pnpm install`.
 - [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager)
 
 After cloning the repo, install and use the project's Node version:
@@ -53,6 +55,16 @@ nvm use       # switches to it (or run `nvm install` which does both)
 Then install dependencies: `pnpm install` (or `npm install` / `yarn`).
 ````
 
+### Example package.json engines
+
+Use the previous LTS as the minimum supported version (one LTS back from `.nvmrc`):
+
+```json
+"engines": {
+  "node": ">=22"
+}
+```
+
 ### Key Commands
 
 - `nvm install` — installs the version from `.nvmrc` (or `lts/*` if `.nvmrc` is missing)
@@ -74,7 +86,7 @@ When the user wants a Dockerfile and containerized local development for a Node.
 ### Your Responsibilities
 
 1. **Create a production-style Dockerfile**
-   - Use a Node LTS image (e.g. `node:22-bookworm`).
+   - Use a Node LTS image matching `.nvmrc` (e.g. `node:24-bookworm` for current Active LTS).
    - Set `WORKDIR /app`.
    - Copy only `package.json` and lockfile (`yarn.lock`, `pnpm-lock.yaml`, or `package-lock.json`) first.
    - Install dependencies with frozen lockfile and `--ignore-scripts` (e.g. `yarn install --frozen-lockfile --ignore-scripts`, or `pnpm install --frozen-lockfile --ignore-scripts`, or `npm ci --ignore-scripts`).
@@ -113,7 +125,7 @@ When the user wants a Dockerfile and containerized local development for a Node.
 **Dockerfile (yarn example):**
 
 ```dockerfile
-FROM node:22-bookworm
+FROM node:24-bookworm
 
 WORKDIR /app
 
@@ -129,7 +141,7 @@ CMD [ "yarn", "start" ]
 **Dockerfile (pnpm example):**
 
 ```dockerfile
-FROM node:22-bookworm
+FROM node:24-bookworm
 
 WORKDIR /app
 
@@ -187,3 +199,58 @@ Use `pnpm run dev` or `npm run dev` in `command` if the project uses that packag
 2. Tell the user how to build and run: `docker compose build`, then `docker compose up --watch` for local development.
 3. Mention that editing files under the watched path will sync and restart the service, and changing `package.json` will trigger a rebuild.
 4. Optionally suggest adding a short "Docker" or "Local development" section to the README with these commands.
+
+---
+
+## TypeScript Path Aliases (@/)
+
+When working with TypeScript projects, use the `@/` path alias for imports so that paths stay clean and stable regardless of file depth.
+
+### Your Responsibilities
+
+1. **Use `@/` for TypeScript imports**
+   - Prefer `import { foo } from '@/components/foo'` over `import { foo } from '../../../components/foo'`.
+   - The `@/` alias should resolve to the project's source root (typically `src/`).
+
+2. **Configure `tsconfig.json`**
+   - Add `baseUrl` and `paths` so TypeScript resolves `@/*` correctly.
+   - Ensure `baseUrl` points to the project root (or the directory containing `src/`).
+   - Map `@/*` to the source directory (e.g. `src/*`).
+
+3. **Configure the bundler/runtime**
+   - If using `tsc` only: `paths` in `tsconfig.json` is sufficient for type-checking, but the build output may need a resolver (e.g. `tsconfig-paths`) unless the bundler handles it.
+   - If using Vite, Next.js, or similar: they read `tsconfig.json` paths automatically.
+   - If using plain `tsc`: consider `tsconfig-paths` at runtime, or a bundler that resolves paths.
+
+### Example tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"]
+}
+```
+
+If the project root is the repo root and source lives in `src/`, this maps `@/utils/foo` → `src/utils/foo`.
+
+### Example Imports
+
+```typescript
+// Prefer
+import { formatDate } from '@/utils/date';
+import { Button } from '@/components/Button';
+
+// Avoid deep relative paths
+import { formatDate } from '../../../utils/date';
+```
+
+### When to Apply
+
+- When creating or configuring a new TypeScript project.
+- When a project uses long relative import chains (`../../../`).
+- When `tsconfig.json` exists but has no `paths` or `baseUrl` for `@/`.

package/agents/logging/content.md

@@ -1,6 +1,6 @@
 # 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, to wire up browser-side logging to a Next.js `/api/logs` endpoint, and to add structured logging for CLI tools.
+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
 
@@ -24,70 +24,7 @@ pnpm add pino pino-fluentd pino-transmit-http @fluent-org/logger
 - **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)
 
-For **CLI projects only**, you need just:
-
-```bash
-pnpm add pino pino-pretty
-```
-
-- **pino-pretty**: Pretty-prints logs for human readability in development (optional, devDependency)
-
-### 2. CLI Projects: Pino for Command-Line Tools
-
-For CLI tools (e.g. `ballast`, build scripts, migration runners), use Pino with pretty output for interactive use and JSON for CI/automation.
-
-Create `src/lib/logger.ts` (or `lib/logger.ts`):
-
-```typescript
-import pino from 'pino';
-
-const isProd = process.env.NODE_ENV === 'production';
-const isCi = process.env.CI === 'true' || process.env.CI === '1';
-const logLevel = process.env.LOG_LEVEL ?? (isProd ? 'error' : 'debug');
-
-// Pretty output for humans (TTY or dev), JSON for CI/automation
-const usePretty = !isProd && !isCi && (process.stdout.isTTY ?? false);
-
-export const logger = pino({
-  level: logLevel,
-  ...(usePretty
-    ? {
-        transport: {
-          target: 'pino-pretty',
-          options: {
-            colorize: true,
-            translateTime: 'SYS:HH:MM:ss'
-          }
-        }
-      }
-    : {})
-});
-```
-
-**Usage in CLI code:**
-
-```typescript
-import { logger } from './lib/logger';
-
-// Instead of console.log('Installing rules...'):
-logger.info('Installing rules');
-
-// With structured data:
-logger.debug({ target: 'cursor', agents: ['linting'] }, 'Resolved config');
-
-// Errors:
-logger.error({ err }, 'Install failed');
-```
-
-**Pipe to Fluentd when running in CI/CD:**
-
-```bash
-node dist/cli.js install --all 2>&1 | pino-fluentd --host 127.0.0.1 --port 24224 --tag cli
-```
-
-For CLI projects, omit pino-transmit-http, pino-fluentd, and @fluent-org/logger unless you need Fluentd integration. Use `pino-pretty` as a devDependency so production installs stay lean.
-
-### 3. Server-Side: Node.js and Next.js API
+### 2. Server-Side: Node.js and Next.js API
 
 #### Option A: Pipe to pino-fluentd (recommended for Node.js)
 
@@ -169,7 +106,7 @@ export const logger = stream
   : pino({ level: logLevel });
 ```
 
-### 4. Next.js API: `/api/logs` endpoint
+### 3. Next.js API: `/api/logs` endpoint
 
 Create `src/app/api/logs/route.ts` (App Router) or `pages/api/logs.ts` (Pages Router):
 
@@ -232,7 +169,7 @@ export default async function handler(
 }
 ```
 
-### 5. Browser-Side: pino-browser with pino-transmit-http
+### 4. Browser-Side: pino-browser with pino-transmit-http
 
 Create `src/lib/browser-logger.ts` (or `lib/browser-logger.ts`):
 
@@ -256,7 +193,7 @@ export const browserLogger = pino({
 });
 ```
 
-### 6. Wire Up Global Error Handlers (Browser)
+### 5. Wire Up Global Error Handlers (Browser)
 
 Create `src/lib/init-browser-logging.ts` and import it from your root layout or `_app`:
 
@@ -334,7 +271,7 @@ export default function App({ Component, pageProps }) {
 }
 ```
 
-### 7. Use the Browser Logger
+### 6. Use the Browser Logger
 
 Replace `console.log` with the browser logger in client components:
 
@@ -348,7 +285,7 @@ browserLogger.debug({ data }, 'User clicked');
 browserLogger.error({ err }, 'Something failed');
 ```
 
-### 8. Environment Variables
+### 7. Environment Variables
 
 Add to `.env.example`:
 
@@ -367,7 +304,7 @@ FLUENT_ENABLED=false
 
 For production, set `FLUENT_ENABLED=true` and configure `FLUENT_HOST` / `FLUENT_PORT` to point to your Fluentd instance.
 
-### 9. Fluentd Configuration (Reference)
+### 8. Fluentd Configuration (Reference)
 
 Minimal Fluentd config to receive logs on port 24224:
 
@@ -387,15 +324,6 @@ Replace `@type stdout` with `@type elasticsearch`, `@type s3`, or another output
 
 ## Implementation Order
 
-**For CLI projects:**
-
-1. Install pino and pino-pretty (pino-pretty as devDependency)
-2. Create `lib/logger.ts` with pretty output for TTY and JSON for CI
-3. Replace `console.log` / `console.error` with `logger.info` / `logger.error`
-4. Add `LOG_LEVEL` to `.env.example` if using env files
-
-**For server/browser projects:**
-
 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
@@ -416,7 +344,6 @@ Override with `LOG_LEVEL` (server) or `NEXT_PUBLIC_LOG_LEVEL` (browser).
 
 ## Important Notes
 
-- **CLI projects**: Use Pino with pino-pretty for human-readable output when running interactively (TTY). In CI (`CI=true`), output stays as JSON for parsing. Omit browser and Fluentd deps unless you need them.
 - 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.

package/agents/testing/content.md

@@ -0,0 +1,122 @@
+# 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/agents/testing/templates/claude-header.md

@@ -0,0 +1,5 @@
+# Testing Rules
+
+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.
+
+---

package/agents/testing/templates/codex-header.md

@@ -0,0 +1,7 @@
+# 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.
+
+---

package/agents/testing/templates/cursor-frontmatter.yaml

@@ -0,0 +1,15 @@
+---
+description: 'Testing specialist - sets up Jest (default) or Vitest for Vite projects, 50% coverage, and test step in build GitHub Action'
+alwaysApply: false
+globs:
+  - '*.ts'
+  - '*.tsx'
+  - '*.js'
+  - '*.jsx'
+  - 'jest.config.*'
+  - 'vitest.config.*'
+  - 'vite.config.*'
+  - 'package.json'
+  - '.github/workflows/*.yml'
+  - '.github/workflows/*.yaml'
+---

package/agents/testing/templates/opencode-frontmatter.yaml

@@ -0,0 +1,22 @@
+---
+description: Sets up Jest (default) or Vitest for Vite projects with 50% coverage and test step in build GitHub Action
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+permission:
+  bash:
+    'git *': ask
+    'npm *': allow
+    'npx *': allow
+    'yarn *': allow
+    'pnpm *': allow
+    'cat *': allow
+    '*': ask
+---

package/dist/agents.d.ts

@@ -1,5 +1,5 @@
 declare const PACKAGE_ROOT: string;
-export declare const AGENT_IDS: readonly ["linting", "local-dev", "cicd", "observability", "logging"];
+export declare const AGENT_IDS: readonly ["linting", "local-dev", "cicd", "observability", "logging", "testing"];
 export type AgentId = (typeof AGENT_IDS)[number];
 /**
  * Resolve path to an agent directory

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,YAAY,QAA6B,CAAC;AAEhD,eAAO,MAAM,SAAS,uEAMZ,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjE;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,YAAY,QAA6B,CAAC;AAEhD,eAAO,MAAM,SAAS,kFAOZ,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,MAAM,EAAE,CAErC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAQjE;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/agents.js

@@ -16,7 +16,8 @@ exports.AGENT_IDS = [
     'local-dev',
     'cicd',
     'observability',
-    'logging'
+    'logging',
+    'testing'
 ];
 /**
  * Resolve path to an agent directory

package/dist/agents.js.map

@@ -1 +1 @@
-{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":";;;;;;AAgBA,kCAEC;AAKD,gCAEC;AAKD,oCAEC;AAKD,sCAQC;AA7CD,gDAAwB;AAExB,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AA6CvC,oCAAY;AA3CR,QAAA,SAAS,GAAG;IACvB,SAAS;IACT,WAAW;IACX,MAAM;IACN,eAAe;IACf,SAAS;CACD,CAAC;AAGX;;GAEG;AACH,SAAgB,WAAW,CAAC,OAAe;IACzC,OAAO,cAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU;IACxB,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,OAAe;IAC1C,OAAQ,iBAA+B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,MAAyB;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAC/C,IAAI,MAAM;YAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;IAC/C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":";;;;;;AAiBA,kCAEC;AAKD,gCAEC;AAKD,oCAEC;AAKD,sCAQC;AA9CD,gDAAwB;AAExB,MAAM,YAAY,GAAG,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AA8CvC,oCAAY;AA5CR,QAAA,SAAS,GAAG;IACvB,SAAS;IACT,WAAW;IACX,MAAM;IACN,eAAe;IACf,SAAS;IACT,SAAS;CACD,CAAC;AAGX;;GAEG;AACH,SAAgB,WAAW,CAAC,OAAe;IACzC,OAAO,cAAI,CAAC,IAAI,CAAC,YAAY,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU;IACxB,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY,CAAC,OAAe;IAC1C,OAAQ,iBAA+B,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAC5D,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa,CAAC,MAAyB;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC;QAC/C,IAAI,MAAM;YAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;QACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,iBAAS,CAAC,KAAK,EAAE,CAAC;IAC/C,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9C,CAAC"}

package/dist/cli.js

@@ -64,7 +64,7 @@ Commands:
 
 Options:
   --target, -t <platform>   AI platform: cursor, claude, opencode, codex
-  --agent, -a <agents>      Agent(s): linting, local-dev, cicd, observability (comma-separated)
+  --agent, -a <agents>      Agent(s): linting, local-dev, cicd, observability, logging, testing (comma-separated)
   --all                     Install all agents
   --force, -f               Overwrite existing rule files
   --yes, -y                 Non-interactive; require --target and --agent/--all if no .rulesrc.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everydaydevopsio/ballast",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "CLI to install TypeScript AI agent rules (linting, local-dev, CI/CD, observability, logging) for Cursor, Claude Code, and OpenCode",
   "main": "dist/cli.js",
   "bin": {
@@ -22,12 +22,12 @@
     "url": "https://github.com/everydaydevopsio/ballast/issues"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.2.0",
     "@typescript-eslint/eslint-plugin": "^8.54.0",
     "@typescript-eslint/parser": "^8.54.0",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "globals": "^17.3.0",