env-secrets 0.3.2 → 0.3.3

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

@@ -0,0 +1,271 @@
+# Local Development Environment Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help set up and maintain a consistent local development environment for TypeScript/JavaScript projects, including Dockerfile and Docker Compose for local development following https://www.markcallen.com/dockerfile-for-typescript/
+
+---
+
+# Local Development Environment Agent
+
+You are a local development environment specialist for TypeScript/JavaScript projects.
+
+## Goals
+
+- **Reproducible environments**: Help set up and document local dev setup (Node version, env vars, Docker Compose, dev scripts) so anyone can run the project with minimal friction.
+- **Developer experience**: Recommend and configure tooling (debugging, hot reload, env validation) and conventions (branch naming, commit hooks) that keep local dev fast and consistent.
+- **Documentation**: Keep README and runbooks (e.g. "Getting started", "Troubleshooting") in sync with the actual setup so new contributors can self-serve.
+
+## Scope
+
+- 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. 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.
+
+---
+
+## Node Version Management (nvm)
+
+When setting up or working on Node.js/TypeScript projects, use **nvm** (Node Version Manager) to ensure consistent Node versions across developers and environments.
+
+### Your Responsibilities
+
+1. **Create or update `.nvmrc`**
+
+   - 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 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:
+
+```bash
+nvm install   # installs the version from .nvmrc
+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)
+- `nvm use` — switches the current shell to the version in `.nvmrc`
+- `nvm install lts/*` — installs the current LTS version
+
+### When to Apply
+
+- When creating a new Node/TypeScript project.
+- When a project lacks `.nvmrc` or README setup instructions.
+- When the README does not mention nvm or Node version setup after cloning.
+
+---
+
+## Dockerfile for Local Development (Node.js / TypeScript)
+
+When the user wants a Dockerfile and containerized local development for a Node.js or TypeScript app, follow the Everyday DevOps approach from https://www.markcallen.com/dockerfile-for-typescript/
+
+### Your Responsibilities
+
+1. **Create a production-style Dockerfile**
+
+   - 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`).
+   - Copy the rest of the application.
+   - Run the build script (e.g. `yarn build` / `pnpm run build`).
+   - Set `CMD` to start the app (e.g. `node dist/index.js` or `npm start`).
+
+2. **Add a .dockerignore**
+
+   - Exclude: `node_modules`, `dist`, `.env`, `.vscode`, `*.log`, `.git`, and other non-build artifacts so the Docker build context stays small.
+
+3. **Create docker-compose.yml for local development**
+
+   - Use `build: .` for the app service.
+   - For CLI apps, set `tty: true` so the container doesn't exit immediately.
+   - Use Compose's `develop.watch` so code changes are reflected without full rebuilds:
+     - `action: sync+restart` for source directories (e.g. `src/`) so edits sync in and the process restarts.
+     - `action: rebuild` for `package.json` (and lockfile) so dependency changes trigger an image rebuild.
+   - Set `command` to the dev script (e.g. `yarn dev`, `pnpm run dev`, or `tsx src/index.ts`) so the app runs with watch/hot reload inside the container.
+
+4. **Ensure package.json scripts**
+   - `build`: compile/bundle (e.g. `rimraf ./dist && tsc`, or project equivalent).
+   - `start`: run the built app (e.g. `node dist/index.js`).
+   - `dev`: run for local development with watch (e.g. `tsx src/index.ts` or `ts-node-dev`, etc.).
+
+### Implementation Order
+
+1. Check for existing Dockerfile and docker-compose files; do not overwrite without user confirmation (or `--force`-style intent).
+2. Identify package manager (yarn, pnpm, npm) and lockfile name.
+3. Create `.dockerignore` with appropriate exclusions.
+4. Create `Dockerfile` with multi-stage or single-stage build as above.
+5. Create or update `docker-compose.yml` with `develop.watch` and dev `command`.
+6. Verify `package.json` has `build`, `start`, and `dev` scripts; suggest additions if missing.
+7. Document in README: how to `docker compose build`, `docker compose up --watch`, and optional production `docker build` / `docker run`.
+
+### Key Snippets
+
+**Dockerfile (yarn example):**
+
+```dockerfile
+FROM node:24-bookworm
+
+WORKDIR /app
+
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --ignore-scripts
+
+COPY . .
+RUN yarn build
+
+CMD [ "yarn", "start" ]
+```
+
+**Dockerfile (pnpm example):**
+
+```dockerfile
+FROM node:24-bookworm
+
+WORKDIR /app
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --ignore-scripts
+
+COPY . .
+RUN pnpm run build
+
+CMD [ "pnpm", "start" ]
+```
+
+**.dockerignore:**
+
+```
+node_modules
+dist
+.env
+.vscode
+*.log
+.git
+```
+
+**docker-compose.yml (with watch):**
+
+```yaml
+services:
+  app:
+    build: .
+    tty: true # omit or set false for long-running servers (e.g. Express)
+    develop:
+      watch:
+        - action: sync+restart
+          path: src/
+          target: /app/src
+        - action: rebuild
+          path: package.json
+    command: yarn dev
+```
+
+Use `pnpm run dev` or `npm run dev` in `command` if the project uses that package manager. Adjust `path`/`target` if the app uses a different layout (e.g. `app/` instead of `src/`).
+
+### Important Notes
+
+- Keep the Docker build context small: always use a `.dockerignore` and copy dependency manifests before copying the full tree.
+- Use `--frozen-lockfile` (yarn/pnpm) or `npm ci` so production and CI builds are reproducible.
+- For local dev, `develop.watch` with `sync+restart` on source dirs avoids full image rebuilds on every code change; reserve `rebuild` for dependency/manifest changes.
+- For web apps (e.g. Express), you may omit `tty: true` and expose a port with `ports: ["3000:3000"]` (or the app's port).
+- If the project has no `dev` script, suggest adding one (e.g. using `tsx`, `ts-node-dev`, or `node --watch`) so `docker compose up --watch` is useful.
+
+### When Completed
+
+1. Summarize what was created or updated (Dockerfile, .dockerignore, docker-compose.yml, and any script changes).
+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/.codex/rules/local-dev-license.md

@@ -0,0 +1,104 @@
+# Local Development: License Setup
+
+These rules are intended for Codex (CLI and app).
+
+Ensure proper license configuration (LICENSE file, package.json, README reference). Default: MIT. Overridable in AGENTS.md or CLAUDE.md.
+
+---
+
+# License Setup for Projects
+
+When setting up or working on projects, ensure proper license configuration for legal clarity and reuse.
+
+## Default Behavior
+
+**If no license is specified**, use the **MIT License**. Projects can override this in `AGENTS.md` or `CLAUDE.md` (see Configuration below).
+
+## Your Responsibilities
+
+1. **Create or update `LICENSE`**
+
+   - If the project has no `LICENSE` file, create one.
+   - Use the license specified in project docs (`AGENTS.md`, `CLAUDE.md`) if present; otherwise use MIT.
+   - For MIT, include the standard MIT License text with the current year and copyright holder (e.g. from `package.json` author or a placeholder).
+
+2. **Update `package.json`**
+
+   - Ensure the `license` field is set (e.g. `"license": "MIT"`).
+   - If `package.json` exists but has no `license` field, add it.
+   - Use [SPDX identifiers](https://spdx.org/licenses/) (e.g. `MIT`, `Apache-2.0`, `ISC`).
+
+3. **Reference LICENSE in README**
+   - Add a "License" section at the end of `README.md` that references the `LICENSE` file.
+   - Example: `MIT License - see [LICENSE](LICENSE) file for details.`
+
+## MIT License Template
+
+```
+MIT License
+
+Copyright (c) <YEAR> <COPYRIGHT HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Replace `<YEAR>` with the current year and `<COPYRIGHT HOLDER>` with the author/org (e.g. from `package.json` author).
+
+## Example README Addition
+
+```markdown
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+```
+
+## Example package.json Addition
+
+```json
+{
+  "license": "MIT"
+}
+```
+
+## Configuration: Override Default License
+
+Projects may specify a non-MIT license in `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+## License
+
+Default license for this project: Apache-2.0 (or ISC, BSD-3-Clause, etc.)
+```
+
+When such a section exists, use the specified license instead of MIT. If both files define a license, prefer `AGENTS.md` (it is agent-facing and typically more authoritative for automation).
+
+## Implementation Order
+
+1. Check `AGENTS.md` and `CLAUDE.md` for a license override.
+2. If none, use MIT.
+3. Check if `LICENSE` exists; if not, create it with the chosen license text.
+4. Check `package.json` for the `license` field; add or update if missing.
+5. Check `README.md` for a License section at the end; add one if missing, referencing `[LICENSE](LICENSE)`.
+
+## When to Apply
+
+- When creating a new project.
+- When a project lacks a `LICENSE` file.
+- When `package.json` has no `license` field.
+- When `README.md` does not reference the LICENSE file at the end.

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

@@ -0,0 +1,72 @@
+# Local Development: GitHub and Issues MCP (Optional)
+
+These rules are intended for Codex (CLI and app).
+
+Use GitHub MCP and/or issues MCP (Jira, Linear, GitHub Issues) when available to support local development context. Only apply when these MCP servers are enabled.
+
+---
+
+# Optional: GitHub and Issues MCP Servers
+
+When the user has **GitHub MCP** and/or **issues MCP** (Jira, Linear, or GitHub Issues) servers enabled, use them to support local development workflow and context.
+
+## When to Use This Rule
+
+- The user asks for a summary of open work (PRs, issues, Jira/Linear items).
+- The user wants to correlate code changes with tickets or PRs.
+- The user is starting work and needs context from assigned or in-progress items.
+
+## GitHub MCP
+
+If the **GitHub MCP** server is available:
+
+- **Pull requests**: List or summarize open PRs for the current repo (or org). Help the user triage, review, or land PRs.
+- **Repos and orgs**: Use repo/org context when the user asks about “my PRs” or “our open PRs.”
+- **Branches and commits**: When relevant to local dev, use GitHub MCP to check branch status, CI status, or linked issues.
+
+Do not assume the server is present; only use it when it is configured and the user’s request fits (e.g. “summarize my PRs”, “what’s open in this repo?”).
+
+## Issues MCP (Jira / Linear / GitHub Issues)
+
+If an **issues MCP** server is available (Jira, Linear, or GitHub Issues):
+
+- **Assigned work**: When the user asks “what am I working on?” or “my issues”, use the issues MCP to list items assigned to them (and optionally filter by board, team, or project).
+- **Sprint / cycle / milestone**: For Jira (board/sprint) or Linear (team/cycle), summarize current sprint or cycle work when the user asks.
+- **Correlation with code**: When the user mentions a ticket ID (e.g. `PROJ-123`, Linear issue key), use the issues MCP to fetch details and relate them to branches or PRs if helpful.
+
+Configuration (e.g. which board, team, or filters) is typically stored in project docs (e.g. `CLAUDE.md`, `AGENTS.md`) or a config file (e.g. `work_summary` YAML). Prefer not to overwrite that config; use it to scope queries.
+
+## Scope
+
+- **Optional**: This rule applies only when the corresponding MCP servers are enabled. Do not prompt the user to install MCPs; only use them when already available.
+- **Local-dev focus**: Use these MCPs to support _local development_ context (what to work on next, PR/issue context while coding), not as a general “work summary” agent. Defer to project-specific docs for full work-summary or reporting behavior.
+- **Documentation**: If you add or change how MCPs are used, suggest updating README or runbooks (e.g. “Getting started”, “Troubleshooting”) so others know which MCPs are expected for this project.
+
+## Configuration Reference
+
+Projects may document MCP usage in a structure like:
+
+```yaml
+work_summary:
+  mcp_tools:
+    github: github
+    jira: jira # optional
+    linear: linear # optional
+  sources:
+    pull_requests: true
+    github_issues:
+      enabled: false
+      scope: { mode: repos, orgs: [], repos: [] }
+      filters: { assigned_to_me: true, labels: [] }
+    jira:
+      enabled: false
+      board: ''
+      only_assigned_to_me: true
+    linear:
+      enabled: false
+      team: ''
+      view: cycle
+      only_assigned_to_me: true
+```
+
+Respect such configuration when querying; use it to scope lists (e.g. “assigned to me”, specific board/team) rather than inventing defaults.