forgecraft-mcp 1.7.0 → 1.8.0

package/templates/api/instructions.yaml

@@ -6,100 +6,51 @@ blocks:
     title: "API Service Standards"
     content: |
       ## API Standards
-
-      ### Contract First
-      - Define OpenAPI/JSON Schema spec before implementing endpoints.
-      - Generate types from spec — don't manually duplicate.
-      - Spec is the source of truth. Implementation must match.
-
-      ### Design Rules
-      - Version from day one: /api/v1/...
-      - Proper HTTP semantics: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes.
-      - Pagination on ALL list endpoints. Never return unbounded results.
-      - Consistent response envelope: { data, meta, errors }.
-      - Async operations return job ID + polling endpoint, not blocking results.
-      - Rate limiting on all public endpoints.
-
-      ### Validation
-      - Input validation at API boundary — reject malformed requests before they reach services.
-      - Use schema validation (Pydantic, Zod, Joi) not manual if-checks.
-      - Validate request body, query params, path params, and headers.
-      - Return 422 with specific field errors, not generic 400.
-
-      ### Authentication & Authorization
-      - Auth middleware/guards at router level, not checked inside handlers.
-      - Role-based or policy-based access control via decorators/middleware.
-      - Never trust client-sent user identity — always verify from token/session.
-
-      ### Database & Migrations
-      - Schema changes managed through migration files (Prisma Migrate, Knex, Flyway, Alembic).
-      - Every migration must be reversible (up + down). Test rollbacks.
-      - Never modify a deployed migration — create a new one.
-      - Seed data separate from migrations. Test seeds run in CI.
-
-      ### Security (OWASP Top 10)
-      - **Injection**: Parameterized queries only. No string concatenation for SQL, commands, or LDAP.
-      - **Broken Auth**: Rate-limit login attempts. Enforce strong passwords. Rotate tokens.
-      - **Sensitive Data Exposure**: Encrypt at rest (AES-256). Never log PII, tokens, or passwords.
-      - **XXE/XSS**: Sanitize all user-generated HTML. Content-Security-Policy headers on all responses.
-      - **Broken Access Control**: Enforce ownership checks — users can't access other users' resources.
-      - **Security Misconfiguration**: No default credentials. No verbose error messages in production.
-        Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
-      - **CSRF**: Token-based protection on all state-changing endpoints (unless using SameSite cookies + bearer tokens).
-      - **Audit logging**: Log WHO did WHAT, WHEN, to WHICH resource. Separate from application logs.
-        Immutable. Retained per compliance requirements.
-
-      ### Graceful Shutdown
-      - Handle SIGTERM: stop accepting new requests, drain in-flight requests, close DB connections, exit.
-      - Kubernetes: readiness probe fails immediately, liveness continues during drain.
-      - Shutdown timeout configurable (default: 30s). Force exit after timeout.
+      - **Contract first**: define OpenAPI/JSON Schema before implementing; generate types from spec (no manual dupes); spec is source of truth.
+      - **Design**: version from day one (`/api/v1/...`); correct HTTP semantics (GET read, POST create, PUT replace, PATCH update, DELETE remove); pagination on ALL list endpoints; envelope `{ data, meta, errors }`; async ops return job ID + polling endpoint; rate limiting on all public endpoints.
+      - **Validation**: at the API boundary via schema (Zod/Pydantic/Joi), not manual if-checks; validate body, query, path, headers; return 422 with field errors, not generic 400.
+      - **Auth**: middleware/guards at router level (not inside handlers); RBAC/policy via middleware; never trust client-sent identity — verify from token/session.
+      - **Migrations**: through migration files (Prisma/Knex/Flyway/Alembic); reversible (up+down), test rollbacks; never modify a deployed migration; seeds separate, run in CI.
+      - **OWASP Top 10**: parameterized queries only; rate-limit logins + rotate tokens; encrypt at rest (AES-256), never log PII/tokens; sanitize user HTML + CSP; ownership checks on every resource; no default creds, no verbose prod errors; security headers (X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy); CSRF tokens on state-changing endpoints; immutable audit log (who/what/when/which) separate from app logs.
+      - **Graceful shutdown**: SIGTERM → stop intake → drain → close DB → exit; k8s readiness fails immediately, liveness continues; configurable timeout (default 30s), force exit after.
 
   - id: api-stack-constraints
     tier: core
     title: "API Stack Constraints"
     content: |
       ## API Stack Constraints — Approved Dependency Choices
