create-rigel 0.1.0

package/templates/nextjs/.claude/agents/reviewer.md

@@ -0,0 +1,79 @@
+---
+name: reviewer
+description: Full harness review before opening a PR. Run with "Use the reviewer agent to review current changes."
+model: claude-opus-4-8
+tools: [Read, Bash]
+color: blue
+---
+
+You are a senior frontend engineer reviewing a PR against harness standards.
+Run `git diff main --name-only` then read all changed files.
+
+## Checklist
+
+### Architecture
+
+- [ ] No cross-layer imports (ESLint + structural tests)
+- [ ] No file > 400 lines
+- [ ] TypeScript: 0 errors
+- [ ] api.generated.ts not manually edited
+
+### Code Quality
+
+- [ ] No console.log
+- [ ] No process.env outside env.ts
+- [ ] No direct fetch() in components/features/pages
+- [ ] No <img> tags (use next/image)
+
+### API Contract
+
+- [ ] api.generated.ts is current
+- [ ] No hand-written types duplicating api.generated.ts
+- [ ] All API calls via openapi-fetch through api-client
+- [ ] Error handling in every hook (throw on error)
+
+### Components
+
+- [ ] Loading + Error + Empty states on every data-fetching component
+- [ ] Forms use react-hook-form + zodResolver
+- [ ] 'use client' has comment explaining why
+- [ ] Interactive elements are accessible (aria-label, role, focus-visible)
+- [ ] Images use next/image with width/height or fill
+
+### Security
+
+- [ ] Access token in memory only (not localStorage)
+- [ ] No secrets in NEXT*PUBLIC*\* vars
+- [ ] No dangerouslySetInnerHTML without sanitisation
+
+### Performance
+
+- [ ] No unnecessary 'use client' (check each one)
+- [ ] Large lists use cursor pagination (not offset)
+
+### Tests
+
+- [ ] Utils: 100% coverage
+- [ ] Hooks: 80% coverage (success + error)
+- [ ] Components: 70% (render + interaction)
+- [ ] E2E: critical paths covered
+
+### Docs
+
+- [ ] ADR for non-obvious decisions
+- [ ] QUALITY_SCORE.md updated
+
+## Verdict
+
+```
+APPROVED — ready to merge.
+
+OR
+
+CHANGES REQUIRED:
+BLOCKING:
+1. [file:line] [problem] → [fix]
+
+NON-BLOCKING:
+2. [description]
+```

package/templates/nextjs/.claude/agents/security-auditor.md

@@ -0,0 +1,50 @@
+---
+name: security-auditor
+description: Security review for Next.js frontend. Run before any auth, token, or data-exposure PR.
+model: claude-opus-4-8
+tools: [Read, Bash]
+color: red
+---
+
+You are a frontend security engineer. Review all changes for auth and XSS risks.
+
+## Checklist
+
+### Auth Token Handling
+
+- [ ] Access token in React context only — NOT localStorage/sessionStorage/cookie
+- [ ] Refresh token flow goes through Next.js API route (proxies to backend)
+- [ ] No token logged in console
+- [ ] Token cleared on logout from context
+
+### Environment Variables
+
+- [ ] No secrets in `NEXT_PUBLIC_*` vars (check .env.example)
+- [ ] process.env only in src/lib/env.ts
+- [ ] Zod schema validates all `NEXT_PUBLIC_*` vars
+
+### XSS Prevention
+
+- [ ] No dangerouslySetInnerHTML without DOMPurify sanitisation
+- [ ] User-generated content rendered via JSX (auto-escaped)
+
+### CSP Headers
+
+- [ ] Content-Security-Policy header in next.config.ts
+- [ ] No 'unsafe-eval' or 'unsafe-inline' in script-src
+
+### API Client
+
+- [ ] Auth header injected via middleware — not in individual hooks
+- [ ] Error responses never expose raw backend error messages to UI
+
+### Next.js API Routes
+
+- [ ] app/api/ routes only used for cookie operations and auth proxy
+- [ ] No business logic in api/ routes
+
+## Verdict
+
+```
+APPROVED or CHANGES REQUIRED: [specific items with fixes]
+```

