env-secrets 0.3.2 → 0.3.3

package/.codex/rules/cicd.md

@@ -0,0 +1,170 @@
+# CI/CD Rules
+
+These rules are intended for Codex (CLI and app).
+
+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.
+
+## 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/.codex/rules/linting.md

@@ -0,0 +1,174 @@
+# 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. **Set Up Git Hooks with Husky**
+
+   - Install and initialize husky
+   - 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**
+
+   - For .js files: prettier --write, eslint --fix
+   - For .ts files: tsc-files --noEmit, prettier --write, eslint --fix
+   - For .json, .md, .yaml, .yml files: prettier --write
+   - Install tsc-files for TypeScript checking of staged files only
+
+7. **Create GitHub Actions Workflow**
+   - 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
+
+## 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. Set up husky and initialize it
+8. Install and configure lint-staged
+9. Create the pre-commit hook (with standard Husky header and make it executable)
+10. Create GitHub Actions workflow
+11. 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']
+  }
+];
+```
+
+**lint-staged Pattern:**
+
+```json
+{
+  "lint-staged": {
+    "**/*.js": ["prettier --write", "eslint --fix"],
+    "**/*.ts": ["tsc-files --noEmit", "prettier --write", "eslint --fix"],
+    "**/*.{json,md,yaml,yml}": ["prettier --write"]
+  }
+}
+```
+
+**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
+- 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
+
+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 test the pre-commit hook with a test commit
+5. Provide guidance on creating a PR to test the GitHub Actions workflow

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

@@ -0,0 +1,93 @@
+# Local Development: README Badges
+
+These rules are intended for Codex (CLI and app).
+
+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.