# Personal Coding Preferences

## Language & Style
- I prefer TypeScript over JavaScript in all new files.
- Use `const` by default; only use `let` when reassignment is necessary.
- Prefer named exports over default exports.
- Use early returns to reduce nesting — never nest more than 3 levels deep.

## Formatting
- Use 2-space indentation in TypeScript, JavaScript, JSON, and YAML.
- Use 4-space indentation in Python and Rust.
- Always add trailing commas in multi-line arrays and objects.
- Prefer single quotes in JS/TS; double quotes in Python.

## Communication
- When explaining changes, be concise. Skip obvious descriptions.
- If a refactor touches more than 5 files, summarize the blast radius first.
- Never add comments that restate what the code already says.

## Git
- Write commit messages in imperative mood ("Add feature" not "Added feature").
- Keep the first line under 72 characters.
- Always include a blank line between the subject and body.

# Project: InvoiceTracker API

## Architecture
- This is a Node.js REST API using Express and Prisma ORM.
- All routes live in src/routes/ and follow the pattern: src/routes/{resource}.routes.ts
- Business logic lives in src/services/ — routes must NOT contain business logic directly.
- Database models are defined in prisma/schema.prisma — never edit the DB directly.

## Build & Run
- Install: `npm install`
- Dev server: `npm run dev` (runs on port 3001)
- Production build: `npm run build && npm start`
- Database migrations: `npx prisma migrate dev`

## Testing
- Test framework: Vitest
- Run all tests: `npm test`
- Run specific test: `npx vitest run src/services/__tests__/invoice.test.ts`
- Tests must pass before any commit. Run them after making changes.

## Conventions
- All API responses use the envelope format: `{ success: boolean, data?: T, error?: string }`
- Errors are handled by the global error middleware in src/middleware/errorHandler.ts
- Input validation uses Zod schemas co-located with routes.
- Environment variables are accessed through src/config/env.ts — never use process.env directly.

## Do NOT
- Do not install new dependencies without asking first.
- Do not modify the CI workflow files in .github/workflows/.
- Do not change the Prisma schema without discussing migration strategy.

# Route Handler Rules

- Every route handler MUST validate its input using the co-located Zod schema.
- Never import from src/services/ files that belong to a different domain.
  For example, invoice.routes.ts may import from invoice.service.ts but NOT from user.service.ts.
  Cross-domain calls go through the event bus in src/events/.
- All route files export a single Express Router instance as the default export.
- Always include request logging middleware for POST, PUT, and DELETE operations.

# Utility Function Rules

- Every function in this directory must be a pure function — no side effects, no I/O.
- Every function must have explicit TypeScript return types (no inference).
- Every function must have at least one unit test in the adjacent __tests__/ folder.
- Do not import from any src/ directory other than src/types/.

---
description: Enforce strict TypeScript conventions
globs:
  - "**/*.ts"
  - "**/*.tsx"
---

# TypeScript Strict Mode Rules

- Always enable `strict: true` in tsconfig. If you create a new tsconfig, include it.
- Never use `any` type. Use `unknown` and narrow with type guards.
- All function parameters and return types must be explicitly annotated.
- Prefer `interface` over `type` for object shapes that may be extended.
- Use `readonly` for properties that should not be reassigned after construction.
- Prefer `as const` assertions over enum for string unions.

---
description: Python file naming and style conventions
globs:
  - "**/*.py"
---

# Python Conventions

- Use snake_case for all variables, functions, and file names.
- Use PascalCase only for class names.
- All modules must include a module-level docstring.
- Type hints are required on all public function signatures.
- Use pathlib.Path instead of os.path for filesystem operations.
- Prefer f-strings over .format() or % formatting.

---
description: Automatically run tests when test files are modified
globs:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
---

# Test File Rules

- After editing any test file, run the corresponding test suite to confirm it passes.
- Use `npx vitest run {filepath}` for individual test files.
- If a test fails, fix the test or the source code — do not skip or comment out tests.
- Test descriptions should follow the pattern: "should {expected behavior} when {condition}".

---
description: Database migration safety rules
globs:
  - "prisma/**"
  - "drizzle/**"
  - "**/migrations/**"
---

# Migration Safety

- NEVER drop a column or table without explicit user confirmation.
- All migrations must be reversible — include both `up` and `down` operations.
- After generating a migration, read the SQL and summarize what it does before proceeding.
- Test migrations against a local database before marking the task complete.

---
name: deploy
description: Build, test, and deploy the application to the staging environment
context: fork
allowed-tools:
  - Bash
  - Read
  - Grep
---

# Deploy Skill

Execute the following steps in order. Stop immediately if any step fails.

## Step 1: Pre-flight Checks
- Run `git status` and confirm the working tree is clean. If there are uncommitted changes, warn the user and stop.
- Confirm we are on the `main` or `staging` branch. If not, warn and stop.

## Step 2: Run Tests
- Execute `npm test` and wait for completion.
- If any tests fail, report the failures and stop. Do not deploy with failing tests.

## Step 3: Build
- Run `npm run build`.
- Verify the `dist/` directory was created and contains output.

## Step 4: Deploy
- Run `npm run deploy:staging`.
- Capture and report the deployment URL.

## Step 5: Verify
- Run `curl -s {deployment_url}/health` and confirm a 200 response.
- Report the deployment status to the user.

---
name: review
description: Perform a structured code review on staged changes
context: fork
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# Code Review Skill

Review the current staged changes (`git diff --cached`) against the following checklist:

