From 6d93faf1a7cf419611fae133f25d75e4d7089a05 Mon Sep 17 00:00:00 2001 From: Michael Salzmann Date: Tue, 14 Apr 2026 11:57:22 +0200 Subject: [PATCH 1/4] chore: add AI tooling configuration and agent skills Install agent skills, MCP server config, and AGENTS.md project context files generated by the shared skills installer. Co-Authored-By: Claude Opus 4.6 (1M context) --- .agents/skills/pr-review-navigator/SKILL.md | 167 ++++++ .agents/skills/remember/SKILL.md | 194 +++++++ .agents/skills/renovate-migrate/SKILL.md | 156 ++++++ .agents/skills/renovate-review/SKILL.md | 143 +++++ .agents/skills/repo-healthcheck-node/SKILL.md | 183 +++++++ .agents/skills/repo-maintenance-node/SKILL.md | 373 +++++++++++++ .agents/skills/security-auditor/SKILL.md | 511 ++++++++++++++++++ .claude/.gitignore | 5 + .claude/settings.json | 16 + .claude/skills/pr-review-navigator | 1 + .claude/skills/remember | 1 + .claude/skills/renovate-migrate | 1 + .claude/skills/renovate-review | 1 + .claude/skills/repo-healthcheck-node | 1 + .claude/skills/repo-maintenance-node | 1 + .claude/skills/security-auditor | 1 + .mcp.json | 20 + AGENTS.md | 120 ++++ CLAUDE.md | 37 ++ generators/AGENTS.md | 25 + generators/CLAUDE.md | 4 + skills-lock.json | 40 ++ standalone/AGENTS.md | 51 ++ standalone/CLAUDE.md | 4 + 24 files changed, 2056 insertions(+) create mode 100644 .agents/skills/pr-review-navigator/SKILL.md create mode 100644 .agents/skills/remember/SKILL.md create mode 100644 .agents/skills/renovate-migrate/SKILL.md create mode 100644 .agents/skills/renovate-review/SKILL.md create mode 100644 .agents/skills/repo-healthcheck-node/SKILL.md create mode 100644 .agents/skills/repo-maintenance-node/SKILL.md create mode 100644 .agents/skills/security-auditor/SKILL.md create mode 100644 .claude/.gitignore create mode 100644 .claude/settings.json create mode 120000 .claude/skills/pr-review-navigator create mode 120000 .claude/skills/remember create mode 120000 .claude/skills/renovate-migrate create mode 120000 .claude/skills/renovate-review create mode 120000 .claude/skills/repo-healthcheck-node create mode 120000 .claude/skills/repo-maintenance-node create mode 120000 .claude/skills/security-auditor create mode 100644 .mcp.json create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 generators/AGENTS.md create mode 100644 generators/CLAUDE.md create mode 100644 skills-lock.json create mode 100644 standalone/AGENTS.md create mode 100644 standalone/CLAUDE.md diff --git a/.agents/skills/pr-review-navigator/SKILL.md b/.agents/skills/pr-review-navigator/SKILL.md new file mode 100644 index 000000000..58a6de88b --- /dev/null +++ b/.agents/skills/pr-review-navigator/SKILL.md @@ -0,0 +1,167 @@ +--- +name: pr-review-navigator +description: Generate AI-assisted navigation aids to help humans start reviewing a pull request more efficiently. +disable-model-invocation: false +argument-hint: '[pr-number] [--comment]' +allowed-tools: Bash, Grep, Glob, Read +--- + +# PR Review Navigator + +Generate navigation aids to help humans review pull requests more efficiently. Provides orientation and structure, not pre-review or judgment. + +**Important constraints:** +- No interpretation of business intent or purpose, only factual descriptions of what changed + +## Arguments + +- `pr-number` (required): The PR number to review +- `--comment` (optional): Post the navigator output as a PR comment. If omitted, write to a local markdown file. + +## Process + +### 1. Fetch PR Information + +```bash +gh pr view $ARGUMENTS --json title,body,files,additions,deletions,url +``` + +Extract: changed files, additions/deletions count, PR URL for link construction. + +For commits/branches without a PR, use `git show --name-status` and `git diff`. + +### 2. Fetch the Diff + +```bash +gh pr diff +``` + +Understand file contents and relationships from the diff. + +### 3. Analyze Dependencies + +Read imports/references in the diff to determine which files depend on which. + +### 4. Determine Review Order + +Based on dependency flow, use outside-in ordering: + +1. API endpoints, HTTP routes, GraphQL resolvers +2. Service/business logic layer +3. Repository/persistence layer +4. Data models/entities +5. Wiring/configuration +6. Unit tests (after the implementation files they test) +7. Cornichon/integration tests last (they test the full stack from outside) + +### 5. Generate Mermaid Diagram + +Create a `flowchart TB` showing: +- All changed files as nodes with circled numbers: โ‘ , โ‘ก, โ‘ข, etc. +- Dependency relationships (arrows showing "depends on" or "uses") +- Test files connected to implementation files they test +- Subgraphs grouped by architectural layer +- Color coding: unit tests green (`fill:#e8f5e9`), integration tests blue (`fill:#e3f2fd`, dashed border) + +Node format: `["โ‘  filename.ext
one-liner"]` + +**Cornichon test styling:** +```mermaid +subgraph "๐Ÿงช Integration Tests (Cornichon)" + style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5 + ... +end +``` + +### 6. Create Review Table + +A numbered table with columns: +- `#` - Review order number +- `File` - Filename (short, without full path) +- `What it does` - One factual sentence about what the file contains/does +- `Link` - Anchor link to the file in the PR + +### 7. Construct File Links + +GitHub uses SHA256 hashes of file paths for PR file anchors: + +```bash +hash=$(echo -n "" | shasum -a 256 | cut -d' ' -f1) +# Link: https://github.com/{owner}/{repo}/pull/{number}/files#diff-{hash} +``` + +Use the file path exactly as returned by `gh pr view --json files`. Compute the hash for each file. + +For commits/branches without a PR, omit the Link column. + +### 8. Output the Result + +If `--comment` flag is provided, post as a PR comment: + +```bash +gh pr comment --body "" +``` + +If `--comment` is NOT provided, write to `pr-review-navigator.md` in the workspace root and inform the user of the file path. + +## Output Format + +The output (whether file or comment) should be valid markdown structured as: + +```markdown +## AI Review Navigator + +**Summary:** + +--- + +### File Relationships & Review Order + +\`\`\`mermaid +flowchart TB + subgraph "1๏ธโƒฃ API Layer" + A["โ‘  FeatureXController.scala
HTTP endpoints"] + end + + subgraph "2๏ธโƒฃ Service Layer" + B["โ‘ก FeatureXService.scala
Business logic"] + end + + subgraph "3๏ธโƒฃ Unit Tests" + C["โ‘ข FeatureXServiceSpec.scala"] + end + + subgraph IntegrationTests ["๐Ÿงช Integration Tests (Cornichon)"] + D["โ‘ฃ FeatureXFeature.scala"] + end + + A --> B + B -.->|tested by| C + A -.->|tested by| D + + style C fill:#e8f5e9 + style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5 +\`\`\` + +--- + +### Suggested Review Order + +| # | File | What it does | Link | +|---|------|--------------|------| +| 1 | `FeatureXController.scala` | HTTP endpoints for FeatureX | [View](link) | +| 2 | `FeatureXService.scala` | Business logic | [View](link) | +| 3 | `FeatureXServiceSpec.scala` | Unit tests for service layer | [View](link) | +| 4 | `FeatureXFeature.scala` | Cornichon integration tests | [View](link) | +``` + +**Summary rules:** +- State only facts about what changed +- Do NOT interpret purpose, intent, or business value +- Do NOT use phrases like "optimized for", "designed to", "intended for" + +## Guidelines + +- This skill assists with review orientation only. The human reviewer makes all judgments about code quality, correctness, and approval. +- If the PR is too large (>30 files), suggest reviewing in logical chunks. +- Wrap the mermaid diagram in triple backticks with `mermaid` language identifier so GitHub renders it as a diagram. diff --git a/.agents/skills/remember/SKILL.md b/.agents/skills/remember/SKILL.md new file mode 100644 index 000000000..1819cf6b8 --- /dev/null +++ b/.agents/skills/remember/SKILL.md @@ -0,0 +1,194 @@ +--- +name: remember +description: Persist guidelines, conventions, and architectural decisions into the repository's knowledge base. Use when told to remember something for future sessions. +disable-model-invocation: false +argument-hint: +allowed-tools: Bash, Grep, Glob, Read, Edit, Write +--- + +# Remember + +Persist new guidelines, best practices, or architectural decisions into the +repository's knowledge base so they are available in future AI sessions. + +## Arguments + +- `thing to remember` (required): A guideline, convention, or decision to + persist. Natural language input describing what should be remembered. + +## Usage Examples + +- `/remember always use the --frozen-lockfile flag in CI` +- `/remember the auth module was refactored to use middleware in PR #342` +- `/remember integration tests must hit a real database, never use mocks` + +## Process + +### 1. Intent Distillation + +- Identify the core principle, rule, or technical intent from the user's input +- Rephrase concisely using precise software development terminology + +### 2. Identify Target File + +Determine which file should contain this knowledge. Repositories follow a +layered structure, preferring tool-agnostic paths when they exist: + +| Intent type | Preferred target | Fallback | +|---|---|---| +| Project-wide convention or standard | `AGENTS.md` | `CLAUDE.md` | +| Domain-specific best practice (testing, components, API design, etc.) | `rules/` or `docs/conventions/` | See resolution rules | +| Change to an automated workflow or skill | `.agents/skills/` | `.claude/skills/` | +| Agent behavior guideline | `.agents/agents/` | `.claude/agents/` | +| Claude-specific configuration (MCP, hooks, permissions) | `CLAUDE.md` | โ€” | + +**Resolution rules:** + +1. Check whether `rules/` or `docs/conventions/` exists +2. If both exist, prefer `rules/` +3. If only one exists, write there +4. If only `docs/conventions/` exists, ask the user whether they want to + create a symlink from `rules/` to `docs/conventions/` so both paths + resolve to the same location. If they confirm, create the symlink before + writing. +5. If neither exists, create `rules/` and write there +6. For other target types: + - For `.agents/skills/` or `.agents/agents/`: Use the `.claude/` equivalent + if the `.agents/` directory does not exist + - For `AGENTS.md`: Use `CLAUDE.md` if `AGENTS.md` does not exist +7. Only write to `CLAUDE.md` or `.claude/` directly when the information is + Claude-specific or no tool-agnostic target exists + +### 3. Conflict Analysis + +- Thoroughly scan the identified file(s) for any existing content that + contradicts the new intent +- Additionally, scan the corresponding file in the other layer (e.g., if writing + to `AGENTS.md`, also scan `CLAUDE.md` and vice versa). If the other layer + contains conflicting or duplicated content, resolve it by replacing that + content in `CLAUDE.md` with a reference to `AGENTS.md` (e.g., + "See `AGENTS.md` for project conventions.") +- A contradiction is any statement that would be invalidated or made obsolete by + the new guideline + +**If a conflict is found:** + +- Halt execution immediately +- Quote the exact conflicting statement(s) from the document +- Inform the user about the contradiction and ask for clarification on how to + proceed +- Do NOT proceed with any updates until the conflict is resolved + +**If no conflicts are found:** + +- Identify the most logical section within the file to add the new information +- If no suitable section exists, create a new one with an appropriate heading +- Refactor existing content as needed to keep the document coherent and + well-structured + +### 4. Write the Update + +When writing the update: + +- Only include production-ready patterns and examples that can be safely copied. + Use precise, declarative language. Do not include anti-patterns or cautionary + examples. + +### 5. Skill Discovery and Synchronization + +After successfully updating documentation, discover which skills may need +updates by scanning skill files in `.agents/skills/*/SKILL.md` and +`.claude/skills/*/SKILL.md` (whichever exist). When reading skill files, resolve +symlinks to access the actual content rather than treating symlinks as empty or +opaque files. + +**Discovery criteria** โ€” a skill is affected if it contains: + +- Explicit references to the updated documentation file +- Content that covers the same topic or concept as the update +- Inline templates, code examples, or patterns related to the updated guideline +- Instructions or rules that may now be outdated or contradicted by the new + documentation + +**If no skills are affected, skip this step.** + +**For each affected skill, determine whether it is local or shared:** + +A skill is **shared** if it is a symlink pointing outside the current repo or +was installed by a package manager and has not been modified locally. A skill is +**local** if it was authored or edited in this repo. Symlinks between +`.claude/skills/` and `.agents/skills/` within the same repo are internal +bridges and do not affect this determination. + +**Local skills** โ€” edit directly: + +- Update the skill's templates, examples, and instructions to align with the + new documentation + +**Shared skills** โ€” report and offer to update: + +- Report the affected shared skill and the specific inconsistency to the user +- Ask: "Shared skill `` is affected. Add repo-specific additions?" +- If the user confirms: + + 1. Resolve the original shared skill path (the symlink target or CLI cache + location where the shared skill was installed) + + 2. Determine which layer to use: + + **If `.agents/skills/` directory exists:** + + Create or update `.agents/skills//SKILL.md` with repo-specific + additions listed **before** the shared skill reference, so local rules take + priority: + + ```markdown + --- + name: + description: + allowed-tools: + --- + + ## Repo-specific additions + + - + + ## Shared skill + + Read and follow the shared skill at ``. + ``` + + Then ensure `.claude/skills//SKILL.md` is a symlink to + `.agents/skills//SKILL.md`: + + - If it is already a symlink to the correct path, no action needed + - If it exists as a regular file, delete it and create the symlink + - If it does not exist, create the symlink + + **If `.agents/skills/` directory does not exist:** + + Create or update `.claude/skills//SKILL.md` directly with the + same structure (repo-specific additions before the shared skill reference). + +- If the user declines, log the inconsistency in the final confirmation but + take no action + +### 6. Final Confirmation + +Report all changes made: + +- Documentation file(s) updated +- Skill file(s) updated (if any), with rationale explaining why each skill was + identified as affected +- Summary of what was added or modified in each file + +## Guidelines + +- Always read target files before modifying them +- Prefer adding to an existing section over creating a new one +- Keep entries concise; one to two sentences per guideline is ideal +- If the user's input is ambiguous, ask for clarification before writing +- Do not duplicate information that already exists in the target file +- When creating skill files, create the `/` subdirectory if needed + but do NOT create `.agents/` or `.agents/skills/` directories โ€” only use them + if they already exist diff --git a/.agents/skills/renovate-migrate/SKILL.md b/.agents/skills/renovate-migrate/SKILL.md new file mode 100644 index 000000000..a7cf73f8a --- /dev/null +++ b/.agents/skills/renovate-migrate/SKILL.md @@ -0,0 +1,156 @@ +--- +name: renovate-migrate +description: Perform migrations for Renovate dependency upgrades based on breaking changes identified in a review. Use after running /renovate-review. +disable-model-invocation: false +argument-hint: '[pr-number] [--comment] [--push]' +allowed-tools: Bash, Grep, Glob, Read, Edit, Write, WebFetch +--- + +# Renovate Dependency Migration + +Perform code migrations for a Renovate PR based on breaking changes identified during review. + +## Arguments + +- `pr-number` (required): The PR number to migrate +- `--comment` (optional): Post the migration summary as a PR comment. If omitted, only output the summary locally. +- `--push` (optional): Push commits to the remote after completing migrations. If omitted, only commits locally. + +## Prerequisites + +This skill should be run after `/renovate-review` has identified breaking changes that require code modifications. + +## Process + +### 1. Load Review Context + +First, check if the review information is already available: + +**Option A: Check conversation context** +If `/renovate-review` was run earlier in the same conversation, the review details (breaking changes, affected files, required code changes) should already be in context. Use that information directly. + +**Option B: Load from GitHub PR comment** +If not in context, fetch the review comment from the PR: + +```bash +gh pr view --json comments --jq '.comments[] | select(.body | contains("## Dependency Upgrade Review")) | .body' +``` + +From the review comment, extract: + +- Package name and version change +- Upgrade type (patch/minor/major) +- Breaking changes that affect this codebase +- List of affected files and required code changes + +### 2. Gather Additional PR Context + +```bash +gh pr view --json title,body,files +``` + +Use this to supplement the review information if needed (e.g., to get the full list of files changed by Renovate). + +### 3. Perform Migrations + +Use the "Required Code Changes" section from the review to guide migrations. For each breaking change: + +1. **Reference the review**: The review already identified what API changed and how +2. **Find all occurrences**: Search for the old API usage (review may have already listed these) +3. **Apply the fix**: Update code to use the new API as specified in the review +4. **Commit immediately**: Make a small, focused commit + +#### Commit Guidelines + +- Make **one commit per logical change** (e.g., one commit per breaking change addressed) +- Keep commits small and focused +- Use this commit message format: + +``` +refactor: migrate to v - + + +``` + +Example commit messages: + +- `refactor: migrate p-retry to v7 - use named export` +- `refactor: migrate lodash to v5 - replace _.pluck with _.map` +- `refactor: migrate react-query to v5 - update useQuery options` + +#### Commit Command + +```bash +git add +git commit -m "refactor: migrate to v - " +``` + +### 4. Verify Changes + +After all migrations: + +1. Ensure the code compiles: `pnpm run build` or `pnpm run build:ts` +2. Format the code with Prettier and `pnpm run format` +3. Run relevant tests if available +4. If `--push` flag is provided, push to remote; otherwise keep changes local + +### 5. Generate Summary + +Create a summary of all changes made: + +```markdown +## Migration Summary: `` v โ†’ v + +**Commits:** +**Files modified:** +**Status:** Build passes / Tests pass / Ready for review + +
+Commits + +- `` +- ... + +
+ +
+Changes + +- `path/to/file1.ts` - +- ... + +
+ +Run `git log --oneline -n ` to review, then `git push` when ready. +``` + +### 6. Push Changes (if `--push` flag provided) + +Only push to remote if the `--push` flag was included in the arguments. + +If `--push` is provided: + +```bash +git push +``` + +If `--push` is NOT provided, skip this step and only keep changes local. + +### 7. Post Summary Comment (if `--comment` flag provided) + +Only post the summary to the PR if the `--comment` flag was included in the arguments. + +If `--comment` is provided: + +```bash +gh pr comment --body "" +``` + +If `--comment` is NOT provided, skip this step and only display the summary locally. + +## Important Notes + +- **Push behavior**: Only push to remote if `--push` flag is provided. Otherwise, only commit locally. +- **Small commits**: Each commit should address one specific change. +- **Verify as you go**: Run typecheck after each significant change if possible. +- **Preserve behavior**: Migrations should not change application behavior, only update API usage. diff --git a/.agents/skills/renovate-review/SKILL.md b/.agents/skills/renovate-review/SKILL.md new file mode 100644 index 000000000..6a821a2b8 --- /dev/null +++ b/.agents/skills/renovate-review/SKILL.md @@ -0,0 +1,143 @@ +--- +name: renovate-review +description: Review Renovate dependency upgrade PRs to assess safety and effort. Use when reviewing PRs from Renovate bot that update NPM dependencies. +disable-model-invocation: false +argument-hint: '[pr-number] [--comment]' +allowed-tools: Bash, Grep, Glob, Read, WebFetch +--- + +# Renovate Dependency Upgrade Review + +Review a Renovate PR to assess the safety and effort required to merge a dependency upgrade. + +## Arguments + +- `pr-number` (required): The PR number to review +- `--comment` (optional): Post the assessment as a PR comment. If omitted, only output the review locally. + +## Process + +### 1. Gather PR Information + +```bash +gh pr view $ARGUMENTS --json title,body,files +``` + +Extract the following information: + +- Package name being upgraded +- Previous version and new version +- Determine upgrade type: **patch**, **minor**, or **major** + +### 2. Analyze Upgrade Type + +#### Semantic Versioning + +We assume packages follow Semantic Versioning. Fix and minor should contain no breaking changes per semver + +In all cases you must: + +- Focus on verifying the upgrade doesn't introduce regressions +- Check if CI passes + +#### Major Upgrades + +1. Research breaking changes by: + - Fetching the GitHub releases page: `https://github.com///releases` + - Looking for a CHANGELOG.md in the repository + - Checking the package's migration guide if available + +2. Identify which breaking changes may affect this codebase + +### 3. Analyze Codebase Impact + +Search for usage of the upgraded package: + +1. Find imports/requires of the package +2. Identify which files and features depend on it +3. For major upgrades: check if any deprecated/removed APIs are used + +### 4. Generate Safety Assessment + +Create a markdown comment with the following structure: + +```markdown +## Dependency Upgrade Review: `` + + + +> [!CAUTION] +> Breaking changes affect this codebase. Code changes required before merge. + + + +> [!WARNING] +> Major upgrade with breaking changes. Review recommended. + +`` โ†’ `` (**patch** / **minor** / **major**) + +**Risk:** Low / Medium / High +**Impact:** files +**Recommendation:** Safe to merge / Review recommended / Changes required + + + +
+Affected files + +- `path/to/file.ts` +- ... + +
+ + +
+Breaking changes + +- +- + +
+ +
+Required code changes + +- +- + + + +
+``` + +### 5. Post the Comment (if `--comment` flag provided) + +Only post the comment to the PR if the `--comment` flag was included in the arguments. + +If `--comment` is provided: + +```bash +gh pr comment --body "" +``` + +If `--comment` is NOT provided, skip this step and only display the assessment locally. + +## Rating Guidelines + +**Risk:** + +- Low: Patch/minor upgrade, or major with no relevant breaking changes +- Medium: Major upgrade with breaking changes that don't affect current usage +- High: Major upgrade with breaking changes that affect current usage + +**Impact:** + +- Low: < 5 files, simple usage patterns +- Medium: 5-20 files, moderate complexity +- High: > 20 files, or critical infrastructure dependency + +**Recommendation:** + +- Safe to merge: CI passes, no breaking changes affect us +- Review recommended: Minor concerns, human review advised +- Changes required: Code modifications needed before merge diff --git a/.agents/skills/repo-healthcheck-node/SKILL.md b/.agents/skills/repo-healthcheck-node/SKILL.md new file mode 100644 index 000000000..eea335aa3 --- /dev/null +++ b/.agents/skills/repo-healthcheck-node/SKILL.md @@ -0,0 +1,183 @@ +--- +name: repo-healthcheck-node +description: Verify a Node.js/TypeScript repo's development environment is correctly set up. Checks Node.js version, pnpm version, dependency installation, and build success. Use when onboarding, troubleshooting CI failures, or verifying a fresh clone. +disable-model-invocation: false +argument-hint: "[--fix]" +allowed-tools: Bash, Grep, Glob, Read +--- + +# Repo Healthcheck โ€” Node.js + +Verify that a Node.js/TypeScript repository's development environment is +correctly set up. Reads `AGENTS.md` and `CLAUDE.md` (if present) for +repo-specific version requirements and build commands, then runs each check and +reports a clear pass/fail summary. + +## Arguments + +- `--fix` (optional): Attempt to auto-fix failures where possible (e.g. run + `pnpm install` if dependencies are missing). Without this flag, the skill + only reports โ€” it does not modify the environment. + +## Process + +### 1. Read Repo Configuration + +Read the following sources in priority order (later sources override earlier): + +1. `AGENTS.md` โ€” repo-specific commands and version requirements +2. `CLAUDE.md` (if present) โ€” may contain additional or overriding requirements +3. `.nvmrc` or `.node-version` (if present) โ€” authoritative Node.js version +4. `package.json` `engines` field โ€” authoritative pnpm/node version constraints + +Look for: + +- **Expected Node.js version** โ€” check `.nvmrc` / `.node-version` first, then + `package.json` `engines.node`, then patterns in `AGENTS.md`/`CLAUDE.md` like + `node 24`, `node: 24.13`, or explicit version statements. +- **Expected pnpm version** โ€” check `package.json` `engines.pnpm` first, then + patterns in `AGENTS.md`/`CLAUDE.md` like `pnpm 10`, `pnpm: 10.29.3`, or + explicit version statements. +- **Install command** โ€” default `pnpm install`. Override if the docs specify a + different command (e.g. `pnpm install --frozen-lockfile`). +- **Build command** โ€” default `pnpm build`. Override if the docs specify + something different (e.g. `pnpm build:packages`, `pnpm run compile`). + +If no version or command overrides are found, use the defaults and note that +expectations came from defaults, not from repo configuration. + +### 2. Run Checks + +Run each check in order. Capture the result (pass/fail), the actual value, and +the required value for the summary table. + +**Critical checks** are Node.js and pnpm version. If either critical check +fails, you MUST skip the dependent checks (install and build) and note the +reason in the output. + +#### Check 1 โ€” Node.js Version + +```bash +node --version +``` + +- If an expected version was found: compare using prefix matching (see + Guidelines). Pass if they match; fail with actual vs expected. +- If no expected version was found: report the installed version as + informational (no pass/fail judgment). +- Fix command (if `--fix` and failing): `nvm install` (reads from `.nvmrc` + automatically, if present). + +#### Check 2 โ€” pnpm Version + +```bash +pnpm --version +``` + +- If pnpm is not installed: MUST skip checks 3 and 4, report as missing. +- If an expected version was found: compare using prefix matching (see + Guidelines). Pass if they match; fail with actual vs expected. +- If no expected version was found: report the installed version as + informational (no pass/fail judgment). +- Fix command (if `--fix` and failing): `npm install -g pnpm@latest`. + +#### Check 3 โ€” Dependency Installation + +Only run if checks 1 and 2 did not produce critical failures. + +Use the install command from step 1 (default: `pnpm install`). + +```bash +pnpm install 2>&1 +``` + +- Pass if exit code is 0. +- Fail with the last 20 lines of output if exit code is non-zero. +- If `--fix` was passed and the default frozen-lockfile variant failed, retry + without `--frozen-lockfile` and report whether the retry succeeded. + +#### Check 4 โ€” Build + +Only run if check 3 passed. + +Run the build command from step 1 (default: `pnpm build`). + +- Pass if exit code is 0. +- Fail with the last 30 lines of output if exit code is non-zero. + +### 3. Report Results + +Output a summary table showing actual version vs required version for each +check: + +```markdown +## ๐Ÿฅ Repo Healthcheck โ€” Node.js + +| Check | Status | +| ----------------- | -------------------------- | +| Node.js >= 24.0.0 | โœ… v24.13.0 | +| pnpm >= 10.0.0 | โœ… v10.29.3 | +| pnpm install | โœ… | +| Build | โŒ Exit code 1 (see below) | +``` + +Status format: + +- Pass with version: `โœ… vX.X.X` +- Pass without version: `โœ…` +- Fail with version mismatch: `โŒ vX.X.X (requires >= Y.Y)` +- Fail with error: `โŒ ` +- Skipped: `โญ Skipped (Node.js check failed)` +- Informational (no expected version): `โ„น vX.X.X` + +Follow the table with the full output for any failed checks so the user can +diagnose the issue. + +#### Issues Found + +If any checks failed, add an Issues Found section with copy-pasteable fix +commands: + +```markdown +### โŒ Issues Found + +- **Node.js**: Run `nvm install` to install the required version +- **Build**: Run `pnpm build` and review the output above +``` + +#### Success + +If ALL checks pass, add a success message with next steps: + +```markdown +### โœ… All Systems Go! + +Environment is ready. Start the dev server with: + +\`\`\`bash +pnpm start +\`\`\` +``` + +## Guidelines + +- You MUST read `AGENTS.md` and `CLAUDE.md` before running any checks โ€” repo + configuration takes precedence over defaults. +- You MUST always show the full results table even if some checks fail. +- You MUST skip install and build checks if a critical check (Node.js or pnpm) + fails, since those checks depend on correct tooling. +- You SHOULD provide clear, copy-pasteable fix commands for any failures. +- Version comparison is prefix-based: if the expected version is `24`, match + any `24.x.y`; if the expected version is `24.13`, match any `24.13.y`. +- Do not fail a version check when no expected version is found โ€” report + informational only. +- Only use `--fix` behaviour when the flag is explicitly passed. +- Keep output concise: show only the last N lines of command output on failure, + not the full log. + +## RFC 2119 Key Words + +- **MUST** / **REQUIRED** โ€” Absolute requirement +- **MUST NOT** โ€” Absolute prohibition +- **SHOULD** / **RECOMMENDED** โ€” Should do unless there is a valid reason not to +- **MAY** / **OPTIONAL** โ€” Truly optional diff --git a/.agents/skills/repo-maintenance-node/SKILL.md b/.agents/skills/repo-maintenance-node/SKILL.md new file mode 100644 index 000000000..fd9ff3e94 --- /dev/null +++ b/.agents/skills/repo-maintenance-node/SKILL.md @@ -0,0 +1,373 @@ +--- +name: repo-maintenance-node +description: Perform a broad Node/TypeScript repository health sweep โ€” formatting, linting, type errors, dead code, dependency hygiene, and open Renovate PRs. +disable-model-invocation: false +argument-hint: '[--dry-run] [--section formatting|dead-code|deps|renovate]' +allowed-tools: Bash, Grep, Glob, Read, Agent +--- + +# Node/TypeScript Repository Maintenance + +Perform a comprehensive health sweep for Node.js and TypeScript repositories. +Checks formatting, linting, type errors, dead code, dependency hygiene, +cross-package consistency, and open Renovate PRs. Reads `AGENTS.md` (or +`CLAUDE.md`) for repo-specific commands before running any checks. + +## Arguments + +- `--dry-run` (optional): Report issues without making changes. +- `--section ` (optional): Run only a specific section. Valid values: + `formatting`, `dead-code`, `deps`, `renovate`. If omitted, run all sections. + +**Target:** $ARGUMENTS (defaults to all sections, applying fixes) + +--- + +## Execution Strategy + +This skill is designed for **parallel execution** to minimize wall clock time. +After Step 0 (configuration discovery), launch Agents A and B in parallel for +the investigative workstreams. Once both complete, run Agent C (Code Quality) +last so formatting/linting/type-check fixes apply on top of any changes from +earlier steps. Only the dependency section has an additional internal ordering +constraint (Renovate PRs must complete before filtering outdated deps). + +```mermaid +flowchart TD + S0["Step 0: Read config"] --> A["Agent A: Dead Code Detection"] + S0 --> B["Agent B: Dependencies & Renovate"] + + B --> B1["B1: Renovate PRs (gh API)"] + B --> B2["B2: Cross-package validation"] + B --> B3["B3: Dedupe check"] + B --> B5["B5: Peer dependency warnings"] + B1 --> B4["B4: Outdated deps (filtered by B1)"] + + A --> C["Agent C: Code Quality (format + lint + typecheck)"] + B2 --> C + B3 --> C + B4 --> C + B5 --> C + + C --> F["Step Final: Merge results โ†’ Generate report"] +``` + +When launching parallel agents, pass them the discovered configuration from +Step 0 (package manager, available scripts, monorepo status) so they don't +need to re-read config files. + +--- + +## Process + +### 0. Read Repo-Specific Configuration + +Before running any checks, read the repository's configuration files to discover +project-specific commands and conventions: + +1. Read `AGENTS.md` (if it exists) for: + - Lint / format / typecheck commands + - Build commands + - Test commands + - Any repo-specific maintenance notes +2. Fall back to `CLAUDE.md` if `AGENTS.md` does not exist. +3. Read `package.json` (or the workspace root manifest) to identify: + - Available scripts (`lint`, `format`, `typecheck`, etc.) + - Package manager (`pnpm`, `npm`, `yarn`) + - Whether this is a monorepo (look for `workspaces` field or + `pnpm-workspace.yaml`) + +Store discovered commands for use in subsequent steps. If a command is not +found, skip the corresponding check and note it in the report. + +### Agent A: Dead Code Detection + +**Goal:** Identify unused exports, imports, and files. + +Launch this as a parallel Agent subagent. + +> **Note:** This section is complementary to deterministic tools like +> [knip](https://knip.dev). If `knip` is configured in the repo, prefer running +> it. Otherwise, use heuristic detection. + +1. **Check for knip:** + + ```bash + # Look for knip in package.json scripts or devDependencies + grep -q '"knip"' package.json && echo "knip available" + ``` + + If knip is available: + + ```bash + pnpm knip # or: npx knip + ``` + + If knip is not available, perform heuristic checks: + +2. **Heuristic dead code scan** (when knip is unavailable): + + - Search for exported symbols that have no import references elsewhere: + ```bash + grep -rn "export \(const\|function\|class\|type\|interface\|enum\)" src/ + ``` + - For each export, check if it's imported anywhere else in the codebase. + - Flag files with zero inbound imports (potential dead files). + +3. **Report findings** as a list of potentially unused items. Do NOT + auto-delete โ€” dead code removal requires human review. + +### Agent B: Dependencies & Renovate + +**Goal:** Surface Renovate PRs, check dependency health, and report outdated +packages not already covered by Renovate. + +Launch this as a parallel Agent subagent. Within this agent, run B1, B2, B3, +and B5 in parallel, then run B4 after B1 completes (B4 needs the Renovate +package list to filter outdated deps). + +#### B1. Open Renovate PRs + +1. List open PRs from Renovate: + + ```bash + gh pr list --author "renovate[bot]" --state open --json number,title,url \ + --jq '.[] | "- #\(.number) \(.title) \(.url)"' + ``` + + If the above returns no results, also try: + + ```bash + gh pr list --author "renovate" --state open --json number,title,url \ + --jq '.[] | "- #\(.number) \(.title) \(.url)"' + ``` + +2. For each open Renovate PR, suggest running `/renovate-review`: + + ``` + Run `/renovate-review ` to assess safety and effort. + ``` + +3. **Collect the package names** covered by open Renovate PRs (parse the PR + titles โ€” Renovate titles typically follow `Update to ` + or `Update dependency to `). Store this set for use in + B4. + +4. If no open Renovate PRs are found, report that the repo is up to date with + Renovate. + +#### B2. Cross-Package Dependency Validation (Monorepos) + +If this is a monorepo: + +1. Check for version inconsistencies across packages: + + ```bash + # For pnpm workspaces with catalogs + cat pnpm-workspace.yaml + + # For npm/yarn workspaces, compare package.json files + find . -name "package.json" -not -path "*/node_modules/*" \ + -exec grep -l '"dependencies"' {} \; + ``` + +2. Flag any package that pins a different version of the same dependency than + other packages in the workspace (unless the workspace uses a catalog or + resolutions to centralize versions). + +#### B3. Duplicate Dependencies in Lockfile + +1. Check for duplicates: + + ```bash + # pnpm + pnpm dedupe --check # or: pnpm dedupe (to fix) + + # npm + npm dedupe --dry-run + + # yarn + yarn dedupe --check + ``` + +2. If `--dry-run` is not set and duplicates are found, run the dedup command + and commit the result: + + ```bash + pnpm dedupe + git add pnpm-lock.yaml + git commit -m "chore(deps): deduplicate lockfile" + ``` + +#### B4. Outdated Dependencies (Not Covered by Renovate) + +**Depends on B1** โ€” wait for Renovate PR list before running. + +1. Run the package manager's outdated check: + + ```bash + pnpm outdated # or: npm outdated / yarn outdated + ``` + +2. **Filter out** any packages that already have an open Renovate PR (from the + set collected in B1). Only report dependencies that are outdated AND not + already being handled by Renovate. + +3. Categorize the remaining results: + - **Patch updates** โ€” safe to update + - **Minor updates** โ€” likely safe, review changelogs + - **Major updates** โ€” requires migration planning + +4. Report a summary table of outdated dependencies by category. + +#### B5. Peer Dependency Warnings + +1. Check for peer dependency mismatches: + + ```bash + pnpm install --dry-run 2>&1 | grep -i "peer" + # or: pnpm ls --depth 0 2>&1 | grep -i "WARN" + ``` + + Alternatively, parse warnings from the most recent `pnpm install` output or + lockfile metadata. + +2. **Report** mismatches grouped by severity: + - **Version range conflicts** โ€” installed version outside the expected peer + range (e.g., plugin expects `cypress@4-13` but `15.x` is installed) + - **Stale peer pins** โ€” addon expects a newer version of its host package + than what's installed (e.g., storybook addon expects `^10.2.14` but + `10.2.10` is installed) + +3. These are advisory โ€” do not auto-fix peer dependency issues. + +### Agent C: Code Quality โ€” Formatting, Linting, and Type Checking + +**Goal:** Ensure code style is consistent and free of lint/type errors. + +Launch this Agent subagent **after Agents A and B complete** so that fixes +apply on top of any code changes from earlier steps. Within this agent, run +formatting, linting, and type checking as **parallel Bash commands** (they +don't depend on each other). + +#### C1. Formatting + +1. **Run the formatter** using the repo's configured command: + + ```bash + # Use the command from AGENTS.md / package.json, e.g.: + pnpm format # or: pnpm prettier --write . + ``` + + If `--dry-run` is set, run the check variant instead: + + ```bash + pnpm format --check # or: pnpm prettier --check . + ``` + +2. **Separate real issues from expected noise.** Formatter errors in CI config + files (e.g., `.circleci-orbs/`, `codegen.*.yml`) that use template variable + syntax (`${...}`) are often false positives โ€” note them separately from + actual source code formatting issues. + +3. **Report** the number of files changed (or issues found in dry-run mode). + +#### C2. Linting + +1. **Run the linter** with auto-fix: + + ```bash + pnpm lint --fix # or: pnpm eslint --fix . + ``` + + If `--dry-run` is set, run without `--fix`: + + ```bash + pnpm lint # report only + ``` + +2. **Report** the number of issues fixed and any remaining issues that require + manual intervention. + +#### C3. Type Checking + +1. **Run the TypeScript compiler** in check mode: + + ```bash + pnpm typecheck # or: pnpm tsc --noEmit + ``` + +2. If errors are found: + - **Attempt to fix** straightforward issues (missing imports, unused + variables, simple type mismatches). + - **Flag for human review** any complex type errors that cannot be + confidently auto-fixed. + +3. **Report** the number of type errors found, fixed, and remaining. + +#### C4. Commit + +If any changes were made (and `--dry-run` is not set), stage and commit: + +```bash +git add -A +git commit -m "chore: fix formatting, lint, and type errors" +``` + +### Final: Generate Report + +After all agents complete, merge their results into a summary report: + +```markdown +## Repository Maintenance Report + +### Code Quality +- Formatting: X files fixed (or: "No issues found") +- Lint: X issues fixed, Y remaining +- TypeScript: X errors fixed, Y remaining (flagged for review) + +### Dead Code +- Potentially unused exports: X +- Potentially dead files: X +- (See details above) + +### Renovate PRs +- Open PRs: X + - #123 Update foo to v2.0.0 + - #124 Update bar to v1.5.0 +- Suggested action: Run `/renovate-review` on each + +### Dependencies (not covered by Renovate) +- Outdated (patch): X +- Outdated (minor): X +- Outdated (major): X +- Peer dependency mismatches: X +- Duplicates in lockfile: X (resolved / not resolved) +- Cross-package inconsistencies: X + +### Actions Taken +- [ ] Code quality fixes committed +- [ ] Lockfile deduplication committed +- [ ] (other actions) +``` + +--- + +## Guidelines + +- **Always read AGENTS.md first.** Repo-specific commands take priority over + generic fallbacks. +- **Maximize parallelism.** Launch Agents A and B simultaneously, then run + Agent C after both complete. Within each agent, run independent commands in + parallel where possible. +- **Never auto-delete code.** Dead code detection is advisory โ€” flag items for + human review. +- **Commit incrementally.** One commit per section keeps changes easy to review + and revert. +- **Respect `--dry-run`.** When set, make zero changes โ€” only report. +- **Handle missing tools gracefully.** If a tool (knip, prettier, eslint) is not + installed, skip that check and note it in the report rather than failing. +- **Monorepo awareness.** Detect whether the repo is a monorepo and adapt + dependency checks accordingly. +- **Renovate-first for outdated deps.** Always check Renovate PRs before + reporting outdated dependencies to avoid duplicate work. diff --git a/.agents/skills/security-auditor/SKILL.md b/.agents/skills/security-auditor/SKILL.md new file mode 100644 index 000000000..80e55f2b1 --- /dev/null +++ b/.agents/skills/security-auditor/SKILL.md @@ -0,0 +1,511 @@ +--- +name: security-auditor +description: Perform comprehensive security audit of a repository with detailed findings and step-by-step PoCs. Reports all web and API security vulnerabilities. +disable-model-invocation: false +argument-hint: '[--path ] [--focus ]' +allowed-tools: Task, Bash, Grep, Glob, Read, Write +--- + +# Security Audit + +Perform a comprehensive security audit of a repository, identifying web and API security vulnerabilities with practical exploitation steps and detailed proof-of-concept demonstrations. + +## Arguments + +- `--path ` (optional): Path to the repository to audit. Defaults to current directory. +- `--focus ` (optional): Focus on specific security category (e.g., `injection`, `auth`, `api`, `crypto`, `logic`). Defaults to all categories. + +## Process + +### 1. Initialize Audit + +Determine the audit scope and target directory: + +```bash +# If --path is provided, use it; otherwise use current directory +TARGET_PATH=$(echo "$ARGUMENTS" | grep -oP '(?<=--path\s)\S+' || pwd) +FOCUS_AREA=$(echo "$ARGUMENTS" | grep -oP '(?<=--focus\s)\S+' || echo "all") +``` + +Create audit report filename with timestamp: + +```bash +TIMESTAMP=$(date +%Y%m%d_%H%M%S) +REPORT_FILE="${TARGET_PATH}/security-audit-report-${TIMESTAMP}.md" +``` + +### 2. Technology Stack Detection + +Identify the technology stack to tailor the security audit: + +Use Glob and Read tools to detect: +- **Backend frameworks**: Express, FastAPI, Spring Boot, Django, Rails, Next.js, etc. +- **Frontend frameworks**: React, Vue, Angular +- **Database technologies**: MongoDB, PostgreSQL, MySQL, Redis +- **Authentication systems**: JWT, OAuth, NextAuth, Passport.js, custom auth +- **Cloud/Infrastructure**: AWS SDK, Docker, Kubernetes configs +- **Package managers**: package.json, requirements.txt, go.mod, Gemfile + +Document the detected stack in the report. + +### 3. Deep Security Analysis + +Launch specialized security agents for comprehensive vulnerability discovery: + +#### A. Application Security Review (security-auditor agent) + +Use the Task tool with `subagent_type: security-auditor` and `model: opus` to perform: + +1. **Injection Vulnerabilities** + - SQL Injection (SQLi) + - NoSQL Injection + - Command Injection + - Code Injection + - LDAP Injection + - XPath Injection + - Template Injection (SSTI) + +2. **Authentication & Authorization Flaws** + - Broken authentication mechanisms + - Weak password policies + - JWT vulnerabilities (weak secrets, algorithm confusion, missing expiration) + - OAuth/OIDC misconfigurations + - Session fixation and hijacking + - Missing or improper authorization checks + - Privilege escalation paths + - IDOR (Insecure Direct Object References) + +3. **Cross-Site Vulnerabilities** + - Cross-Site Scripting (XSS) - stored, reflected, DOM-based + - Cross-Site Request Forgery (CSRF) + - Cross-Origin Resource Sharing (CORS) misconfigurations + - Clickjacking vulnerabilities + +4. **Data Exposure** + - Sensitive data in logs + - Exposed credentials in code or config files + - API keys and secrets in repositories + - Information disclosure through error messages + - Missing encryption for sensitive data + - Insecure data transmission + +5. **Security Misconfigurations** + - Default credentials + - Unnecessary features enabled + - Verbose error messages + - Missing security headers + - Insecure file permissions + - Misconfigured cloud storage + - Debug mode in production + +6. **Business Logic Vulnerabilities** + - Race conditions + - Payment/pricing manipulation + - Workflow bypasses + - Mass assignment vulnerabilities + - Insufficient anti-automation + - Trust boundary violations + +#### B. Deep Vulnerability Research (deep-vuln-researcher agent) + +Use the Task tool with `subagent_type: deep-vuln-researcher` and `model: opus` to discover: + +1. **Complex Logic Vulnerabilities** + - State machine vulnerabilities + - Time-of-check to time-of-use (TOCTOU) + - Async race conditions + - GraphQL security issues (query depth, batching attacks) + - API rate limiting bypasses + +2. **Advanced Injection Techniques** + - Prototype pollution (Node.js) + - Server-Side Request Forgery (SSRF) + - XXE (XML External Entity) attacks + - Deserialization vulnerabilities + - Path traversal and LFI/RFI + +3. **Cryptographic Weaknesses** + - Weak encryption algorithms + - Improper key management + - Insufficient randomness + - Hash collision vulnerabilities + - Timing attacks + +4. **API Security Issues** + - Broken object level authorization (BOLA) + - Broken function level authorization (BFLA) + - Mass assignment + - Excessive data exposure + - Lack of resources & rate limiting + - Security misconfiguration in APIs + - Improper asset management + +5. **Container & Infrastructure** + - Docker misconfigurations + - Kubernetes security issues + - AWS/Cloud misconfigurations + - Environment variable leakage + - Secrets in container images + +### 4. Generate Proof-of-Concepts + +For each vulnerability discovered, create a detailed PoC including: + +1. **Vulnerability Description**: Clear explanation of the security flaw +2. **Location**: Exact file paths and line numbers +3. **Severity**: Critical / High / Medium / Low (based on CVSS or custom criteria) +4. **Impact**: Real-world consequences of exploitation +5. **Reproduction Steps**: Detailed step-by-step instructions +6. **Code Snippet**: The vulnerable code section +7. **Exploit PoC**: Working proof-of-concept with example payloads +8. **Remediation**: Specific fix recommendations with secure code examples + +### 5. Generate Security Report + +Create a comprehensive markdown report with the following structure: + +```markdown +# Security Audit Report + +**Repository:** [repository name] +**Audit Date:** [date] +**Auditor:** Claude Security Auditor +**Scope:** [all/focused category] + +--- + +## Executive Summary + +[Brief overview of audit findings, total vulnerabilities by severity] + +### Key Statistics + +- **Critical:** X findings +- **High:** X findings +- **Medium:** X findings +- **Low:** X findings +- **Informational:** X findings + +### Most Critical Issues + +1. [Issue 1 with severity] +2. [Issue 2 with severity] +3. [Issue 3 with severity] + +--- + +## Technology Stack + +[Detected frameworks, libraries, and infrastructure] + +--- + +## Detailed Findings + +### [SEVERITY-001] [Vulnerability Title] + +**Severity:** Critical/High/Medium/Low +**Category:** [e.g., Injection, Authentication, etc.] +**CWE:** [CWE number if applicable] +**CVSS Score:** [if applicable] + +#### Description + +[Detailed explanation of the vulnerability] + +#### Location + +- **File:** `path/to/file.js` +- **Line:** 42-55 +- **Function/Method:** `vulnerableFunction()` + +#### Impact + +[Real-world impact - what can an attacker achieve?] + +- Data breach potential +- Unauthorized access +- System compromise +- etc. + +#### Vulnerable Code + +```javascript +// Vulnerable code snippet +const query = `SELECT * FROM users WHERE id = ${req.params.id}`; +db.query(query); +``` + +#### Proof of Concept + +**Step 1:** [Setup/Prerequisites] +```bash +# Commands or setup needed +``` + +**Step 2:** [Exploitation] +```bash +# Exploit payload +curl -X POST http://localhost:3000/api/user \ + -H "Content-Type: application/json" \ + -d '{"id": "1 OR 1=1; DROP TABLE users;--"}' +``` + +**Step 3:** [Verification] +```bash +# How to verify the exploit worked +``` + +**Expected Result:** +``` +[What happens when exploited] +``` + +#### Remediation + +**Recommended Fix:** + +```javascript +// Secure code example +const query = 'SELECT * FROM users WHERE id = ?'; +db.query(query, [req.params.id]); +``` + +**Additional Recommendations:** +- Use parameterized queries +- Implement input validation +- Add proper error handling +- etc. + +--- + +[Repeat for each finding] + +--- + +## Security Best Practices Recommendations + +### Immediate Actions Required + +1. [Critical fixes needed immediately] + +### Short-term Improvements + +1. [Important improvements to implement soon] + +### Long-term Security Strategy + +1. [Architectural improvements and security practices] + +--- + +## Compliance & Standards + +[If applicable, map findings to compliance frameworks:] +- OWASP Top 10 coverage +- OWASP API Security Top 10 +- PCI DSS considerations +- GDPR implications + +--- + +## Appendix + +### Testing Methodology + +[Description of the audit process and tools used] + +### References + +- [Relevant CVEs, security advisories] +- [OWASP references] +- [Framework-specific security guides] + +### Glossary + +[Definition of security terms used in the report] +``` + +Save this report to the file determined in step 1. + +### 6. Output Summary + +After completing the audit, provide a summary: + +```markdown +โœ… Security audit completed successfully + +๐Ÿ“„ **Report:** `[path to report file]` + +๐Ÿ“Š **Summary:** +- Critical: X +- High: X +- Medium: X +- Low: X + +๐Ÿ”ด **Action Required:** [List 3 most critical issues] + +The detailed report includes: +- Comprehensive vulnerability analysis +- Step-by-step exploitation PoCs +- Specific remediation guidance +- Security best practices recommendations +``` + +## Guidelines + +### Model Selection + +**IMPORTANT:** Always use `model: opus` when invoking security agents via the Task tool. Opus 4.6 provides the highest quality analysis and is essential for: +- Detecting subtle logic vulnerabilities +- Generating accurate and exploitable PoCs +- Minimizing false positives +- Ensuring comprehensive coverage + +Example Task invocation: +``` +Task tool with: +- subagent_type: security-auditor +- model: opus +- prompt: [detailed security audit instructions] +``` + +### Severity Classification + +**Critical:** +- Remote code execution +- Authentication bypass +- SQL injection leading to data breach +- Exposed secrets/credentials with high privileges +- Critical business logic flaws + +**High:** +- Privilege escalation +- IDOR allowing access to sensitive data +- XSS in high-value contexts +- Authorization bypass +- Cryptographic failures with data exposure + +**Medium:** +- CSRF on state-changing operations +- Information disclosure of sensitive data +- Security misconfigurations with moderate impact +- Business logic issues with limited impact +- Missing security headers + +**Low:** +- Information disclosure (non-sensitive) +- Security headers on static content +- Minor configuration issues +- Best practice violations + +**Informational:** +- Code quality improvements +- Defense-in-depth suggestions +- Security awareness recommendations + +### Focus Areas by Technology + +**Node.js/Express:** +- Prototype pollution +- ReDoS (Regular Expression Denial of Service) +- Package vulnerabilities (npm audit) +- Express middleware security + +**Python/Django/FastAPI:** +- SSTI (Server-Side Template Injection) +- Pickle deserialization +- Django ORM injection +- Package vulnerabilities (pip) + +**Java/Spring Boot:** +- Deserialization vulnerabilities +- Spring Expression Language injection +- XXE in XML parsers +- Log4j-style vulnerabilities + +**MongoDB/NoSQL:** +- NoSQL injection +- Missing access controls +- Unprotected admin interfaces + +**JWT/Authentication:** +- Algorithm confusion (alg: none) +- Weak signing keys +- Missing expiration validation +- Token leakage + +**APIs:** +- BOLA/IDOR in API endpoints +- Mass assignment +- Excessive data exposure +- Missing rate limiting + +### Testing Scope + +**Include:** +- All source code files +- Configuration files +- Infrastructure as Code (IaC) +- Environment variable templates +- Docker/Kubernetes configs +- CI/CD pipeline configurations +- Database schemas and migrations + +**Exclude:** +- Third-party libraries (note if vulnerable versions detected) +- Minified/compiled code +- Test fixtures (unless they expose patterns used in production) + +### Report Quality Standards + +1. **No False Positives**: Every finding must be verified and exploitable +2. **Practical PoCs**: All exploits must include working reproduction steps +3. **Actionable Remediation**: Provide specific code fixes, not just generic advice +4. **Context Awareness**: Consider the actual deployment context and risk +5. **Clear Communication**: Write for both technical and non-technical audiences + +### Ethics and Responsible Disclosure + +- This tool is for authorized security testing only +- Only scan repositories you own or have permission to test +- Do not execute exploits against production systems without authorization +- Handle discovered vulnerabilities responsibly +- Follow responsible disclosure practices for third-party issues + +## Examples + +### Example 1: Full audit of current directory + +``` +/security-auditor +``` + +### Example 2: Audit specific directory + +``` +/security-auditor --path /path/to/repo +``` + +### Example 3: Focus on injection vulnerabilities + +``` +/security-auditor --focus injection +``` + +### Example 4: Focus on authentication issues + +``` +/security-auditor --path ./backend --focus auth +``` + +## Notes + +- The audit may take several minutes depending on repository size +- Progress updates will be shown during the scan +- The report file will be created in the target directory +- Review the report thoroughly and prioritize fixes by severity +- Consider running the audit regularly (e.g., before major releases) +- Integrate findings into your security development lifecycle + + diff --git a/.claude/.gitignore b/.claude/.gitignore new file mode 100644 index 000000000..763ec210e --- /dev/null +++ b/.claude/.gitignore @@ -0,0 +1,5 @@ +# Local settings +*.local.* + +# Plan artifacts from jira-implement-task skill +skills/jira-implement-task/ diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 000000000..31b5f45b2 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "enableAllProjectMcpServers": true, + "hooks": { + "PostToolUse": [ + { + "matcher": "Edit|MultiEdit|Write", + "hooks": [ + { + "type": "command", + "command": "file_path=$(jq -r '.tool_input.file_path'); if echo \"$file_path\" | grep -qE '\\.(ts|tsx|js|jsx|md|mdx|json)$'; then npx prettier --write \"$file_path\"; fi" + } + ] + } + ] + } +} diff --git a/.claude/skills/pr-review-navigator b/.claude/skills/pr-review-navigator new file mode 120000 index 000000000..a5a2145d5 --- /dev/null +++ b/.claude/skills/pr-review-navigator @@ -0,0 +1 @@ +../../.agents/skills/pr-review-navigator \ No newline at end of file diff --git a/.claude/skills/remember b/.claude/skills/remember new file mode 120000 index 000000000..a9ec54ebb --- /dev/null +++ b/.claude/skills/remember @@ -0,0 +1 @@ +../../.agents/skills/remember \ No newline at end of file diff --git a/.claude/skills/renovate-migrate b/.claude/skills/renovate-migrate new file mode 120000 index 000000000..98825a508 --- /dev/null +++ b/.claude/skills/renovate-migrate @@ -0,0 +1 @@ +../../.agents/skills/renovate-migrate \ No newline at end of file diff --git a/.claude/skills/renovate-review b/.claude/skills/renovate-review new file mode 120000 index 000000000..d7b646202 --- /dev/null +++ b/.claude/skills/renovate-review @@ -0,0 +1 @@ +../../.agents/skills/renovate-review \ No newline at end of file diff --git a/.claude/skills/repo-healthcheck-node b/.claude/skills/repo-healthcheck-node new file mode 120000 index 000000000..8d2c4c8a9 --- /dev/null +++ b/.claude/skills/repo-healthcheck-node @@ -0,0 +1 @@ +../../.agents/skills/repo-healthcheck-node \ No newline at end of file diff --git a/.claude/skills/repo-maintenance-node b/.claude/skills/repo-maintenance-node new file mode 120000 index 000000000..2fad63cb3 --- /dev/null +++ b/.claude/skills/repo-maintenance-node @@ -0,0 +1 @@ +../../.agents/skills/repo-maintenance-node \ No newline at end of file diff --git a/.claude/skills/security-auditor b/.claude/skills/security-auditor new file mode 120000 index 000000000..6867b229b --- /dev/null +++ b/.claude/skills/security-auditor @@ -0,0 +1 @@ +../../.agents/skills/security-auditor \ No newline at end of file diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 000000000..6530e8df8 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,20 @@ +{ + "mcpServers": { + "commercetools-docs": { + "type": "http", + "url": "https://docs.commercetools.com/apis/mcp" + }, + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp@latest"] + }, + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + }, + "sequential-thinking": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + } + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d172e4fa9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,120 @@ +# commercetools Test Data + +## What This Repo Does + +Monorepo of test data builders for commercetools platform entities. Teams across +the organization use these builders to generate realistic mock data for both REST +and GraphQL API responses in their test suites. + +## Architecture + +Two workspace packages (`pnpm-workspace.yaml`): + +- **`standalone/`** โ€” the published package + (`@commercetools/composable-commerce-test-data`). Contains all domain models + under `src/models/`, organized by domain area (product, cart, category, etc.). + Each model folder contains `types.ts`, `fields-config.ts`, `builders.ts`, + `builders.spec.ts`, `index.ts`, and an optional `presets/` directory. The + `src/core/` module provides `createSpecializedBuilder` and helpers that all + domain models depend on. +- **`generators/`** โ€” internal CLI tool (`pnpm generate-model`) for scaffolding + new test data models. + +Every model has two representations โ€” REST and GraphQL โ€” each with a random +builder and optional presets. REST types come from `@commercetools/platform-sdk`. +GraphQL types are generated via `graphql-codegen` from introspection schemas +stored in `schemas/` (core, ctp, mc, settings). A `types-post-processor.mjs` +runs after codegen to un-export colliding helper types and replace `any` with +`unknown`. + +`preconstruct` builds the standalone package โ€” each domain model is a separate +entrypoint (see `standalone/package.json` `preconstruct.entrypoints`). + +## How To Make Changes + +### Verify your work + +| Task | Command | Notes | +| ----------------- | --------------------------------------- | --------------------------------- | +| Run tests | `pnpm test` | Jest, matches `**/*.spec.{js,ts}` | +| Run a single test | `pnpm test -- --testPathPattern=` | Path fragment is enough | +| Typecheck | `pnpm typecheck` | `tsc --noEmit` from root | +| Lint | `pnpm lint` | Jest runner with ESLint | + +### Common workflows + +**Create a new model:** + +1. Run `pnpm generate-model` โ€” the CLI scaffolds `types.ts`, `fields-config.ts`, + `builders.ts`, `builders.spec.ts`, and `index.ts` with TODOs. +2. Define REST and GraphQL types in `types.ts` (REST from `@commercetools/platform-sdk`, + GraphQL from `@commercetools-test-data/graphql-types`). +3. Implement `restFieldsConfig` and `graphqlFieldsConfig` in `fields-config.ts`. + Only assign values to **required** properties โ€” use presets for fully-populated + versions. +4. Wire up builders in `builders.ts` using `createSpecializedBuilder`. +5. Re-export from the domain's `index.ts` and add the entrypoint to + `standalone/package.json` `preconstruct.entrypoints`. +6. Write builder specs validating default REST and GraphQL output shapes. +7. Run `pnpm test`, `pnpm typecheck`, and `pnpm lint`. + +**Update GraphQL types after schema changes:** + +1. Copy `.env.template` to `.env` and fill in credentials (if not already done). +2. Run `pnpm generate-types` โ€” this regenerates types in + `standalone/src/graphql-types/generated/`. Do not edit generated files manually. + +**Add a changeset before opening a PR:** + +1. Run `pnpm changeset` and follow the prompts to select affected packages and + semver bump type. + +## Boundaries + +- **Published:** `@commercetools/composable-commerce-test-data` (standalone) โ€” public + npm, semver obligations apply. Changesets are required for publishable changes. +- **Internal-only:** `@commercetools-test-data/generators` โ€” private, never published. +- REST types come from `@commercetools/platform-sdk` โ€” do not manually define them. +- GraphQL types are generated by `graphql-codegen` โ€” run `generate-types` to update, + do not edit files in `standalone/src/graphql-types/generated/` manually. +- Preset ownership: presets under team-specific folders (e.g. `change-history-data`, + `sample-data-fashion`, `sample-data-b2c-lifestyle`) are owned by their respective + teams and must not be altered without that team's review. + +## Gotchas + +- `preconstruct dev` runs during `postinstall` and creates symlinks in + `standalone/` for local dev. If you see missing module errors, run + `pnpm install` first. +- `types-post-processor.mjs` runs after codegen to un-export helper types and + replace `any` with `unknown`. Do not manually edit generated type files โ€” your + changes will be overwritten. +- Draft GraphQL models must NOT include `__typename` (see ADR 0002). This is a + deliberate design decision for mutation input compatibility. +- The pre-commit hook runs `lint-staged` (prettier + eslint + tsc-files on + changed files). The `commit-msg` hook enforces conventional commits via + `commitlint`. +- `@faker-js/faker` is ESM-only since v10 โ€” Jest is configured with a custom + `transformIgnorePatterns` to handle this. Do not add faker to the ignore list. +- The `prettierPath` in `jest.test.config.js` points to `prettier-jest` (an + older version) because the latest Prettier is incompatible with Jest's snapshot + formatting. + +## Conventions + +- **Commits:** conventional commit format (enforced by commitlint). Scopes with + slashes are allowed, e.g. `refactor(app/my-component): something`. +- **Model file structure:** every model must have `types.ts`, `fields-config.ts`, + `builders.ts`, `builders.spec.ts`, and `index.ts`. Presets go in a `presets/` + subdirectory. +- **Fields config:** only assign values to required properties. For fully-populated + versions, create a `withAllFields` preset. +- **Changesets:** required for publishable changes. Run `pnpm changeset` โ€” see + `docs/guidelines/writing-changesets.md` for content guidelines. + +## Further Reading + +- `docs/contributing/test-data-models-overview.md` โ€” model architecture and public API +- `docs/guidelines/creating-new-model.md` โ€” step-by-step model creation guide +- `docs/guidelines/writing-changesets.md` โ€” changeset content guidelines +- `docs/architecture-decisions/` โ€” ADRs (notably ADR 0002: draft model `__typename` exclusion) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..59473a947 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,37 @@ +# Claude Code Configuration + +Read `AGENTS.md` for full project context โ€” it is the primary reference for this +repository's architecture, commands, constraints, and conventions. + +## MCP Servers + +See `.mcp.json` for configured servers: + +- **commercetools-developer** โ€” commercetools API docs, GraphQL schemas, OpenAPI + specs +- **context7** โ€” third-party library documentation +- **playwright** โ€” visual UI verification +- **sequential-thinking** โ€” structured multi-step reasoning + +## Hooks + +See `.claude/settings.json` for configured hooks: + +- Post-write: auto-format with Prettier + +## Skills + +Skills live in `.agents/skills/` and are symlinked into `.claude/skills/`. +Update with `npx skills update` โ€” check `git diff` afterward for lost repo-specific content. + +Shared skills installed via `skills add commercetools/agent-skills/skills/`: + +- `/repo-healthcheck-node` โ€” verify repo setup +- `/remember` โ€” persistent memory across sessions +- `/repo-maintenance-node` โ€” formatting, dead code, dependency validation +- `/jira-create-epic-from-plan` โ€” create Jira epic from markdown plan +- `/jira-implement-task` โ€” implement a Jira ticket end-to-end +- `/renovate-review` โ€” review Renovate dependency PRs +- `/renovate-migrate` โ€” migrate code for Renovate breaking changes +- `/pr-review-navigator` โ€” PR file dependency diagrams and review order +- `/security-auditor` โ€” security audit with OWASP mapping diff --git a/generators/AGENTS.md b/generators/AGENTS.md new file mode 100644 index 000000000..6e90e90ae --- /dev/null +++ b/generators/AGENTS.md @@ -0,0 +1,25 @@ +# generators + +## Purpose + +Internal CLI tool (`pnpm generate-model`) that scaffolds new test data model +files from Squirrelly templates, consumed only by developers in this repo. + +## How To Work Here + +This package is simple โ€” a `prompts`-based CLI entry point (`src/index.ts`) that +dispatches to generators. Currently the only generator is `new-test-model`. + +Templates live in `src/new-test-model/templates/`. If you need to change the +scaffolded file structure for new models, edit the templates there. The generator +uses [Squirrelly](https://squirrelly.js.org/) for template rendering. + +Root `pnpm test`, `pnpm typecheck`, and `pnpm lint` all cover this package โ€” +no package-scoped commands needed. + +## Gotchas + +- This package uses `tsx` to run TypeScript directly (`pnpm generate-model` + invokes `tsx src/index.ts`). It is not built by `preconstruct` โ€” the + `preconstruct` config in the root `package.json` only covers `generators` + for workspace resolution, but the CLI is run via `tsx`, not from `dist/`. diff --git a/generators/CLAUDE.md b/generators/CLAUDE.md new file mode 100644 index 000000000..bd09b6753 --- /dev/null +++ b/generators/CLAUDE.md @@ -0,0 +1,4 @@ +# Claude Code Configuration + +Read `AGENTS.md` for full project context. This package is part of the monorepo +โ€” see the root `AGENTS.md` for monorepo-wide commands and conventions. diff --git a/skills-lock.json b/skills-lock.json new file mode 100644 index 000000000..00be01b18 --- /dev/null +++ b/skills-lock.json @@ -0,0 +1,40 @@ +{ + "version": 1, + "skills": { + "pr-review-navigator": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "7e07bd27b2019b6f8b40458f0e9d68f33f5aa35501c42aef7d05147b7b6722ae" + }, + "remember": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "6c90f38c7dc90853cde33e54c78ace5486f66862b139bd2d9c6082b88a70a3e3" + }, + "renovate-migrate": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "9abfafafee247f87f3528fc197f36c49c42e0c625c0bd3ff2a7d20f5f40ca284" + }, + "renovate-review": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "fcbfd6b908e152a680d4a1404d072e0788a83e97251688e719b8569b39cf0a14" + }, + "repo-healthcheck-node": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "88439b482c743721e7e3c546125257973987cbd43e5b784169bf7f689aecdfce" + }, + "repo-maintenance-node": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "9c4dd7478e45279f51380e471132debcf0f6d2e687b7293d54e58f0908cb61dd" + }, + "security-auditor": { + "source": "commercetools/agent-skills", + "sourceType": "github", + "computedHash": "8243178ee8b26923ef5b125ff12f7d7c5bbb7e5f5eefdfff1237554b7cd18951" + } + } +} diff --git a/standalone/AGENTS.md b/standalone/AGENTS.md new file mode 100644 index 000000000..adf8e819a --- /dev/null +++ b/standalone/AGENTS.md @@ -0,0 +1,51 @@ +# standalone + +## Purpose + +The published package (`@commercetools/composable-commerce-test-data`) โ€” contains +all domain test data models consumed by teams across the organization in their +test suites. + +## Key Context + +- **Entry points:** each domain model is a separate `preconstruct` entrypoint + (see `package.json` `preconstruct.entrypoints`). Adding a new model requires + adding its entrypoint there. +- **`src/core/`** โ€” the builder framework. Exports `createSpecializedBuilder`, + `fake`, `sequence`, `oneOf`, `buildLimitGraphqlList`, `buildCountGraphqlList`, + and other helpers. All domain models depend on core. Changes here have + blast-radius across every model. +- **`src/graphql-types/`** โ€” auto-generated TypeScript types from GraphQL + introspection schemas (ctp, core, mc, settings). Generated by + `pnpm generate-types` from the root. Do not edit files in + `src/graphql-types/generated/` manually. +- **`src/models/`** โ€” all domain models, organized by domain area. Each model + contains `types.ts`, `fields-config.ts`, `builders.ts`, `builders.spec.ts`, + `index.ts`, and optional `presets/`. +- **Dependencies beyond root stack:** `@commercetools/platform-sdk` (REST types), + `@faker-js/faker` (random data generation), `lodash`, `omit-deep`. + +## How To Work Here + +Follow the root AGENTS.md workflows โ€” all commands (`pnpm test`, `pnpm typecheck`, +`pnpm lint`) run from the root and cover this package. To run a single model's +tests: + +```bash +pnpm test -- --testPathPattern=standalone/src/models/ +``` + +When adding a new model, remember to add the entrypoint to `package.json` +`preconstruct.entrypoints` and add re-exports from the top-level barrel files +(e.g. `src/product.ts` re-exports from `src/models/product/`). + +## Gotchas + +- **`src/core/` is high blast-radius** โ€” it is the foundation for every model + builder. Changes here affect all models. Run the full test suite after any + core change. +- **Entrypoint registration is manual** โ€” if you add a new model directory + under `src/models/` but forget to add it to `preconstruct.entrypoints` in + `package.json`, it won't be included in the published build. +- **The `files` array in `package.json`** also needs updating when adding a new + domain โ€” it controls what gets published to npm. diff --git a/standalone/CLAUDE.md b/standalone/CLAUDE.md new file mode 100644 index 000000000..bd09b6753 --- /dev/null +++ b/standalone/CLAUDE.md @@ -0,0 +1,4 @@ +# Claude Code Configuration + +Read `AGENTS.md` for full project context. This package is part of the monorepo +โ€” see the root `AGENTS.md` for monorepo-wide commands and conventions. From 6aef109a457cf664d28d0d985aa5ec07c3798ad5 Mon Sep 17 00:00:00 2001 From: Michael Salzmann Date: Tue, 14 Apr 2026 12:11:13 +0200 Subject: [PATCH 2/4] docs: consolidate AGENTS.md files into single root file Merge unique content from standalone/AGENTS.md and generators/AGENTS.md into the root AGENTS.md and remove the sub-package files. Also remove sub-package CLAUDE.md files since they only pointed to their local AGENTS.md. The repo is small enough that separate per-package files created more duplication than value. Also clarifies the two-level model folder structure (domain folder containing sub-model folders) which was slightly oversimplified in the generated template. Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 38 +++++++++++++++++++++++++-------- generators/AGENTS.md | 25 ---------------------- generators/CLAUDE.md | 4 ---- standalone/AGENTS.md | 51 -------------------------------------------- standalone/CLAUDE.md | 4 ---- 5 files changed, 29 insertions(+), 93 deletions(-) delete mode 100644 generators/AGENTS.md delete mode 100644 generators/CLAUDE.md delete mode 100644 standalone/AGENTS.md delete mode 100644 standalone/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index d172e4fa9..0b6d3d628 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,12 +13,21 @@ Two workspace packages (`pnpm-workspace.yaml`): - **`standalone/`** โ€” the published package (`@commercetools/composable-commerce-test-data`). Contains all domain models under `src/models/`, organized by domain area (product, cart, category, etc.). - Each model folder contains `types.ts`, `fields-config.ts`, `builders.ts`, - `builders.spec.ts`, `index.ts`, and an optional `presets/` directory. The - `src/core/` module provides `createSpecializedBuilder` and helpers that all - domain models depend on. + Each domain folder (e.g. `product/`) contains one or more sub-model folders + (e.g. `product/`, `product-draft/`), and each sub-model folder contains + `types.ts`, `fields-config.ts`, `builders.ts`, `builders.spec.ts`, `index.ts`, + and an optional `presets/` directory. The `src/core/` module exports + `createSpecializedBuilder`, `fake`, `sequence`, `oneOf`, + `buildLimitGraphqlList`, `buildCountGraphqlList`, and other helpers. All domain + models depend on core โ€” changes here have blast-radius across every model. + Dependencies beyond root stack: `@commercetools/platform-sdk` (REST types), + `@faker-js/faker` (random data generation), `lodash`, `omit-deep`. - **`generators/`** โ€” internal CLI tool (`pnpm generate-model`) for scaffolding - new test data models. + new test data models. A `prompts`-based CLI entry point (`src/index.ts`) + dispatches to generators โ€” currently the only generator is `new-test-model`. + Templates live in `src/new-test-model/templates/` and use + [Squirrelly](https://squirrelly.js.org/) for rendering. This package uses + `tsx` to run TypeScript directly โ€” it is not built by `preconstruct`. Every model has two representations โ€” REST and GraphQL โ€” each with a random builder and optional presets. REST types come from `@commercetools/platform-sdk`. @@ -54,7 +63,9 @@ entrypoint (see `standalone/package.json` `preconstruct.entrypoints`). versions. 4. Wire up builders in `builders.ts` using `createSpecializedBuilder`. 5. Re-export from the domain's `index.ts` and add the entrypoint to - `standalone/package.json` `preconstruct.entrypoints`. + `standalone/package.json` `preconstruct.entrypoints`. Add re-exports from the + top-level barrel files (e.g. `src/product.ts` re-exports from + `src/models/product/`). Update the `files` array in `standalone/package.json`. 6. Write builder specs validating default REST and GraphQL output shapes. 7. Run `pnpm test`, `pnpm typecheck`, and `pnpm lint`. @@ -99,14 +110,23 @@ entrypoint (see `standalone/package.json` `preconstruct.entrypoints`). - The `prettierPath` in `jest.test.config.js` points to `prettier-jest` (an older version) because the latest Prettier is incompatible with Jest's snapshot formatting. +- `src/core/` is high blast-radius โ€” it is the foundation for every model + builder. Changes here affect all models. Run the full test suite after any + core change. +- Entrypoint registration is manual โ€” if you add a new model directory under + `src/models/` but forget to add it to `preconstruct.entrypoints` in + `standalone/package.json`, it won't be included in the published build. +- The `files` array in `standalone/package.json` also needs updating when adding + a new domain โ€” it controls what gets published to npm. ## Conventions - **Commits:** conventional commit format (enforced by commitlint). Scopes with slashes are allowed, e.g. `refactor(app/my-component): something`. -- **Model file structure:** every model must have `types.ts`, `fields-config.ts`, - `builders.ts`, `builders.spec.ts`, and `index.ts`. Presets go in a `presets/` - subdirectory. +- **Model file structure:** each domain folder contains one or more sub-model + folders (e.g. `product/product/`, `product/product-draft/`). Every sub-model + must have `types.ts`, `fields-config.ts`, `builders.ts`, `builders.spec.ts`, + and `index.ts`. Presets go in a `presets/` subdirectory. - **Fields config:** only assign values to required properties. For fully-populated versions, create a `withAllFields` preset. - **Changesets:** required for publishable changes. Run `pnpm changeset` โ€” see diff --git a/generators/AGENTS.md b/generators/AGENTS.md deleted file mode 100644 index 6e90e90ae..000000000 --- a/generators/AGENTS.md +++ /dev/null @@ -1,25 +0,0 @@ -# generators - -## Purpose - -Internal CLI tool (`pnpm generate-model`) that scaffolds new test data model -files from Squirrelly templates, consumed only by developers in this repo. - -## How To Work Here - -This package is simple โ€” a `prompts`-based CLI entry point (`src/index.ts`) that -dispatches to generators. Currently the only generator is `new-test-model`. - -Templates live in `src/new-test-model/templates/`. If you need to change the -scaffolded file structure for new models, edit the templates there. The generator -uses [Squirrelly](https://squirrelly.js.org/) for template rendering. - -Root `pnpm test`, `pnpm typecheck`, and `pnpm lint` all cover this package โ€” -no package-scoped commands needed. - -## Gotchas - -- This package uses `tsx` to run TypeScript directly (`pnpm generate-model` - invokes `tsx src/index.ts`). It is not built by `preconstruct` โ€” the - `preconstruct` config in the root `package.json` only covers `generators` - for workspace resolution, but the CLI is run via `tsx`, not from `dist/`. diff --git a/generators/CLAUDE.md b/generators/CLAUDE.md deleted file mode 100644 index bd09b6753..000000000 --- a/generators/CLAUDE.md +++ /dev/null @@ -1,4 +0,0 @@ -# Claude Code Configuration - -Read `AGENTS.md` for full project context. This package is part of the monorepo -โ€” see the root `AGENTS.md` for monorepo-wide commands and conventions. diff --git a/standalone/AGENTS.md b/standalone/AGENTS.md deleted file mode 100644 index adf8e819a..000000000 --- a/standalone/AGENTS.md +++ /dev/null @@ -1,51 +0,0 @@ -# standalone - -## Purpose - -The published package (`@commercetools/composable-commerce-test-data`) โ€” contains -all domain test data models consumed by teams across the organization in their -test suites. - -## Key Context - -- **Entry points:** each domain model is a separate `preconstruct` entrypoint - (see `package.json` `preconstruct.entrypoints`). Adding a new model requires - adding its entrypoint there. -- **`src/core/`** โ€” the builder framework. Exports `createSpecializedBuilder`, - `fake`, `sequence`, `oneOf`, `buildLimitGraphqlList`, `buildCountGraphqlList`, - and other helpers. All domain models depend on core. Changes here have - blast-radius across every model. -- **`src/graphql-types/`** โ€” auto-generated TypeScript types from GraphQL - introspection schemas (ctp, core, mc, settings). Generated by - `pnpm generate-types` from the root. Do not edit files in - `src/graphql-types/generated/` manually. -- **`src/models/`** โ€” all domain models, organized by domain area. Each model - contains `types.ts`, `fields-config.ts`, `builders.ts`, `builders.spec.ts`, - `index.ts`, and optional `presets/`. -- **Dependencies beyond root stack:** `@commercetools/platform-sdk` (REST types), - `@faker-js/faker` (random data generation), `lodash`, `omit-deep`. - -## How To Work Here - -Follow the root AGENTS.md workflows โ€” all commands (`pnpm test`, `pnpm typecheck`, -`pnpm lint`) run from the root and cover this package. To run a single model's -tests: - -```bash -pnpm test -- --testPathPattern=standalone/src/models/ -``` - -When adding a new model, remember to add the entrypoint to `package.json` -`preconstruct.entrypoints` and add re-exports from the top-level barrel files -(e.g. `src/product.ts` re-exports from `src/models/product/`). - -## Gotchas - -- **`src/core/` is high blast-radius** โ€” it is the foundation for every model - builder. Changes here affect all models. Run the full test suite after any - core change. -- **Entrypoint registration is manual** โ€” if you add a new model directory - under `src/models/` but forget to add it to `preconstruct.entrypoints` in - `package.json`, it won't be included in the published build. -- **The `files` array in `package.json`** also needs updating when adding a new - domain โ€” it controls what gets published to npm. diff --git a/standalone/CLAUDE.md b/standalone/CLAUDE.md deleted file mode 100644 index bd09b6753..000000000 --- a/standalone/CLAUDE.md +++ /dev/null @@ -1,4 +0,0 @@ -# Claude Code Configuration - -Read `AGENTS.md` for full project context. This package is part of the monorepo -โ€” see the root `AGENTS.md` for monorepo-wide commands and conventions. From 66d4528165729d8e4919c8bb02fcc821e3b77e9a Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Wed, 15 Apr 2026 13:15:48 -0400 Subject: [PATCH 3/4] fix: correct MCP server name and remove uninstalled Jira skills from CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix "commercetools-developer" โ†’ "commercetools-docs" to match .mcp.json - Remove /jira-create-epic-from-plan and /jira-implement-task (not installed) - Remove jira-implement-task gitignore entry Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/.gitignore | 3 --- CLAUDE.md | 4 +--- 2 files changed, 1 insertion(+), 6 deletions(-) diff --git a/.claude/.gitignore b/.claude/.gitignore index 763ec210e..028600c99 100644 --- a/.claude/.gitignore +++ b/.claude/.gitignore @@ -1,5 +1,2 @@ # Local settings *.local.* - -# Plan artifacts from jira-implement-task skill -skills/jira-implement-task/ diff --git a/CLAUDE.md b/CLAUDE.md index 59473a947..61cc79cef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,7 @@ repository's architecture, commands, constraints, and conventions. See `.mcp.json` for configured servers: -- **commercetools-developer** โ€” commercetools API docs, GraphQL schemas, OpenAPI +- **commercetools-docs** โ€” commercetools API docs, GraphQL schemas, OpenAPI specs - **context7** โ€” third-party library documentation - **playwright** โ€” visual UI verification @@ -29,8 +29,6 @@ Shared skills installed via `skills add commercetools/agent-skills/skills/ - `/repo-healthcheck-node` โ€” verify repo setup - `/remember` โ€” persistent memory across sessions - `/repo-maintenance-node` โ€” formatting, dead code, dependency validation -- `/jira-create-epic-from-plan` โ€” create Jira epic from markdown plan -- `/jira-implement-task` โ€” implement a Jira ticket end-to-end - `/renovate-review` โ€” review Renovate dependency PRs - `/renovate-migrate` โ€” migrate code for Renovate breaking changes - `/pr-review-navigator` โ€” PR file dependency diagrams and review order From 717c4fede4e88b501680f689ae67123468e6cda1 Mon Sep 17 00:00:00 2001 From: Byron Wall Date: Wed, 15 Apr 2026 13:25:14 -0400 Subject: [PATCH 4/4] docs: add import aliases, builder API, and preset patterns to AGENTS.md Document the undocumented patterns an LLM needs to work effectively: - Path aliases (@/core, @/models/*, etc.) - Builder factory functions and fluent API methods - Fields config generators (fake, sequence, oneOf, bool) - GraphQL __typename requirement for non-draft models - postBuild callback pattern for computed fields - Preset export structure and naming conventions Co-Authored-By: Claude Opus 4.6 (1M context) --- AGENTS.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0b6d3d628..44fe3dd8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -39,6 +39,125 @@ runs after codegen to un-export colliding helper types and replace `any` with `preconstruct` builds the standalone package โ€” each domain model is a separate entrypoint (see `standalone/package.json` `preconstruct.entrypoints`). +## Import Aliases + +All imports within `standalone/` use path aliases (defined in `tsconfig.json`, +mirrored in `babel.config.js`): + +| Alias | Resolves to | +| ------------------- | -------------------------------- | +| `@/core` | `standalone/src/core` | +| `@/core/test-utils` | `standalone/src/core/test-utils` | +| `@/graphql-types` | `standalone/src/graphql-types` | +| `@/models/*` | `standalone/src/models/*` | +| `@/utils` | `standalone/src/utils` | + +Do not use relative imports to reach across these boundaries. + +## Builder API + +### Factory functions + +- **`createSpecializedBuilder({ name, type, modelFieldsConfig })`** โ€” creates a + builder for a single API type (`'rest'` or `'graphql'`). Use for + `RestModelBuilder` and `GraphqlModelBuilder`. +- **`createCompatibilityBuilder({ name, modelFieldsConfig: { rest, graphql } })`** + โ€” creates a builder that supports all three build methods. Deprecated for new + models; prefer specialized builders. + +### Builder methods + +Every builder is a Proxy with: + +- **`.build()`** โ€” returns the built object (REST for specialized rest builders, + REST for compat builders). +- **`.buildRest()`** / **`.buildGraphql()`** โ€” explicitly build one + representation. +- **`.fieldName(value)`** โ€” fluent setter for any model field. Returns the + builder for chaining. Value can be a literal, a nested builder (auto-built), + or a function `(currentState) => Partial`. +- **`.build({ omitFields: ['a'] })`** / **`.build({ keepFields: ['a'] })`** โ€” + include or exclude specific fields from the output. + +### Fields config + +Each model exports `restFieldsConfig` and `graphqlFieldsConfig` of type +`TModelFieldsConfig`: + +```ts +export const restFieldsConfig: TModelFieldsConfig = { + fields: { + id: fake((f) => f.string.uuid()), // callback receives a Faker instance + version: sequence(), // auto-incrementing number per build + status: oneOf('Active', 'Inactive'), // random pick + active: bool(), // random true/false + name: fake(() => LocalizedString.random()), // nested builder (auto-built) + }, +}; +``` + +Only assign values to **required** fields. Use presets for fully-populated +versions. + +GraphQL configs for non-draft models **must** include `__typename` as a string +literal (e.g. `__typename: 'Category'`). Draft models must **not** include it +(see ADR 0002). + +### `postBuild` callback + +Use `postBuild` when a field's value depends on other generated fields โ€” most +commonly in GraphQL configs where singular fields are derived from +`*AllLocales` arrays: + +```ts +export const graphqlFieldsConfig: TModelFieldsConfig = { + fields: { + name: null, + nameAllLocales: fake(() => LocalizedString.random()) /* ... */, + }, + postBuild: (model) => ({ + ...model, + name: LocalizedString.resolveGraphqlDefaultLocaleValue( + model.nameAllLocales + ), + }), +}; +``` + +In compat builders, `postBuild` receives a second arg `{ isCompatMode: boolean }` +to handle shape differences between REST and GraphQL field names. + +### Presets + +Presets live in `presets/` next to the model and return **builders** (not built +objects) so consumers can chain further overrides before calling `.build()`. + +Each preset file exports up to three variants (`restPreset`, `graphqlPreset`, +`compatPreset`). The `presets/index.ts` collects them: + +```ts +export const restPresets = { withAllFields: restPreset }; +export const graphqlPresets = { withAllFields: graphqlPreset }; +export const compatPresets = { withAllFields: compatPreset }; +``` + +### Model index pattern + +Each sub-model's `index.ts` wires builders and presets into the public API: + +```ts +export const MyModelRest = { + presets: presets.restPresets, + random: RestModelBuilder, +}; +export const MyModelGraphql = { + presets: presets.graphqlPresets, + random: GraphqlModelBuilder, +}; +``` + +Consumers use: `MyModelRest.random().fieldName(value).build()`. + ## How To Make Changes ### Verify your work