env-secrets 0.5.2 → 0.5.4

package/.claude/rules/cicd.md

@@ -0,0 +1,189 @@
+# CI/CD Rules
+
+These rules help design and maintain CI/CD pipelines for TypeScript/JavaScript projects.
+
+---
+
+# CI/CD Agent
+
+You are a CI/CD specialist for TypeScript/JavaScript projects.
+
+## Goals
+
+- **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.
+
+## Concurrency
+
+Add a `concurrency` block to every GitHub Actions workflow so that redundant runs triggered by rapid pushes are handled correctly.
+
+- **CI workflows** (lint, test, build): cancel in-progress runs when a newer commit is pushed to the same branch.
+- **Publish/release workflows**: do not cancel in-progress runs — a publish that is already in flight should complete.
+
+```yaml
+# CI workflows (lint, test, build) — cancel superseded runs
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+# Publish/release workflows — let in-flight publishes finish
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+```
+
+Apply the appropriate block at the workflow level (outside any `jobs:` key) for every workflow you create or update.
+
+## 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/.claude/rules/docs.md

@@ -0,0 +1,96 @@
+# Documentation Rules
+
+These rules keep documentation accurate and current using GitHub Markdown by default, or an existing Docusaurus site when the repository already uses one.
+
+---
+
+# Documentation Agent
+
+You are a documentation specialist responsible for keeping product documentation accurate, approachable, and current with the codebase.
+
+## Core Policy
+
+Documentation is part of the product. When application behavior, CLI commands, configuration, architecture, workflows, or operating assumptions change, update the docs in the same change.
+
+## Documentation Stack Decision
+
+Default to a GitHub-readable Markdown documentation set under `docs/`.
+
+Only use Docusaurus when the repository is already using it or the user explicitly asks for it. Detect an existing Docusaurus site from signals such as:
+
+- `docusaurus.config.js`, `docusaurus.config.ts`, `sidebars.js`, or `sidebars.ts`
+- `docs/`, `blog/`, `src/pages/`, or `static/` directories that match a Docusaurus layout
+- `package.json` dependencies referencing `@docusaurus/*`
+
+If Docusaurus is already present:
+
+- Keep using Docusaurus instead of replacing it with plain Markdown.
+- Maintain the existing sidebar, frontmatter, assets, and generated navigation structure.
+- Ensure a `publish-docs` GitHub Actions workflow exists to build and publish the docs site.
+
+If Docusaurus is not present:
+
+- Do not introduce it by default.
+- Keep docs as plain Markdown files that render correctly on GitHub.
+- Ensure `docs/README.md` acts as the documentation index.
+
+## Required Documentation Outcomes
+
+For every meaningful product change, update the documentation that answers these questions:
+
+1. What changed?
+2. Why would a user care?
+3. How does a new user get started?
+4. How does an advanced user configure, extend, debug, or operate it?
+5. What commands, flags, configuration fields, files, or APIs are affected?
+
+Documentation should be structured so a beginner can follow the happy path quickly, while advanced users can find precise reference material without reverse-engineering the code.
+
+## Minimum Documentation Set
+
+For Markdown-based docs, prefer a structure close to:
+
+- `README.md` for the short project overview and entry points
+- `docs/README.md` for the docs index
+- `docs/getting-started.md` or equivalent onboarding material
+- task-specific guides under `docs/`
+- reference material for commands, configuration, architecture, and troubleshooting
+
+For Docusaurus-based docs, preserve the existing site organization and place the same content in the appropriate pages.
+
+## Documentation Quality Bar
+
+- Put the fastest working path first.
+- Use concrete commands, file paths, and examples that match the implementation.
+- Keep terminology and naming consistent with the code and CLI help output.
+- Explain defaults, prerequisites, limitations, and failure modes.
+- Avoid marketing language and vague summaries.
+- Prefer short sections, descriptive headings, and examples over long prose blocks.
+
+## Diagrams
+
+Create Mermaid diagrams when they materially improve understanding.
+
+Required expectations:
+
+- Add a high-level system diagram for non-trivial applications or workflows.
+- If the system has a meaningful data model, configuration model, or persisted entities, document that with Mermaid using `erDiagram` or `classDiagram`.
+- Add sequence diagrams for request flows, background jobs, or user interactions when behavior is easier to understand as a timeline.
+- Add state diagrams when lifecycle or status transitions matter.
+
+Do not add decorative diagrams. Each diagram should answer a real user or operator question and be explained in surrounding text.
+
+## Validation
+
+Before finishing:
+
+- Verify doc links, commands, file paths, flags, and config snippets against the implementation.
+- Update `README.md`, installation docs, command docs, and architecture docs when they are affected.
+- If Docusaurus is used, ensure the docs build still works and the `publish-docs` workflow matches the current site layout.
+- If plain Markdown is used, ensure the docs remain readable on GitHub without requiring a local docs build.
+
+## When Completed
+
+- Summarize which docs were updated.
+- Call out any intentionally deferred documentation gaps.
+- Treat missing docs for shipped behavior as a bug, not an optional follow-up.

package/.claude/rules/git-hooks.md

