create-rigel 0.1.0

package/templates/nextjs/.github/workflows/ci.yml

@@ -0,0 +1,143 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+# Least-privilege default token. Jobs opt into more only where needed.
+permissions:
+  contents: read
+
+# Cancel superseded runs on the same ref.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: typecheck · lint · format · test · build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # The bare template has no package.json (it's generated by /infra-setup).
+      # Skip the real steps until an app exists so this stays green on the harness itself.
+      - name: Detect app
+        id: app
+        run: |
+          if [ -f package.json ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No package.json yet (bare harness) — skipping verify steps. Run /infra-setup to scaffold the app."
+          fi
+
+      - uses: actions/setup-node@v4
+        if: steps.app.outputs.exists == 'true'
+        with:
+          node-version: 'lts/*'
+          cache: npm
+
+      - name: Install
+        if: steps.app.outputs.exists == 'true'
+        run: npm ci
+
+      - name: Type-check
+        if: steps.app.outputs.exists == 'true'
+        run: npm run typecheck
+
+      - name: Lint
+        if: steps.app.outputs.exists == 'true'
+        run: npm run lint
+
+      - name: Format check
+        if: steps.app.outputs.exists == 'true'
+        run: npm run format:check
+
+      - name: Test (coverage)
+        if: steps.app.outputs.exists == 'true'
+        run: npm run test:coverage
+
+      - name: Build
+        if: steps.app.outputs.exists == 'true'
+        env:
+          # env.ts validates this at build time; a dummy value is fine for CI build.
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+        run: npm run build
+
+  # End-to-end browser tests (Playwright). Separate job so a flaky e2e never blocks
+  # the fast verify signal, and so the browser download is cached independently.
+  e2e:
+    name: e2e (Playwright)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Detect app
+        id: app
+        run: |
+          if [ -f package.json ]; then echo "exists=true" >> "$GITHUB_OUTPUT";
+          else echo "exists=false" >> "$GITHUB_OUTPUT"; echo "::notice::No app yet — skipping e2e."; fi
+      - uses: actions/setup-node@v4
+        if: steps.app.outputs.exists == 'true'
+        with:
+          node-version: 'lts/*'
+          cache: npm
+      - name: Install
+        if: steps.app.outputs.exists == 'true'
+        run: npm ci
+      - name: Install Playwright browsers
+        if: steps.app.outputs.exists == 'true'
+        run: npx playwright install --with-deps chromium
+      - name: Run e2e
+        if: steps.app.outputs.exists == 'true'
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+        run: npm run test:e2e
+
+  # Dependency vulnerabilities + leaked secrets. Runs on the bare harness too
+  # (gitleaks scans history; audit no-ops without a lockfile).
+  security:
+    name: audit · secret-scan
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # gitleaks needs full history
+
+      - name: Detect app
+        id: app
+        run: |
+          if [ -f package-lock.json ]; then echo "lock=true" >> "$GITHUB_OUTPUT";
+          else echo "lock=false" >> "$GITHUB_OUTPUT"; echo "::notice::No lockfile yet — skipping npm audit."; fi
+
+      - uses: actions/setup-node@v4
+        if: steps.app.outputs.lock == 'true'
+        with:
+          node-version: 'lts/*'
+          cache: npm
+
+      - name: npm audit (high+)
+        if: steps.app.outputs.lock == 'true'
+        run: npm audit --audit-level=high
+
+      # Use the gitleaks CLI via Docker, NOT gitleaks-action — the action requires a
+      # paid license on GitHub Organizations; the CLI/image is free everywhere.
+      - name: Secret scan (gitleaks)
+        run: docker run --rm -v "${{ github.workspace }}:/repo" ghcr.io/gitleaks/gitleaks:latest detect --source=/repo --redact --verbose
+
+  # GitHub's dependency-review blocks PRs that introduce vulnerable/incompatible deps.
+  # PR-only (the action requires a base..head diff).
+  dependency-review:
+    name: dependency-review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          comment-summary-in-pr: on-failure

package/templates/nextjs/.github/workflows/lighthouse.yml

@@ -0,0 +1,54 @@
+name: Lighthouse CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lighthouse-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lighthouse:
+    name: Core Web Vitals budget
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Skip until /infra-setup has generated the app.
+      - name: Detect app
+        id: app
+        run: |
+          if [ -f package.json ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No package.json yet (bare harness) — skipping Lighthouse."
+          fi
+
+      - uses: actions/setup-node@v4
+        if: steps.app.outputs.exists == 'true'
+        with:
+          node-version: 'lts/*'
+          cache: npm
+
+      - name: Install
+        if: steps.app.outputs.exists == 'true'
+        run: npm ci
+
+      - name: Build
+        if: steps.app.outputs.exists == 'true'
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+        run: npm run build
+
+      - name: Lighthouse CI
+        if: steps.app.outputs.exists == 'true'
+        env:
+          NEXT_PUBLIC_API_URL: http://localhost:8000
+        run: npx --yes @lhci/cli@latest autorun --config=lighthouserc.js

package/templates/nextjs/.github/workflows/load-test.yml

@@ -0,0 +1,54 @@
+name: Load Test
+
+# Manual only — never runs on push or PR. Trigger from the Actions tab
+# (GitHub → Actions → Load Test → Run workflow) and point it at any reachable URL.
+on:
+  workflow_dispatch:
+    inputs:
+      base_url:
+        description: 'Target base URL (e.g. https://staging.example.com)'
+        required: true
+        type: string
+      test:
+        description: 'Which test to run'
+        required: true
+        type: choice
+        default: smoke
+        options:
+          - smoke
+          - stress
+          - soak
+      auth_token:
+        description: 'Bearer token for authenticated endpoints (optional)'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  load-test:
+    name: k6 ${{ inputs.test }} → ${{ inputs.base_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      # The k6 scripts are written by /infra-setup (tests/load/*.js). Fail loudly with
+      # a fix hint if they are missing, instead of a cryptic k6 "file not found".
+      - name: Verify load script exists
+        run: |
+          script="tests/load/${{ inputs.test }}.js"
+          if [ ! -f "$script" ]; then
+            echo "::error::$script not found. Run /infra-setup to scaffold tests/load/, or add the script."
+            exit 1
+          fi
+
+      - name: Install k6
+        uses: grafana/setup-k6-action@v1
+
+      - name: Run k6 ${{ inputs.test }}
+        env:
+          BASE_URL: ${{ inputs.base_url }}
+          AUTH_TOKEN: ${{ inputs.auth_token }}
+        run: k6 run tests/load/${{ inputs.test }}.js

package/templates/nextjs/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/templates/nextjs/.lintstagedrc.json

@@ -0,0 +1,4 @@
+{
+  "*.{ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{json,css,md,mjs}": ["prettier --write"]
+}

package/templates/nextjs/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    }
+  }
+}

package/templates/nextjs/.prettierignore

@@ -0,0 +1,13 @@
+.next
+out
+node_modules
+dist
+coverage
+playwright-report
+test-results
+package-lock.json
+# Auto-generated by Next on every build — not prettier-clean, gitignored. Excluding it
+# keeps `format:check` (gate + CI) green after a build regenerates it.
+next-env.d.ts
+# Generated — never format (READ ONLY, regenerated by /api-sync)
+src/types/api.generated.ts

package/templates/nextjs/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "printWidth": 100,
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "useTabs": false,
+  "plugins": ["prettier-plugin-tailwindcss"]
+}