package/templates/nextjs/.claude/hooks/post-write.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# .claude/hooks/post-write.sh
+# Fires after every Write/Edit/MultiEdit on TypeScript/TSX files.
+#
+# Two severities:
+#   BLOCKERS (exit 2) — the agent MUST fix before continuing. These are correctness
+#     /security violations that should never land: editing the read-only generated
+#     contract, or putting an auth token in web storage.
+#   WARNINGS (exit 0) — printed for the agent to address before commit, but not fatal.
+#
+# Exit-code contract (Claude Code PostToolUse): a non-zero exit (2) with text on stderr
+# is fed back to the agent as a required fix. Exit 0 with text on stdout is advisory.
+#
+# Parses the PostToolUse hook JSON from stdin with `node` (always present in a Node
+# project) — no python3 dependency. Normalises the absolute path Claude Code sends
+# (incl. Windows backslashes) to a repo-relative, forward-slash path so the layer
+# checks below actually match.
+
+set -euo pipefail
+
+RAW=$(cat)
+
+# Extract the written file path. Claude Code puts it at tool_input.file_path;
+# fall back to other shapes defensively.
+FILE=$(printf '%s' "$RAW" | node -e "
+let d='';
+process.stdin.on('data', c => d += c).on('end', () => {
+  try {
+    const j = JSON.parse(d);
+    const p = (j.tool_input && j.tool_input.file_path)
+      || (j.tool_response && j.tool_response.filePath)
+      || j.file_path || j.path || '';
+    process.stdout.write(p || '');
+  } catch { process.stdout.write(''); }
+});
+" 2>/dev/null || echo "")
+
+[[ -z "$FILE" ]] && exit 0
+[[ ! -f "$FILE" ]] && exit 0
+[[ ! "$FILE" =~ \.(ts|tsx)$ ]] && exit 0
+
+# Normalise backslashes → forward slashes for portable matching.
+NORM="${FILE//\\//}"
+
+WARNINGS=()
+BLOCKERS=()
+
+# ── BLOCKER 1: api.generated.ts is READ ONLY ───────────────────────────────
+# Editing the generated contract by hand breaks the single source of truth.
+if [[ "$NORM" =~ api\.generated\.ts$ ]]; then
+  BLOCKERS+=("🚫 [HOOK] $NORM is READ ONLY — it is regenerated by /api-sync. Revert this edit and run /api-sync against openapi.json instead.")
+fi
+
+# ── BLOCKER 2: auth tokens must never touch web storage ────────────────────
+# Broadened from the old "token must be literally inside setItem(...)" grep so
+# `localStorage.setItem('auth', accessToken)` (key does not contain "token") is
+# caught too. Matches any setItem whose call references an auth-ish identifier.
+if grep -qniE "(local|session)Storage\.setItem\([^)]*(token|jwt|auth|bearer|access|refresh|secret|credential)" "$FILE" 2>/dev/null; then
+  LINE=$(grep -niE "(local|session)Storage\.setItem" "$FILE" | head -1 | cut -d: -f1)
+  BLOCKERS+=("🚫 [HOOK] Token/credential written to web storage at $NORM:$LINE — access tokens must stay in memory (React context). Revert.")
+fi
+
+# ── WARNING 1: console.log in src/ or app/ (no structured console logging) ──
+# Use the structured logger (src/lib/logger.ts) instead; raw console.log is noise.
+if [[ "$NORM" =~ (^|/)src/ ]] || [[ "$NORM" =~ (^|/)app/ ]]; then
+  if grep -qn "console\.log\b" "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "console\.log\b" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] console.log at $NORM:$LINE — use the structured logger from src/lib/logger.ts (or remove before committing)")
+  fi
+fi
+
+# ── WARNING 2: process.env outside src/lib/ (env.ts validates NEXT_PUBLIC_*) ──
+# NODE_ENV / NEXT_RUNTIME are build-time constants Next inlines — not flagged.
+# src/lib/ is the infra boundary (env.ts, logger.ts) and may read them.
+if [[ "$NORM" =~ (^|/)src/ ]] && [[ ! "$NORM" =~ (^|/)src/lib/ ]]; then
+  if grep -nE "process\.env" "$FILE" 2>/dev/null | grep -vqE "process\.env\.(NODE_ENV|NEXT_RUNTIME)\b"; then
+    LINE=$(grep -nE "process\.env" "$FILE" | grep -vE "process\.env\.(NODE_ENV|NEXT_RUNTIME)\b" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] process.env at $NORM:$LINE — use env from src/lib/env.ts")
+  fi
+fi
+
+# ── WARNING 3: direct fetch() in components, features, or pages ─────────────
+# Anchored so it does NOT false-positive on TanStack's refetch()/prefetchQuery()
+# (fetch preceded by a letter or a dot is someone else's method, not a bare fetch).
+if [[ "$NORM" =~ (^|/)(src/features|src/components|app)/ ]]; then
+  if grep -qnE "(^|[^A-Za-z.])fetch\(" "$FILE" 2>/dev/null; then
+    LINE=$(grep -nE "(^|[^A-Za-z.])fetch\(" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] Direct fetch() at $NORM:$LINE — API calls must go through src/hooks/")
+  fi
+fi
+
+# ── WARNING 4: raw <img> tag (should use next/image) ───────────────────────
+if [[ "$NORM" =~ \.tsx$ ]]; then
+  if grep -qn "<img " "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "<img " "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] <img> at $NORM:$LINE — use next/image <Image /> component")
+  fi
+fi
+
+# ── WARNING 5: file size > 400 lines ───────────────────────────────────────
+LINE_COUNT=$(wc -l < "$FILE" 2>/dev/null || echo 0)
+if [[ "$LINE_COUNT" -gt 400 ]]; then
+  WARNINGS+=("⚠ [HOOK] $NORM has $LINE_COUNT lines — exceeds 400-line limit. Split into focused modules.")
+fi
+
+# Print advisory warnings to stdout (guard empty array for bash 3.2 / set -u).
+if [[ ${#WARNINGS[@]} -gt 0 ]]; then
+  for w in "${WARNINGS[@]}"; do
+    echo "$w"
+  done
+fi
+
+# Blockers go to stderr and fail the hook so the agent must address them.
+if [[ ${#BLOCKERS[@]} -gt 0 ]]; then
+  for b in "${BLOCKERS[@]}"; do
+    echo "$b" >&2
+  done
+  exit 2
+fi
+
+exit 0

package/templates/nextjs/.claude/rules/api-contract.md

@@ -0,0 +1,166 @@
+---
+paths:
+  - "src/hooks/**/*.ts"
+  - "src/hooks/**/*.tsx"
+  - "src/lib/api-client.ts"
+---
+
+# API Contract Rules — Auto-injected on hook and api-client edits
+
+## The Golden Rule
+`api.generated.ts` is the contract. Every API call must flow through it.
+
+## Canonical Wire Contract (cross-stack — FastAPI · Express · NestJS)
+
+This frontend talks to any of the harness backends. They MUST agree on ONE wire shape
+so the client never special-cases a backend. The agreed conventions:
+
+- **Field naming: `snake_case`** on the wire (`next_cursor_id`, `has_more`, `created_at`).
+  FastAPI/Pydantic emits this by default. Express/NestJS + Sequelize must emit it too
+  (Sequelize `underscored: true`, or a response serializer) — do NOT ship camelCase.
+- **List envelope (cursor pagination):**
+  `{ "items": T[], "has_more": boolean, "next_cursor_id": string | null }`
+  Request params: `cursor_id` (opaque), `limit` (int).
+- **Error envelope (every non-2xx):**
+  `{ "error": { "code": "SNAKE_CASE_CODE", "message": "human readable", "details"?: object } }`
+  (Not FastAPI's bare `{ "detail": ... }` — backends register a handler that emits this.)
+
+**How this is enforced mechanically (not just prose):** the field names you write in
+hooks are checked against `api.generated.ts` by `tsc`. If a backend deviates (e.g. emits
+`nextCursorId`), `/api-sync` regenerates camelCase types and `npm run typecheck` FAILS on
+`lastPage.next_cursor_id` — the drift cannot pass the gate silently. Agreement across
+templates + typecheck is the guard; keep the convention above in lock-step with the
+Express/NestJS/FastAPI templates.
+
+## Hook Pattern — Every Hook Must Follow This
+
+```typescript
+// src/hooks/use-applications.ts
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { apiClient } from '@/lib/api-client'
+import { toApiError } from '@/lib/api-error'
+import type { components } from '@/types/api.generated'
+
+type Application = components['schemas']['ApplicationResponse']
+type CreateApplicationInput = components['schemas']['CreateApplicationInput']
+
+// ─── Query Keys ─────────────────────────────────────────
+// Centralise all query keys — never use raw strings in components
+export const applicationKeys = {
+  all:    () => ['applications'] as const,
+  lists:  () => [...applicationKeys.all(), 'list'] as const,
+  list:   (filters: Record<string, unknown>) =>
+            [...applicationKeys.lists(), filters] as const,
+  detail: (id: string) => [...applicationKeys.all(), 'detail', id] as const,
+}
+
+// ─── List ────────────────────────────────────────────────
+export function useApplications(filters?: { stage?: string; limit?: number }) {
+  return useQuery({
+    queryKey: applicationKeys.list(filters ?? {}),
+    queryFn: async () => {
+      const { data, error } = await apiClient.GET('/api/v1/applications', {
+        params: { query: filters },
+      })
+      if (error) throw toApiError(error, 'Failed to fetch applications')
+      return data
+    },
+    staleTime: 60_000,  // 1 min — server data doesn't change every second
+  })
+}
+
+// ─── Single ──────────────────────────────────────────────
+export function useApplication(id: string) {
+  return useQuery({
+    queryKey: applicationKeys.detail(id),
+    queryFn: async () => {
+      const { data, error } = await apiClient.GET('/api/v1/applications/{id}', {
+        params: { path: { id } },
+      })
+      if (error) throw toApiError(error, `Application ${id} not found`)
+      return data
+    },
+    enabled: !!id,  // don't fetch if no id
+  })
+}
+
+// ─── Mutation ────────────────────────────────────────────
+export function useCreateApplication() {
+  const queryClient = useQueryClient()
+  return useMutation({
+    mutationFn: async (body: CreateApplicationInput) => {
+      const { data, error } = await apiClient.POST('/api/v1/applications', { body })
+      if (error) throw toApiError(error, 'Failed to create application')
+      return data
+    },
+    onSuccess: () => {
+      // Invalidate all application lists — triggers refetch
+      queryClient.invalidateQueries({ queryKey: applicationKeys.lists() })
+    },
+  })
+}
+```
+
+## Error Handling in Hooks
+
+Preserve the backend error — do NOT replace it with a hard-coded English string (that
+throws away the `code`/`message` the canonical error envelope carries). Use a shared
+helper that reads the envelope defensively:
+
+```typescript
+// src/lib/api-error.ts  (authored in Phase 0 glue)
+export class ApiError extends Error {
+  constructor(public code: string, message: string, public details?: unknown) {
+    super(message)
+  }
+}
+// Reads the canonical { error: { code, message } } envelope; falls back gracefully
+// for a bare FastAPI { detail } or an opaque error so a message ALWAYS surfaces.
+export function toApiError(error: unknown, fallback = 'Request failed'): ApiError {
+  const e = error as { error?: { code?: string; message?: string; details?: unknown }; detail?: unknown }
+  if (e?.error?.message) return new ApiError(e.error.code ?? 'unknown', e.error.message, e.error.details)
+  if (typeof e?.detail === 'string') return new ApiError('unknown', e.detail)
+  return new ApiError('unknown', fallback)
+}
+```
+
+```typescript
+// ✅ Throw the real error — code + message reach the UI
+if (error) throw toApiError(error, 'Failed to fetch applications')
+
+// ✅ Handle in component via isError + error (error.message is the backend message)
+const { isError, error } = useApplications()
+if (isError) return <ErrorState message={error.message} />
+
+// ❌ Never swallow errors
+const { data } = await apiClient.GET(...)
+// missing: if (error) throw ...
+
+// ❌ Never discard the backend error for a hard-coded string
+if (error) throw new Error('Failed to fetch applications')  // loses code + real message
+```
+
+## staleTime Guidance
+```typescript
+// User-specific, changes often: staleTime: 30_000     (30s)
+// Reference data, rarely changes: staleTime: 300_000   (5min)
+// Static config: staleTime: Infinity
+```
+
+## Pagination with Cursor
+```typescript
+export function useApplications(cursor?: string) {
+  return useInfiniteQuery({
+    queryKey: applicationKeys.list({ cursor }),
+    queryFn: async ({ pageParam }) => {
+      const { data, error } = await apiClient.GET('/api/v1/applications', {
+        params: { query: { cursor_id: pageParam, limit: 20 } },
+      })
+      if (error) throw error
+      return data
+    },
+    getNextPageParam: (lastPage) => lastPage.next_cursor_id ?? undefined,
+    initialPageParam: undefined,
+  })
+}
+```

package/templates/nextjs/.claude/rules/architecture.md

@@ -0,0 +1,99 @@
+---
+paths:
+  - "src/**/*.ts"
+  - "src/**/*.tsx"
+  - "app/**/*.tsx"
+  - "app/**/*.ts"
+---
+
+# Architecture Rules — Auto-injected on every src/ and app/ file edit
+
+## Import Order Check — Before Writing Any Import
+
+| Your file is in | You may import from |
+|---|---|
+| `src/types/` | Nothing (third-party ok: zod) |
+| `src/lib/` | `src/types/` only |
+| `src/hooks/` | `src/types/`, `src/lib/` |
+| `src/store/` | `src/types/` only |
+| `src/utils/` | Nothing (stdlib + third-party only) |
+| `src/components/` | `src/types/`, `src/utils/` |
+| `src/features/` | `src/types/`, `src/lib/`, `src/hooks/`, `src/store/`, `src/components/`, `src/utils/` |
+| `app/` | `src/features/`, `src/components/` |
+
+## api.generated.ts — THE CONTRACT
+```typescript
+// ✅ Import types FROM the generated file
+import type { components, paths } from '@/types/api.generated'
+type Application = components['schemas']['ApplicationResponse']
+
+// ❌ NEVER manually write a type that mirrors the generated one
+type Application = {   // if this matches api.generated.ts → DELETE IT
+  id: string
+  stage: string
+  ...
+}
+
+// ❌ NEVER edit api.generated.ts
+// Run /api-sync to regenerate it
+```
+
+## API Calls — Hooks Only
+```typescript
+// ✅ Feature uses a hook
+import { useApplications } from '@/hooks/use-applications'
+
+function ApplicationList() {
+  const { data, isPending, error } = useApplications()
+  if (isPending) return <Skeleton />
+  if (error) return <ErrorState />
+  return data?.items.map(app => <ApplicationCard key={app.id} app={app} />)
+}
+
+// ❌ Direct fetch in component — FORBIDDEN
+function ApplicationList() {
+  useEffect(() => {
+    fetch('/api/v1/applications')  // WRONG
+  }, [])
+}
+```
+
+## Server vs Client Components
+```typescript
+// ✅ Server Component — default, no directive
+export default async function ApplicationsPage() {
+  return (
+    <div>
+      <ApplicationListClient />  {/* client boundary inside */}
+    </div>
+  )
+}
+
+// ✅ Client Component — with reason comment
+'use client'  // Client: uses TanStack Query (useQuery)
+export function ApplicationListClient() {
+  const { data } = useApplications()
+  ...
+}
+
+// ❌ 'use client' without comment
+'use client'
+export function SomeComponent() { ... }  // Why? What browser API?
+```
+
+## No Business Logic in App Pages
+```typescript
+// ✅ Page = layout + render feature
+export default function ApplicationsPage() {
+  return <ApplicationsFeature />
+}
+
+// ❌ Business logic in page — belongs in features/
+export default function ApplicationsPage() {
+  const [filtered, setFiltered] = useState([])
+  const handleStageChange = async (id, stage) => {   // WRONG LAYER
+    await fetch(`/api/v1/applications/${id}/stage`)
+    ...
+  }
+}
+```

package/templates/nextjs/.claude/rules/components.md

@@ -0,0 +1,122 @@
+---
+paths:
+  - "src/features/**/*.tsx"
+  - "src/components/**/*.tsx"
+  - "app/**/*.tsx"
+---
+
+# Component Rules — Auto-injected on component file edits
+
+## Every Component Checklist
+
+### Loading, Error, and Empty States (ALL THREE required on data-fetching components)
+```typescript
+// ✅ All 3 states handled
+export function ApplicationList() {
+  const { data, isPending, isError, error } = useApplications()
+
+  if (isPending) return <ApplicationListSkeleton />   // skeleton > spinner
+  if (isError)   return <ErrorState message={error.message} retry={refetch} />
+  if (!data?.items.length) return <EmptyState />
+
+  return data.items.map(app => <ApplicationCard key={app.id} app={app} />)
+}
+
+// ❌ Missing states — silent failure
+export function ApplicationList() {
+  const { data } = useApplications()
+  return data?.items.map(app => <ApplicationCard key={app.id} app={app} />)
+  // undefined if loading? Error? No items? All render nothing silently.
+}
+```
+
+### Forms — React Hook Form + Zod + shadcn/ui
+```typescript
+import { useForm } from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { z } from 'zod'
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form'
+
+const createApplicationSchema = z.object({
+  company: z.string().min(1, 'Company is required'),
+  role:    z.string().min(1, 'Role is required'),
+  jobUrl:  z.string().url().optional(),
+})
+type CreateApplicationInput = z.infer<typeof createApplicationSchema>
+
+export function CreateApplicationForm({ onSuccess }: { onSuccess: () => void }) {
+  const form = useForm<CreateApplicationInput>({
+    resolver: zodResolver(createApplicationSchema),
+    defaultValues: { company: '', role: '' },
+  })
+  const { mutate, isPending } = useCreateApplication()
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(data => mutate(data, { onSuccess }))}>
+        <FormField control={form.control} name="company" render={({ field }) => (
+          <FormItem>
+            <FormLabel>Company</FormLabel>
+            <FormControl><Input {...field} /></FormControl>
+            <FormMessage />
+          </FormItem>
+        )} />
+        <Button type="submit" disabled={isPending}>
+          {isPending ? 'Creating...' : 'Create'}
+        </Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+### Images — Always next/image
+```typescript
+// ✅
+import Image from 'next/image'
+<Image src="/logo.png" alt="Logo" width={120} height={40} />
+
+// ❌ Flagged by post-write hook + ESLint (next/core-web-vitals no-img-element)
+<img src="/logo.png" alt="Logo" />
+```
+
+### Accessibility (every interactive element)
+```typescript
+// ✅
+<button
+  aria-label="Delete application"
+  onClick={handleDelete}
+  className="focus-visible:ring-2 focus-visible:ring-ring"
+>
+  <TrashIcon aria-hidden />
+</button>
+
+// ❌
+<div onClick={handleDelete}>  {/* not focusable, no role */}
+  <TrashIcon />
+</div>
+```
+
+### Tailwind + shadcn/ui — Use cn() for conditional classes
+```typescript
+import { cn } from '@/utils/cn.util'
+
+<div className={cn(
+  'rounded-lg border p-4',
+  isPending && 'opacity-50 pointer-events-none',
+  isError && 'border-destructive',
+)}>
+```
+
+### No Inline Event Handlers with Business Logic
+```typescript
+// ✅ Handler defined, logic delegated to mutation
+const { mutate: deleteApp } = useDeleteApplication()
+<Button onClick={() => deleteApp(app.id)}>Delete</Button>
+
+// ❌ Inline logic
+<Button onClick={async () => {
+  await fetch(`/api/v1/applications/${app.id}`, { method: 'DELETE' })
+  router.refresh()
+}}>Delete</Button>
+```