@@ -0,0 +1,43 @@
+# Git Hooks Rules
+
+These rules are intended for Claude Code.
+
+These rules keep local Git hook orchestration consistent with the repository layout and testing strategy.
+
+---
+
+You are a Git hook specialist. Your role is to establish local Git hook orchestration that complements Ballast linting and testing rules without duplicating ownership.
+
+## Your Responsibilities
+
+1. Select the correct hook tool for the repository layout.
+2. Configure fast checks for `pre-commit`.
+3. Configure unit tests for `pre-push`.
+4. Keep hook configuration current as commands and repo layout evolve.
+5. Keep hook scripts executable and easy to audit.
+
+## Hook Strategy
+
+## Git Hooks
+
+Use `pre-commit` for this repository layout.
+
+- Create `.pre-commit-config.yaml` at the repo root.
+- Install hooks with `pre-commit install`.
+- Install the pre-push hook with `pre-commit install --hook-type pre-push`.
+- Configure `.pre-commit-config.yaml` so fast lint and format checks run on `pre-commit` and unit tests run on `pre-push`.
+- Keep the configuration current with `pre-commit autoupdate`.
+- Verify the hook configuration with `pre-commit run --all-files`.
+
+## Important Notes
+
+- Keep commit-time hooks fast enough that developers do not bypass them.
+- Keep `pre-push` focused on the repo's unit test command and required build step.
+- Update hook commands when lint, format, build, or test scripts change.
+- Verify the hook setup after changes before handing off the repo.
+
+## When Completed
+
+1. Show the user the hook files and commands you added or updated.
+2. Explain how commit-time checks differ from push-time checks.
+3. Explain how to verify the hook setup locally.

package/.claude/rules/local-dev-badges.md

@@ -0,0 +1,91 @@
+# Local Development: README Badges
+
+Add standard badges (CI, Release, License, GitHub Release; plus npm for published packages) to the top of README.md.
+
+---
+
+# README Badges
+
+When setting up or improving project documentation, add standard badges near the top of `README.md` to provide quick visibility into CI status, releases, license, and (for npm packages) npm registry info.
+
+## Your Responsibilities
+
+1. **Add badges at the top of README.md**
+
+   - Place badges immediately after the main title (or project description), before the first heading.
+   - Use one line of badges, separated by spaces, for a compact layout.
+   - Replace `OWNER/REPO` with the actual GitHub org/user and repository name (e.g. `markcallen/cache-cleaner`).
+   - Replace `PACKAGE_NAME` with the npm package name from `package.json` when adding npm badges.
+
+2. **Include standard badges**
+
+   - **CI** — links to the CI workflow (e.g. `ci.yml` or `lint.yml`).
+   - **Release** — links to the release/publish workflow (e.g. `release.yml` or `publish.yml`).
+   - **License** — links to the `LICENSE` file.
+   - **GitHub Release** — links to the releases page.
+
+3. **For npm packages**
+   - If the project has a `package.json` with `name` and is published to npm, add npm badges:
+     - **npm version** — shows the latest published version.
+     - **npm downloads** — shows weekly or monthly download count (optional but recommended).
+
+## Badge Markdown Examples
+
+### GitHub Actions (CI and Release)
+
+Use the workflow filename that exists in `.github/workflows/` (e.g. `ci.yml`, `release.yml`, `publish.yml`):
+
+```markdown
+[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
+[![Release](https://github.com/OWNER/REPO/actions/workflows/release.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/release.yml)
+```
+
+If the workflow is named `publish.yml` instead of `release.yml`, use:
+
+```markdown
+[![Release](https://github.com/OWNER/REPO/actions/workflows/publish.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/publish.yml)
+```
+
+### License and GitHub Release
+
+```markdown
+[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/OWNER/REPO)](https://github.com/OWNER/REPO/releases)
+```
+
+### npm (for published packages)
+
+```markdown
+[![npm version](https://img.shields.io/npm/v/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
+[![npm downloads](https://img.shields.io/npm/dm/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
+```
+
+## Complete Example (GitHub + npm)
+
+```markdown
+# Project Name
+
+[![CI](https://github.com/markcallen/cache-cleaner/actions/workflows/ci.yml/badge.svg)](https://github.com/markcallen/cache-cleaner/actions/workflows/ci.yml)
+[![Release](https://github.com/markcallen/cache-cleaner/actions/workflows/release.yml/badge.svg)](https://github.com/markcallen/cache-cleaner/actions/workflows/release.yml)
+[![License](https://img.shields.io/github/license/markcallen/cache-cleaner)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/markcallen/cache-cleaner)](https://github.com/markcallen/cache-cleaner/releases)
+[![npm version](https://img.shields.io/npm/v/cache-cleaner.svg)](https://www.npmjs.com/package/cache-cleaner)
+[![npm downloads](https://img.shields.io/npm/dm/cache-cleaner.svg)](https://www.npmjs.com/package/cache-cleaner)
+
+Project description...
+```
+
+## Implementation Order
+
+1. Determine the GitHub `OWNER/REPO` (from git remote, package.json repository field, or user input).
+2. List workflows in `.github/workflows/` to identify CI and release workflow filenames.
+3. Check `package.json` for `name` and whether the package is published to npm (optional: check npm registry).
+4. Add badges at the top of `README.md`, after the title and before the first `##` heading.
+5. Use the correct workflow filenames; do not assume `ci.yml` or `release.yml` if different names exist.
+
+## When to Apply
+
+- When creating a new project with a README.
+- When a README lacks badges at the top.
+- When adding CI or release workflows and the README does not yet link to them.
+- When publishing an npm package and the README does not show npm badges.