package/templates/nextjs/AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS.md — Navigation Map
+
+Stack (latest LTS — no version pins): Next.js · React · TypeScript (strict) · Tailwind CSS · shadcn/ui · TanStack Query · Zustand · openapi-fetch · Vitest · Playwright
+
+---
+
+## 🗺️ Where Everything Lives
+
+| What you need | Where |
+|---|---|
+| First 30 minutes / day-one guide | `QUICKSTART.md` |
+| Layer rules + dependency diagram | `ARCHITECTURE.md` |
+| Engineering constitution | `docs/design-docs/core-beliefs.md` |
+| Active execution plan | `docs/exec-plans/active/` |
+| Completed plans | `docs/exec-plans/completed/` |
+| Product roadmap (feature areas → specs, dependency order) | `docs/product-specs/ROADMAP.md` |
+| Product specs (draft) | `docs/product-specs/draft/` |
+| Product specs (approved) | `docs/product-specs/ready/` |
+| Architectural decisions | `docs/design-docs/decisions/` |
+| Tech debt | `docs/exec-plans/tech-debt-tracker.md` |
+| Domain health grades | `docs/QUALITY_SCORE.md` |
+| API contract (generated) | `src/types/api.generated.ts` ← READ ONLY |
+| Plan format | `docs/PLANS.md` |
+
+---
+
+## ⚡ Slash Commands
+
+| Command | What it does |
+|---|---|
+| `/infra-setup` | Phase 0 — full Next.js scaffold (run once) |
+| `/write-roadmap` | Brief + `openapi.json` → ordered frontend spec roadmap → `docs/product-specs/ROADMAP.md` |
+| `/write-spec` | Write product spec → `docs/product-specs/draft/` |
+| `/write-plan` | Turn READY spec into execution plan |
+| `/build-layer` | Build next unchecked layer + run gate |
+| `/validate-layer` | Gate check without building |
+| `/push-layer` | Commit + push with conventional message |
+| `/layer-check` | Ad-hoc architecture violation scan |
+| `/garbage-collect` | End-of-feature cleanup |
+| `/doc-garden` | Fix stale documentation |
+| `/api-sync` | Regenerate `api.generated.ts` from OpenAPI spec file |
+| `/perf-budget` | Run Lighthouse CI + bundle analysis |
+
+---
+
+## 🤖 Agents
+
+| Agent | When to use |
+|---|---|
+| `gate-checker` | Auto-called by `/build-layer` — PASS/FAIL |
+| `reviewer` | Before opening a PR |
+| `arch-validator` | Deep import + layer scan |
+| `security-auditor` | Before any auth/data-exposure PR |
+| `perf-auditor` | Core Web Vitals + bundle size gatekeeper |
+| `contract-checker` | Detect API contract drift |
+| `doc-gardener` | Fix stale docs |
+| `garbage-collector` | End-of-feature cleanup |
+
+---
+
+## ✅ Non-Negotiable Invariants
+
+- No `console.log` in `src/` → use error boundaries or monitoring
+- No `process.env` outside `src/lib/env.ts`
+- No direct `fetch()` in components or pages → all API calls via hooks in `src/hooks/`
+- No business logic in `app/` pages → pages are layout + data trigger only
+- No hand-written types that duplicate `api.generated.ts`
+- `api.generated.ts` is READ ONLY — regenerated by `/api-sync`, never edited manually
+- Access tokens stored in memory only — never `localStorage`
+- All images via `next/image` — never raw `<img>`
+- Every `use client` must have a comment explaining why it needs client rendering
+- No file > 400 lines → split into focused modules
+- TypeScript strict — no `any`, no `as SomeType` on API response data
+
+---
+
+## 🔁 The Flow
+
+```
+# Whole product (once, after the backend ships its openapi.json):
+/write-roadmap  →  human reviews ROADMAP  →  pick the walking-skeleton spec
+
+# Every feature (repeat down the roadmap, as backend specs ship):
+/write-spec (roadmap-guided)  →  human marks READY  →  /write-plan
+  →  /api-sync (ensure contract is current)
+  →  /build-layer (repeats, gate-enforced)
+  →  /garbage-collect  →  plan closed
+```