## Security
- [ ] No hardcoded secrets, API keys, or credentials
- [ ] User input is validated and sanitized before use
- [ ] SQL queries use parameterized statements (no string concatenation)

## Quality
- [ ] Functions are under 50 lines; if longer, suggest extraction
- [ ] No duplicated logic — check if similar code exists elsewhere with Grep
- [ ] Error cases are handled explicitly (no silent catches)

## Testing
- [ ] New functions have corresponding tests
- [ ] Edge cases are covered (null, empty, boundary values)

## Style
- [ ] Naming is clear and follows project conventions
- [ ] No commented-out code left in place
- [ ] Imports are organized and unused imports removed

Output a structured review with findings grouped by category.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 .claude/hooks/block_dangerous_commands.py"
      },
      {
        "matcher": "Edit",
        "command": "python3 .claude/hooks/check_file_locked.py"
      }
    ]
  }
}

#!/usr/bin/env python3
"""
PreToolUse hook: Block dangerous Bash commands.
Receives tool invocation JSON on stdin.
Exit 0 to allow, exit 1 to block.
"""
import sys
import json

BLOCKED_PATTERNS = [
    "rm -rf /",
    "rm -rf ~",
    "git push --force",
    "git reset --hard",
    "DROP TABLE",
    "DROP DATABASE",
    "> /dev/sda",
]

data = json.load(sys.stdin)
tool_input = data.get("tool_input", {})
command = tool_input.get("command", "")

for pattern in BLOCKED_PATTERNS:
    if pattern.lower() in command.lower():
        print(f"BLOCKED: Command contains dangerous pattern '{pattern}'", file=sys.stderr)
        sys.exit(1)

sys.exit(0)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "python3 .claude/hooks/lint_on_write.py"
      },
      {
        "matcher": "Edit",
        "command": "python3 .claude/hooks/lint_on_write.py"
      }
    ]
  }
}

#!/usr/bin/env python3
"""
PostToolUse hook: Run ESLint after any file write/edit.
"""
import sys
import json
import subprocess

data = json.load(sys.stdin)
tool_input = data.get("tool_input", {})
file_path = tool_input.get("file_path", "")

# Only lint JS/TS files
if file_path.endswith((".ts", ".tsx", ".js", ".jsx")):
    result = subprocess.run(
        ["npx", "eslint", "--fix", file_path],
        capture_output=True, text=True
    )
    if result.returncode != 0:
        print(f"Lint issues found in {file_path}:", file=sys.stderr)
        print(result.stdout, file=sys.stderr)
        # Non-zero exit here informs Claude of the lint failure
        sys.exit(1)

sys.exit(0)

# Single prompt, printed output, non-interactive
claude -p "Review the changes in this PR for security issues" --output-format json

# Pipe input for context
git diff main...HEAD | claude -p "Review this diff for bugs and security issues"

# Use a specific model
claude -p "Generate unit tests for src/auth.ts" --model claude-sonnet-4-20250514

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for accurate diffs

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Get the diff between the PR branch and base
          DIFF=$(git diff origin/${{ github.base_ref }}...HEAD)

          # Run Claude in headless mode
          REVIEW=$(echo "$DIFF" | claude -p \
            "Review this pull request diff. Check for:
             1. Bugs and logic errors
             2. Security vulnerabilities
             3. Performance issues
             4. Style violations
             Output a concise markdown review." \
            --output-format text)

          # Post the review as a PR comment
          gh pr comment ${{ github.event.pull_request.number }} \
            --body "$REVIEW"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Restrict Claude to read-only tools in CI
claude -p "Review this code" \
  --allowedTools "Read,Grep,Glob" \
  --output-format text

---
name: security-auditor
description: Reviews code with a security-first mindset
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

# Security Auditor Agent

You are a security-focused code reviewer. Your primary concern is identifying
vulnerabilities, unsafe patterns, and security anti-patterns.

## Focus Areas
- **Injection attacks**: SQL injection, XSS, command injection, path traversal
- **Authentication/Authorization**: Missing auth checks, privilege escalation, insecure token handling
- **Data exposure**: Sensitive data in logs, overly permissive API responses, PII leakage
- **Dependency risk**: Known vulnerable packages, outdated dependencies

## Behavior
- When reviewing code, always check imports for known-vulnerable packages.
- Search the codebase for related security controls before suggesting changes.
- Classify findings by severity: CRITICAL, HIGH, MEDIUM, LOW.
- Provide a fix for every finding — never just report a problem without a solution.

## Output Format
For each finding:
1. **Severity**: [CRITICAL/HIGH/MEDIUM/LOW]
2. **Location**: file path and line number
3. **Description**: What the vulnerability is
4. **Fix**: Concrete code change to remediate

---
name: api-designer
description: Designs and implements REST APIs following best practices
allowed-tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Write
  - Bash
---

# API Designer Agent

You are an API design specialist. You follow REST conventions strictly and
prioritize consistency, discoverability, and backward compatibility.

## Design Principles
- Use plural nouns for resource names: /users, /invoices, /payments
- Use HTTP methods correctly: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes
- Always version the API: /api/v1/
- Return consistent envelope format: { success, data, error, meta }
- Use proper HTTP status codes: 201 for creation, 204 for deletion, 422 for validation errors

## When Designing a New Endpoint
1. Check existing endpoints for consistency in naming and response format
2. Define the Zod validation schema first
3. Implement the route handler
4. Add the service layer logic
5. Write integration tests
6. Update the API documentation