-
-      These are the **approved libraries for this API project**.
-      Every choice has a banned alternative with a concrete reason.
-      If you reach for a banned alternative, stop and use the approved one instead.
-      Rationale is stated so you understand the constraint — not so you can argue around it.
+      Use the approved library; if you reach for a banned one, stop.
 
       {{#if language_is_typescript}}
-      ### TypeScript API — Required Packages
-
-      | Concern | Use | Do NOT use | Reason |
-      |---|---|---|---|
-      | **Password hashing** | `argon2@^0.31` | `bcrypt`, `bcryptjs` | `bcrypt` requires a native module (`@mapbox/node-pre-gyp`) that pulls in an old `tar` CVE chain. `argon2` is pure JS, faster, OWASP-preferred. |
-      | **HTTP framework** | `express@^4` or `fastify@^4` | `restify`, `hapi@<21`, `koa` alone | `restify` is unmaintained. `hapi` is fine at `^21+` only. |
-      | **Input validation** | `zod@^3` | `joi` alone, `express-validator` alone | `zod` infers TypeScript types natively — no separate type declaration needed. |
-      | **JWT** | `jsonwebtoken@^9` | `jwt-simple` (abandoned), `jsonwebtoken@<9` | Security fixes landed in v9. `jwt-simple` has no active maintainer. |
-      | **ORM / query builder** | `@prisma/client@^5` or `kysely@^0.27` | `typeorm`, `sequelize` | `typeorm` uses decorators (not type-safe), slow migrations. `sequelize` has weak TypeScript support. |
-      | **Logger** | `pino@^9` | `winston` alone, `console.log` in prod | `pino` is 5–10× faster than `winston` and outputs structured JSON natively. `console.log` is not structured. |
-      | **HTTP client (outbound)** | `undici@^6` or native `fetch` (Node 18+) | `axios` for Node ≥18 | Native `fetch` is available; `axios` adds bundle weight and a dependency surface for a built-in feature. |
-      | **ESLint** | `@typescript-eslint/eslint-plugin@^8` | `@typescript-eslint@^5` or `^6` | `^6` has a known CVE via old `minimatch` transitive dep. `^8` is the current stable. |
-
-      **npm audit policy**: `npm audit` must return zero `high` or `critical` findings before the
-      first commit. If a dependency introduces a high/critical CVE, replace it with an alternative
-      from this table or open an ADR documenting the exception with mitigation.
+      ### TypeScript API
+      | Concern | Use | Do NOT use |
+      |---|---|---|
+      | Password hashing | `argon2@^0.31` | `bcrypt`/`bcryptjs` (native tar CVE chain) |
+      | HTTP framework | `express@^4`/`fastify@^4` | `restify` (unmaintained), `hapi@<21`, `koa` |
+      | Input validation | `zod@^3` | `joi`/`express-validator` alone |
+      | JWT | `jsonwebtoken@^9` | `jwt-simple` (abandoned), `<9` |
+      | ORM | `@prisma/client@^5`/`kysely@^0.27` | `typeorm`, `sequelize` (weak TS) |
+      | Logger | `pino@^9` | `winston`, `console.log` in prod |
+      | HTTP client | `undici@^6`/native `fetch` | `axios` for Node ≥18 |
+      | ESLint | `@typescript-eslint/*@^8` | `^5`/`^6` (minimatch CVE) |
+
+      `npm audit` zero high/critical before first commit; else replace or ADR the exception.
       {{/if}}
 
       {{#if language_is_python}}
-      ### Python API — Required Packages
-
-      | Concern | Use | Do NOT use | Reason |
-      |---|---|---|---|
-      | **Web framework** | `fastapi@^0.110` | `flask` for new async APIs | Flask has no native `async` request handling at the framework level — blocks on every request without extra extensions. |
-      | **Validation** | `pydantic@^2` | `pydantic@^1` | v2 is 5–50× faster. v1 is not maintained for new projects. Breaking API — pin to `^2`. |
-      | **Password hashing** | `argon2-cffi@^23` | `hashlib` for passwords, `MD5/SHA256` for passwords | `hashlib` is not a KDF — it is trivially reversible with a GPU. `argon2` wins OWASP Password Hashing Competition. |
-      | **JWT** | `PyJWT@^2.8` or `python-jose[cryptography]@^3.3` | `python-jwt` (unmaintained), `itsdangerous` alone | `python-jwt` has no active maintainer. `itsdangerous` is for URL-safe tokens, not JWT. |
-      | **ORM** | `sqlalchemy@^2.0` with `asyncpg` | `sqlalchemy@^1.x` | v2 has a fundamentally better async story and type-annotated query API. |
-      | **HTTP client** | `httpx@^0.27` | `requests` in async code | `requests` is sync-only — it will block the asyncio event loop. |
-      | **Logger** | `structlog@^24` | bare `logging` module in production | Unstructured log lines are not machine-parseable. `structlog` wraps `logging` with structured output. |
-      | **Linting** | `ruff@^0.4` | `flake8` + `isort` + `black` separately | `ruff` replaces all three with one tool 10–100× faster. No reason to run them separately. |
-
-      **pip audit policy**: `pip audit` must return zero `high` or `critical` findings before the
-      first commit. If a dependency introduces a high/critical CVE, replace it or open an ADR.
+      ### Python API
+      | Concern | Use | Do NOT use |
+      |---|---|---|
+      | Web framework | `fastapi@^0.110` | `flask` for async (blocks per request) |
+      | Validation | `pydantic@^2` | `pydantic@^1` (unmaintained) |
+      | Password hashing | `argon2-cffi@^23` | `hashlib`/`MD5`/`SHA256` (not a KDF) |
+      | JWT | `PyJWT@^2.8`/`python-jose[cryptography]@^3.3` | `python-jwt`, `itsdangerous` |
+      | ORM | `sqlalchemy@^2.0` + `asyncpg` | `sqlalchemy@^1.x` |
+      | HTTP client | `httpx@^0.27` | `requests` in async (blocks loop) |
+      | Logger | `structlog@^24` | bare `logging` in prod |
+      | Linting | `ruff@^0.4` | `flake8`+`isort`+`black` separately |
+
+      `pip audit` zero high/critical before first commit; else replace or ADR.
       {{/if}}
 
   - id: api-deployment
@@ -107,125 +58,36 @@ blocks:
     title: "API Deployment & Hosting"
     content: |
       ## API Deployment
-
-      ### Container-Based (Production)
-      - Multi-stage Dockerfile: builder stage (install + compile) → runtime stage (minimal image, non-root).
-      - Pin base image digests, not just tags. Scan images for CVEs in CI (Trivy, Grype).
-      - Push to container registry (ECR, GCR, GHCR) on every merge to main.
-      - Orchestrate with Kubernetes, ECS, or Cloud Run. Define resource limits for every container.
-
-      ### PaaS / Quick Deploy
-      - **Railway**: Git-push deploy with auto-detected Dockerfile or Nixpacks. Ideal for staging and side projects.
-      - **Render**: Free tier + auto-deploy from Git. Native cron jobs, managed Postgres.
-      - **Fly.io**: Edge deployment with Firecracker VMs. Good for low-latency APIs. `fly deploy` from CI.
-      - All PaaS platforms: use platform env vars for secrets, connect managed DB add-ons, enable auto-sleep
-        for non-production to control cost.
-
-      ### Environment Management
-      - One Dockerfile, many environments. Same image runs in dev, staging, prod.
-      - Health check endpoint (`/health`) returns: status, version, uptime, dependency connectivity.
-      - Database connection pooling configured per environment (dev: 5, staging: 20, prod: 50+).
-      - Migrations run automatically on deploy (pre-deploy hook or init container). Never manually.
+      - **Containers**: multi-stage Dockerfile (builder → minimal non-root runtime); pin base image digests; scan in CI (Trivy/Grype); push to registry (ECR/GCR/GHCR) on merge to main; orchestrate (k8s/ECS/Cloud Run) with resource limits.
+      - **PaaS quick deploy**: Railway (git-push), Render (free tier, managed Postgres), Fly.io (`fly deploy`, edge). Platform env vars for secrets, managed DB add-ons, auto-sleep non-prod.
+      - **Environments**: one Dockerfile, same image dev→staging→prod; `/health` returns status/version/uptime/deps; connection pooling per env (dev 5, staging 20, prod 50+); migrations run automatically on deploy, never manually.
 
   - id: api-testing
     tier: recommended
     title: "API-Specific Testing Requirements"
     content: |
       ## API-Specific Testing Requirements
-
-      ### Contract / Consumer-Driven Contract (CDC) — Mandatory
-      CDC is not optional for API projects. The consumer writes the pact file; the provider verifies it in CI before deployment. API breakage that passes all provider-side tests but fails consumers is the exact class of defect CDC prevents.
-      - Use Pact or Spring Cloud Contract.
-      - Pact broker (self-hosted or pactflow.io) stores pact files and verification results.
-      - Provider verification runs in CI on every build — a failed verification blocks deployment.
-      - CDC covers request schema, response schema, status codes, and error shapes. It does not cover load or security — those are separate gates.
-
-      ### API / Subcutaneous Tests as Primary Integration Layer
-      The subcutaneous layer (HTTP requests to a running server with real DB and stubbed external deps) is the primary integration verification surface for API projects. Unit tests verify logic; subcutaneous tests verify contracts.
-      - Use Supertest (Node) or httpx/pytest (Python) against a locally started server instance.
-      - Stub external services with WireMock, msw, or responses (Python). Never call real external APIs in CI.
-      - Every public endpoint has a subcutaneous test for: 200 happy path, 4xx validation rejection, 401/403 auth enforcement, and at least one edge case.
-
-      ### DAST at Staging — Mandatory
-      Dynamic application security testing is required before every production promotion. OWASP ZAP minimum.
-      - Run ZAP active scan against the staging environment as a post-deploy CI step.
-      - Define an acceptable risk threshold in the spec: which finding severities are blocking (High = always blocking; Medium/Low = tracked, not blocking by default).
-      - ZAP scan configuration committed to the repo (`zap-config.yaml`). Not a one-off manual step.
-
-      ### Rate Limiting and Throttling in Integration Layer
-      - Rate limit behavior must be covered in the subcutaneous integration suite, not just documented.
-      - Test: normal traffic (no throttle), burst traffic (trigger rate limit, receive 429), retry-after header present and correct.
-      - Test quota exhaustion and quota reset behavior for API-key-based limits.
-
-
-      ### Scaling
-      - Horizontal scaling by default. No in-memory session state — use Redis or DB.
-      - Auto-scaling rules based on CPU + request queue depth, not just CPU alone.
-      - Database read replicas for read-heavy workloads. Connection pooler (PgBouncer) in front of Postgres.
+      - **CDC (mandatory)**: consumer writes pact, provider verifies in CI (Pact / Spring Cloud Contract); broker stores pacts; failed verification blocks deployment. Covers request/response schema, status codes, error shapes.
+      - **Subcutaneous tests (primary integration layer)**: HTTP to a running server, real DB, stubbed external deps (Supertest / httpx+pytest; stub with WireMock/msw/responses, never real external APIs in CI). Every endpoint: 200 happy, 4xx validation, 401/403 auth, ≥1 edge case.
+      - **DAST at staging (mandatory)**: OWASP ZAP active scan as post-deploy CI step; `zap-config.yaml` committed; High always blocking, Medium/Low tracked.
+      - **Rate limiting in integration suite**: normal (no throttle), burst (429 + correct retry-after), quota exhaustion + reset for API-key limits.
+      - **Scaling**: horizontal by default, no in-memory session (Redis/DB); auto-scale on CPU + queue depth; read replicas + PgBouncer for read-heavy.
 
   - id: api-smoke-testing
     tier: recommended
     title: "API Smoke Testing (Post-Deploy)"
     content: |
       ## API Smoke Testing
-
-      ### Required: Playwright APIRequestContext (no browser overhead)
-      Tag all smoke tests `@smoke` for isolated execution:
+      Playwright APIRequestContext (no browser). Tag `@smoke`:
       ```
       npx playwright test --config playwright.smoke.config.ts --grep @smoke
       ```
 
-      Minimum smoke suite for every API:
-      - **Health check**: `GET /health` → 200, body includes `status: ok` and `version`
-      - **Auth**: primary login endpoint with valid credentials → token returned
-      - **Primary read**: one representative `GET` → 200, response envelope validates
-      - **Primary write**: one representative `POST` → 2xx, verify with follow-up `GET`
-      - **404 shape**: non-existent resource → 404, error envelope matches spec contract
-
-      ```typescript
-      // tests/smoke/api.smoke.ts
-      import { test, expect } from '@playwright/test';
+      Minimum suite:
+      - Health: `GET /health` → 200, body has `status: ok` + `version`
+      - Auth: primary login with valid creds → token returned
+      - Primary read: representative `GET` → 200, envelope validates
+      - Primary write: representative `POST` → 2xx, verify with follow-up `GET`
+      - 404 shape: missing resource → 404, error envelope matches contract
 
-      test('@smoke health check', async ({ request }) => {
-        const res = await request.get('/health');
-        expect(res.ok()).toBeTruthy();
-        const body = await res.json();
-        expect(body).toMatchObject({ status: 'ok' });
-      });
-
-      test('@smoke auth returns token', async ({ request }) => {
-        const res = await request.post('/api/v1/auth/login', {
-          data: {
-            email: process.env['SMOKE_USER'],
-            password: process.env['SMOKE_PASSWORD'],
-          },
-        });
-        expect(res.status()).toBe(200);
-        const body = await res.json();
-        expect(typeof body.token ?? body.data?.token).toBe('string');
-      });
-      ```
-
-      ```typescript
-      // playwright.smoke.config.ts
-      import { defineConfig } from '@playwright/test';
-      export default defineConfig({
-        use: { baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000' },
-        testMatch: '**/*.smoke.ts',
-        retries: 1,
-        timeout: 10_000,
-      });
-      ```
-
-      Smoke tests run against the **deployed staging URL** only (`PLAYWRIGHT_BASE_URL` env var).
-      They never run against localhost in CI — that is the integration suite's job.
-
-      CI integration (post-deploy step):
-      ```yaml
-      - name: Smoke Tests
-        run: npx playwright test --config playwright.smoke.config.ts
-        env:
-          PLAYWRIGHT_BASE_URL: ${{ env.STAGING_URL }}
-          SMOKE_USER: ${{ secrets.SMOKE_USER }}
-          SMOKE_PASSWORD: ${{ secrets.SMOKE_PASSWORD }}
-      ```
+      Run against the deployed staging URL only (`PLAYWRIGHT_BASE_URL`), never localhost in CI (that's the integration suite). Wire as a post-deploy CI step with `PLAYWRIGHT_BASE_URL`, `SMOKE_USER`, `SMOKE_PASSWORD` from secrets.