package/templates/nextjs/ARCHITECTURE.md

@@ -0,0 +1,165 @@
+# ARCHITECTURE.md — Layered Architecture
+
+Stack (latest LTS — no version pins): Next.js · React · TypeScript (strict) · Tailwind CSS · shadcn/ui · TanStack Query
+
+---
+
+## Dependency Layer Diagram
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Utils (src/utils/)  — stateless helpers, zero domain imports    │
+│                         100% test coverage required              │
+└─────────────────────────────┬────────────────────────────────────┘
+                              │
+┌─────────────────────────────▼────────────────────────────────────┐
+│                                                                   │
+│  Types (src/types/)                                               │
+│  ├─ api.generated.ts  ← READ ONLY — from /api-sync              │
+│  └─ domain.types.ts   ← frontend-only types (no duplication)    │
+│                                                                   │
+│  Lib (src/lib/)                                                   │
+│  ├─ env.ts            ← Zod-validated NEXT_PUBLIC_* env vars     │
+│  ├─ api-client.ts     ← openapi-fetch instance (typed)          │
+│  └─ constants.ts                                                  │
+│                                                                   │
+│  Hooks (src/hooks/)   ← "Repo" layer — ALL API calls live here  │
+│  ├─ use-applications.ts    ← TanStack Query per domain          │
+│  └─ use-auth.ts                                                   │
+│                                                                   │
+│  Store (src/store/)   ← Zustand — client-only UI state          │
+│  └─ Only state that does NOT belong on the server               │
+│                                                                   │
+│  Features (src/features/)  ← Feature-scoped modules             │
+│  ├─ applications/          ← components + feature hooks         │
+│  └─ auth/                                                         │
+│                                                                   │
+│  Components (src/components/)  ← Shared design system           │
+│  ├─ ui/         ← shadcn/ui (copy-owned — in your repo)        │
+│  └─ shared/     ← cross-feature shared components               │
+│                                                                   │
+│  App (app/)     ← Next.js App Router — routing only             │
+│  ├─ (auth)/     ← public auth routes                            │
+│  ├─ (dashboard)/← protected routes (auth guard in layout)       │
+│  └─ api/        ← Next.js API routes (cookie auth only)         │
+│                                                                   │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Layer Definitions
+
+### Types (`src/types/`)
+- `api.generated.ts` — **NEVER edit this file**. Generated by `/api-sync` from the OpenAPI spec.
+- `domain.types.ts` — Frontend-only types (UI state, component props, form inputs). Must NOT duplicate api.generated.ts.
+- Zero imports from other layers.
+
+### Lib (`src/lib/`)
+- `env.ts` — Zod-validated NEXT_PUBLIC_* env vars. `process.env` only here.
+- `api-client.ts` — Single openapi-fetch client instance. Auth headers injected here.
+- Imports: Types only.
+
+### Hooks (`src/hooks/`)
+- **The only place API calls happen.** TanStack Query hooks per domain.
+- Imports: Types, Lib
+- Every hook wraps openapi-fetch via the api-client.
+- Never call raw `fetch()` here — always through api-client.
+
+### Store (`src/store/`)
+- Zustand for client-only state: sidebar open/closed, selected tab, modal state.
+- **NOT** for server data (that lives in TanStack Query cache).
+- Imports: Types only.
+
+### Features (`src/features/`)
+- Feature-scoped components, forms, and feature-specific hooks.
+- Imports: Types, Lib, Hooks, Store, Components, Utils.
+- Never imports from `app/` (no routing concerns).
+
+### Components (`src/components/`)
+- `ui/` — shadcn/ui components (yours to own and modify).
+- `shared/` — cross-feature components (layout, nav, data tables).
+- Imports: Types, Utils only. No hooks, no store.
+
+### App (`app/`)
+- Next.js App Router pages and layouts — **routing only**.
+- Pages render Feature components and trigger data fetches.
+- Business logic lives in Features, not in pages.
+- Imports: Features, Components only.
+
+### Utils (`src/utils/`)
+- Pure, stateless TypeScript functions. Zero domain imports.
+- 100% test coverage required.
+- Examples: `formatDate.ts`, `cn.ts` (Tailwind class merger), `parseError.ts`
+
+---
+
+## Import Rules (ESLint enforces)
+
+```
+Types      →  (nothing)
+Lib        →  Types
+Hooks      →  Types, Lib
+Store      →  Types
+Features   →  Types, Lib, Hooks, Store, Components, Utils
+Components →  Types, Utils
+App        →  Features, Components
+Utils      →  (nothing — stdlib only)
+```
+
+**Forbidden:**
+- `fetch()` in components, features, or pages (use hooks)
+- `process.env` outside `src/lib/env.ts`
+- Business logic in `app/` pages
+- Editing `src/types/api.generated.ts` manually
+- Storing access tokens in `localStorage` or `sessionStorage`
+- `<img>` tags — use `next/image`
+
+---
+
+## Server Components vs Client Components
+
+**Default: Server Component** (no directive needed)
+- Pages that only render data
+- Layout components
+- Static content
+
+**`'use client'` required when:**
+- Using React hooks (`useState`, `useEffect`, `useRef`)
+- Using browser APIs
+- Using TanStack Query hooks (via `QueryClientProvider`)
+- Using event handlers directly on interactive elements
+
+**Rule:** Every `'use client'` directive must have a comment: `// Client: needs [reason]`
+
+---
+
+## Auth Token Strategy (matches backend)
+
+The backend issues:
+- **Access token** (JWT, 15 min) — sent as `Authorization: Bearer` header
+- **Refresh token** (JWT, 7 days) — stored in `httpOnly` cookie by the backend
+
+Frontend storage:
+- Access token → React context/memory only. **Never localStorage.**
+- Refresh token → Backend sets httpOnly cookie. Frontend never touches it.
+- On 401 → call `/api/auth/refresh` → backend reads cookie, issues new access token.
+
+---
+
+## File Size Limit
+- **400 lines max** per file
+- Enforced by: PostToolUse hook + gate-checker
+
+---
+
+## Naming Conventions
+
+| Layer | Pattern | Example |
+|---|---|---|
+| Hooks | `use-{domain}.ts` | `use-applications.ts` |
+| Feature components | `{Domain}{Component}.tsx` | `ApplicationCard.tsx` |
+| Shared components | `{Component}.tsx` | `DataTable.tsx` |
+| Utils | `{name}.util.ts` | `format-date.util.ts` |
+| Stores | `{domain}-store.ts` | `ui-store.ts` |
+| Page | `page.tsx` | `app/(dashboard)/applications/page.tsx` |

package/templates/nextjs/Dockerfile

@@ -0,0 +1,38 @@
+# syntax=docker/dockerfile:1
+# Multi-stage production image for the Next.js app.
+# Requires `output: 'standalone'` in next.config.ts (the harness sets it).
+# Result: a minimal image that runs as a non-root user with a healthcheck.
+# Owned by the platform team (see .github/CODEOWNERS).
+
+# ---- deps: reproducible install from the committed lockfile ----
+FROM node:lts-bookworm-slim AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# ---- builder: compile the app ----
+FROM node:lts-bookworm-slim AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+ENV NEXT_TELEMETRY_DISABLED=1
+# NEXT_PUBLIC_* are inlined at build time. Override at build with --build-arg.
+ARG NEXT_PUBLIC_API_URL=http://localhost:8000
+ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
+RUN npm run build
+
+# ---- runner: copy only the standalone output, run as non-root ----
+FROM node:lts-bookworm-slim AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN mkdir .next && chown node:node .next
+COPY --from=builder --chown=node:node /app/public ./public
+COPY --from=builder --chown=node:node /app/.next/standalone ./
+COPY --from=builder --chown=node:node /app/.next/static ./.next/static
+USER node
+EXPOSE 3000
+ENV PORT=3000 HOSTNAME=0.0.0.0
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:3000/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "server.js"]

package/templates/nextjs/Makefile

@@ -0,0 +1,50 @@
+# Daily-driver targets — thin wrappers over the npm scripts so muscle memory works.
+# Committed in the template (parked/restored by /infra-setup). Run `make help`.
+# NOTE: recipes are TAB-indented (Make requirement).
+.DEFAULT_GOAL := help
+.PHONY: help setup dev build start lint format typecheck test coverage e2e gate api-sync analyze docker-build
+
+help: ## List available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+setup: ## Phase 0 infra setup (run after the create-next-app scaffold step)
+	bash .claude/scripts/infra-setup.sh
+
+dev: ## Run the dev server
+	npm run dev
+
+build: ## Production build
+	npm run build
+
+start: ## Start the production server
+	npm run start
+
+lint: ## ESLint (flat config)
+	npm run lint
+
+format: ## Prettier (write)
+	npm run format
+
+typecheck: ## tsc --noEmit
+	npm run typecheck
+
+test: ## Unit tests (watch)
+	npm run test
+
+coverage: ## Unit tests + per-layer coverage gate
+	npm run test:coverage
+
+e2e: ## Playwright end-to-end tests
+	npm run test:e2e
+
+gate: ## Full layer gate (typecheck + lint + format:check + coverage)
+	npm run gate
+
+api-sync: ## Regenerate API types from openapi.json
+	npm run api:sync
+
+analyze: ## Bundle analysis
+	npm run analyze
+
+docker-build: ## Build the production container image
+	docker build -t app:local .