create-rigel 0.1.0

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

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# .claude/hooks/post-write.sh
+# Fires after every Write/Edit on Python files.
+# Warns on: print(), os.environ, 400-line limit, raw dict cast on DB results.
+
+set -euo pipefail
+
+FILE=$(cat | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('file_path') or data.get('path') or '')
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+[[ -z "$FILE" ]] && exit 0
+[[ ! -f "$FILE" ]] && exit 0
+[[ ! "$FILE" =~ \.py$ ]] && exit 0
+
+WARNINGS=()
+
+# 1. print() in src/ — use structlog logger
+if [[ "$FILE" =~ ^src/ ]] && [[ ! "$FILE" =~ src/providers/logger ]] && [[ ! "$FILE" =~ src/config/ ]]; then
+  if grep -qn "^\s*print(" "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "^\s*print(" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] print() at $FILE:$LINE — use logger from src/providers/logger.py")
+  fi
+fi
+
+# 2. os.environ outside config/settings.py
+if [[ "$FILE" =~ ^src/ ]] && [[ ! "$FILE" =~ src/config/settings\.py ]]; then
+  if grep -qn "os\.environ" "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "os\.environ" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] os.environ at $FILE:$LINE — use settings from src/config/settings.py")
+  fi
+fi
+
+# 3. File size > 400 lines
+LINE_COUNT=$(wc -l < "$FILE" 2>/dev/null || echo 0)
+if [[ $LINE_COUNT -gt 400 ]]; then
+  WARNINGS+=("⚠ [HOOK] $FILE has $LINE_COUNT lines — exceeds 400-line limit. Split into focused modules.")
+fi
+
+# 4. Unsafe DB result cast in repo files
+if [[ "$FILE" =~ _repo\.py$ ]]; then
+  if grep -qn "return row\.__dict__\b\|return dict(row" "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "return row\.__dict__\|return dict(row" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] Unsafe cast at $FILE:$LINE — use Schema.model_validate(row.__dict__)")
+  fi
+fi
+
+# 5. HTTPException in service files
+if [[ "$FILE" =~ _service\.py$ ]]; then
+  if grep -qn "HTTPException\|raise HTTPException" "$FILE" 2>/dev/null; then
+    LINE=$(grep -n "HTTPException" "$FILE" | head -1 | cut -d: -f1)
+    WARNINGS+=("⚠ [HOOK] HTTPException at $FILE:$LINE — services must raise DomainError, not HTTPException")
+  fi
+fi
+
+for w in "${WARNINGS[@]}"; do
+  echo "$w"
+done
+
+exit 0

package/templates/fastapi/.claude/rules/api.md

@@ -0,0 +1,119 @@
+---
+paths:
+  - "src/runtime/routers/**/*.py"
+---
+
+# API Rules — Auto-injected on router file edits
+
+## Every Route File Checklist
+
+### Versioning
+```python
+# ✅ All routers under version prefix
+router = APIRouter(prefix="/applications", tags=["applications"])
+# Mounted in main.py at: app.include_router(router, prefix="/api/v1")
+
+# ❌ Never create unversioned routes
+app.include_router(router)   # no version prefix
+```
+
+### Required Handler Structure
+```python
+@router.post("/", status_code=status.HTTP_201_CREATED)
+async def create_application(
+    body: CreateApplicationInput,                       # 1. Pydantic validates body
+    auth: AuthContext = Depends(require_auth),          # 2. Auth
+    session: AsyncSession = Depends(get_session),      # 3. DB session
+    _: None = Depends(user_rate_limit),                # 4. Rate limit
+) -> ApplicationResponse:                              # 5. Typed return
+    result = await application_service.create(session, auth.user_id, body)
+    return result                                      # 6. FastAPI serialises
+# Errors → global exception handlers → no try/except here
+```
+
+### Rate Limit Tiers
+```python
+# In src/providers/rate_limit.py — three tiers:
+auth_rate_limit  = Depends(...)   # 10/min — login, register, reset
+public_rate_limit = Depends(...)  # 60/min — unauthenticated reads
+user_rate_limit  = Depends(...)   # 300/min — authenticated endpoints
+
+# Apply at router level for all routes in a router:
+router = APIRouter(dependencies=[Depends(user_rate_limit)])
+```
+
+### Response Envelope — Always
+```python
+# ✅ Wrap all responses in SuccessEnvelope
+from src.runtime.response_util import ok   # builders live in runtime (utils may not import types)
+from src.types.common import SuccessEnvelope
+
+@router.get("/{app_id}")
+async def get_application(
+    app_id: UUID,
+    request: Request,  # for request_id
+    auth: AuthContext = Depends(require_auth),
+    session: AsyncSession = Depends(get_session),
+) -> SuccessEnvelope[ApplicationResponse]:
+    result = await application_service.get(session, auth.user_id, app_id)
+    return ok(result, request.state.request_id)
+# Response: { "ok": true, "data": {...}, "meta": { "request_id": "...", "timestamp": "..." } }
+
+# ✅ For lists — use PageResult wrapped in envelope
+@router.get("/")
+async def list_applications(
+    request: Request,
+    ...
+) -> SuccessEnvelope[PageResult[ApplicationResponse]]:
+    result = await application_service.list(session, auth.user_id, cursor, limit)
+    return ok(result, request.state.request_id)
+# Response: { "ok": true, "data": { "items": [...], "next_cursor": "...", "has_more": true }, "meta": {...} }
+
+# ❌ Never return bare Pydantic models
+@router.get("/{app_id}")
+async def get_application(...) -> ApplicationResponse:  # FORBIDDEN
+    return await application_service.get(...)  # missing envelope
+```
+
+**Error envelope** (handled by global exception handler):
+```python
+# Errors automatically wrapped by exception_handlers.py:
+# { "ok": false, "error": { "code": "NOT_FOUND", "message": "..." }, "meta": {...} }
+```
+
+### Pagination Query Params — Opaque Cursor
+```python
+from src.utils.cursor_util import decode_cursor, encode_cursor
+
+@router.get("/")
+async def list_applications(
+    cursor: str | None = Query(None),  # opaque base64url-encoded cursor
+    limit: int = Query(default=20, ge=1, le=100),
+    auth: AuthContext = Depends(require_auth),
+    session: AsyncSession = Depends(get_session),
+) -> SuccessEnvelope[PageResult[ApplicationResponse]]:
+    decoded_cursor = decode_cursor(cursor) if cursor else None
+    # decoded_cursor = {"id": uuid, "created_at": iso_str} or None
+    result = await application_service.list(session, auth.user_id, decoded_cursor, limit)
+    return ok(result, request.state.request_id)
+
+# ❌ Never expose dual cursor params (leaks implementation details)
+@router.get("/")
+async def list_applications(
+    cursor_id: UUID | None = Query(None),           # FORBIDDEN
+    cursor_created_at: datetime | None = Query(None),  # FORBIDDEN
+    ...
+```
+
+**Cursor encoding** (in service layer):
+```python
+# Service returns PageResult with next_cursor as opaque string
+from src.utils.cursor_util import encode_cursor
+
+next_cursor = encode_cursor({"id": str(last_item.id), "created_at": last_item.created_at.isoformat()})
+return PageResult(items=items, next_cursor=next_cursor, has_more=has_more)
+```
+
+### Security Headers
+Applied globally in `main.py` via middleware — never per-route.
+Verify `SecurityHeadersMiddleware` is in the middleware stack.

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

@@ -0,0 +1,84 @@
+---
+paths:
+  - "src/**/*.py"
+---
+
+# Architecture Rules — Auto-injected on every src/ file edit
+
+## Import Order Enforcement
+
+Before writing any import, check which layer you are in:
+
+| Your file is in | You may import from |
+|---|---|
+| `src/types/` | Nothing (third-party ok: pydantic, enum) |
+| `src/config/` | `src/types/` only |
+| `src/models/` | `src/types/`, `src/config/` |
+| `src/repo/` | `src/types/`, `src/config/`, `src/models/` |
+| `src/services/` | `src/types/`, `src/config/`, `src/repo/` |
+| `src/runtime/` | `src/types/`, `src/config/`, `src/repo/`, `src/services/` |
+| `src/utils/` | Nothing (stdlib + third-party only) |
+| `src/providers/` | `src/types/`, `src/config/` only |
+
+## Correct Patterns Per Layer
+
+### Types (`src/types/`)
+```python
+# ✅ Pure Pydantic schema — no imports from other layers
+from pydantic import BaseModel
+from enum import Enum
+
+class ApplicationStage(str, Enum):
+    SAVED = "SAVED"
+    APPLIED = "APPLIED"
+
+class ApplicationResponse(BaseModel):
+    id: str
+    stage: ApplicationStage
+
+# ❌ Wrong
+from src.config.settings import settings   # FORBIDDEN in types
+```
+
+### Service (`src/services/`)
+```python
+# ✅ Takes typed inputs, returns typed outputs, raises DomainError
+async def create_application(
+    session: AsyncSession,
+    user_id: str,
+    data: CreateApplicationInput,
+) -> ApplicationResponse:
+    ...
+    raise ApplicationNotFoundError("...")   # Domain error — ok
+
+# ❌ Wrong
+from fastapi import HTTPException           # FORBIDDEN in service
+raise HTTPException(status_code=404)        # FORBIDDEN — only in runtime
+```
+
+### Runtime (`src/runtime/`)
+```python
+# ✅ Correct handler structure — THIS ORDER always
+@router.post("/applications", status_code=201)
+async def create_application(
+    body: CreateApplicationInput,                    # 1. Pydantic validates
+    auth: AuthContext = Depends(require_auth),       # 2. Auth
+    session: AsyncSession = Depends(get_session),   # 3. DB session
+) -> ApplicationResponse:
+    return await application_service.create(session, auth.user_id, body)
+    # error mapping handled by global exception handlers — not here
+
+# ❌ Wrong — business logic in handler
+@router.post("/applications")
+async def create(body: dict, ...):    # untyped body
+    if body["stage"] == "APPLIED":   # logic in handler
+```
+
+## ruff Configuration
+`ruff.toml` enforces:
+- `no-print` (T20) — use structlog
+- Import order (I) — enforced automatically
+- No unused imports (F401)
+- Type annotations required (ANN)
+
+Run anytime: `uv run ruff check src/`

package/templates/fastapi/.claude/rules/database.md

@@ -0,0 +1,153 @@
+---
+paths:
+  - "src/repo/**/*.py"
+  - "src/models/**/*.py"
+  - "alembic/versions/**/*.py"
+---
+
+# Database Rules — Auto-injected on repo/model/migration edits
+
+## The 5 Checks Before Every Repo Method Ships
+
+### 1. Pydantic Validation on Every Result
+```python
+# ✅ REQUIRED
+row = result.scalar_one_or_none()
+if not row:
+    raise ApplicationNotFoundError(...)
+return ApplicationResponse.model_validate(row.__dict__)
+
+# ❌ FORBIDDEN
+return row.__dict__          # raw, unvalidated
+return dict(row.__dict__)    # cast, not validated
+return row                   # ORM object leaking out of repo
+```
+
+### 2. No N+1 — Eager Load Always
+```python
+# ✅ selectinload for related collections
+stmt = (
+    select(Application)
+    .where(Application.user_id == user_id)
+    .options(
+        selectinload(Application.notes),
+        selectinload(Application.contacts),
+    )
+)
+
+# ❌ N+1 — async loop over lazy loads
+apps = (await session.execute(select(Application))).scalars().all()
+for app in apps:
+    notes = await session.execute(select(Note).where(Note.application_id == app.id))
+```
+
+### 3. Cursor Pagination on All List Methods
+
+`PageResult` has ONE shape across the whole stack — `{ items, next_cursor, has_more }` where
+`next_cursor` is the OPAQUE base64url token produced by `encode_cursor`. The repo decodes the
+incoming token, keyset-paginates, and re-encodes the last row. Never expose `created_at`/`id`
+cursor fields on the API or in `PageResult` (see `.claude/rules/api.md`).
+
+**The cursor is adversarial input.** `decode_cursor` MUST catch malformed values
+(`binascii.Error`, `json.JSONDecodeError`, `ValueError`, `UnicodeDecodeError`) and raise
+`InvalidCursorError` (mapped to **400**). A raw `decode_cursor("null")` otherwise throws an
+unhandled exception → **500**. (Found by schemathesis fuzzing `?cursor=null`.)
+
+```python
+# ✅ Cursor-based — opaque token in, opaque token out
+from src.utils.cursor_util import decode_cursor, encode_cursor
+
+async def list_applications(
+    session: AsyncSession,
+    user_id: UUID,
+    cursor: str | None = None,   # opaque base64url token (or None for first page)
+    limit: int = 20,
+) -> PageResult[ApplicationResponse]:
+    stmt = select(Application).where(Application.user_id == user_id, Application.deleted_at.is_(None))
+
+    decoded = decode_cursor(cursor) if cursor else None   # {"created_at": iso_str, "id": uuid} | None
+    if decoded:
+        cursor_created_at = datetime.fromisoformat(decoded["created_at"])
+        cursor_id = UUID(decoded["id"])
+        stmt = stmt.where(
+            or_(
+                Application.created_at < cursor_created_at,
+                and_(Application.created_at == cursor_created_at, Application.id < cursor_id),
+            )
+        )
+
+    stmt = stmt.order_by(Application.created_at.desc(), Application.id.desc()).limit(limit + 1)
+    rows = (await session.execute(stmt)).scalars().all()
+
+    has_more = len(rows) > limit
+    items = rows[:limit]
+    next_cursor = (
+        encode_cursor({"created_at": items[-1].created_at.isoformat(), "id": str(items[-1].id)})
+        if has_more and items
+        else None
+    )
+    return PageResult(
+        items=[ApplicationResponse.model_validate(r.__dict__) for r in items],
+        next_cursor=next_cursor,   # single opaque token — matches api.md + frontend contract
+        has_more=has_more,
+    )
+
+# ❌ FORBIDDEN — offset on large tables
+stmt = select(Application).offset(page * limit).limit(limit)
+
+# ❌ FORBIDDEN — leaking dual cursor fields (next_cursor_created_at / next_cursor_id)
+```
+
+### 4. Transactions for Multi-Table Writes
+
+Atomicity is orchestrated by the SERVICE, but every `session.add` / ORM construction stays
+inside a repo method. The repo is the ONLY layer that touches ORM models — services never
+import `src/models` (see `ARCHITECTURE.md` import rules).
+
+```python
+# ✅ Service opens ONE transaction; repos do the ORM writes
+# in application_service.create():
+async with session.begin():
+    app = await application_repo.create(session, user_id, data)
+    await note_repo.create(session, app.id, content="Created", type="SYSTEM")
+# commits on context exit, rolls back on exception
+
+# ✅ Inside application_repo.create() — the repo owns ORM construction + validation:
+async def create(session, user_id, data) -> ApplicationResponse:
+    row = Application(user_id=user_id, **data.model_dump())
+    session.add(row)
+    await session.flush()
+    return ApplicationResponse.model_validate(row.__dict__)
+
+# ❌ Never construct ORM models or call session.add() in a service — that is the repo's job
+# ❌ Never call external APIs inside a transaction block
+```
+
+### 5. Soft Delete Pattern
+```python
+# ✅ Model has deleted_at — filter in every query
+stmt = select(Application).where(
+    Application.user_id == user_id,
+    Application.deleted_at.is_(None)    # always include this
+)
+
+# ✅ Soft delete (timezone-aware — datetime.utcnow() is deprecated in 3.12+)
+row.deleted_at = datetime.now(UTC)   # from datetime import UTC — ruff UP017 prefers UTC over timezone.utc
+await session.flush()
+
+# ❌ Hard delete — only for GDPR with explicit comment
+await session.delete(row)  # only if legally required
+```
+
+## Model Checklist (every new model)
+- [ ] `deleted_at: Mapped[datetime | None]` — soft delete
+- [ ] `id: Mapped[UUID]` with `default=uuid7` — time-ordered UUID
+- [ ] `__table_args__` with indexes on FK + ORDER BY columns
+- [ ] Partial index for `WHERE deleted_at IS NULL` queries
+- [ ] `created_at`, `updated_at` with server defaults
+
+## Migration Checklist (every new migration)
+- [ ] Run `alembic revision --autogenerate -m "description"` then review output
+- [ ] New indexes use `postgresql_concurrently=True`
+- [ ] Both `upgrade()` and `downgrade()` implemented
+- [ ] Run `alembic upgrade head` to verify

package/templates/fastapi/.claude/rules/jobs.md

@@ -0,0 +1,85 @@
+---
+paths:
+  - "src/runtime/workers/**/*.py"
+  - "src/workers/**/*.py"
+---
+
+# Job Rules — Auto-injected on worker file edits
+
+## Every Celery Task Checklist
+
+### 1. Validate payload with Pydantic before touching it
+```python
+@celery_app.task(
+    name="reminder.send_email",
+    bind=True,
+    max_retries=3,
+    default_retry_delay=60,
+    queue="reminder-email",
+)
+def send_reminder_email_task(self: Task, payload: dict) -> None:
+    # ✅ REQUIRED — validate before processing
+    data = ReminderEmailPayload.model_validate(payload)
+
+    # ❌ FORBIDDEN — trusting raw task payload
+    reminder_id = payload["reminder_id"]   # no validation
+```
+
+### 2. Structured logging — start, complete, failed
+```python
+def send_reminder_email_task(self: Task, payload: dict) -> None:
+    data = ReminderEmailPayload.model_validate(payload)
+    start = time.time()
+
+    logger.info("job.start", task=self.name, task_id=self.request.id)
+
+    try:
+        reminder_service.send_email(data)
+        logger.info(
+            "job.complete",
+            task=self.name,
+            task_id=self.request.id,
+            duration_ms=int((time.time() - start) * 1000),
+        )
+    except Exception as exc:
+        logger.error("job.failed", task=self.name, err=str(exc))
+        raise self.retry(exc=exc, countdown=2 ** self.request.retries * 30)
+```
+
+### 3. Retry with exponential backoff
+```python
+@celery_app.task(
+    bind=True,
+    max_retries=3,
+    acks_late=True,              # ack after success, not on receipt
+    reject_on_worker_lost=True,  # re-queue if worker dies mid-task
+)
+def my_task(self, payload: dict) -> None:
+    ...
+    except SomeTransientError as exc:
+        raise self.retry(exc=exc, countdown=2 ** self.request.retries * 30)
+```
+
+### 4. External calls use tenacity retry + timeout
+```python
+from tenacity import retry, stop_after_attempt, wait_exponential
+import httpx
+
+@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10))
+async def call_email_provider(data: EmailPayload) -> None:
+    async with httpx.AsyncClient(timeout=10.0) as client:
+        response = await client.post(EMAIL_API_URL, json=data.model_dump())
+        response.raise_for_status()
+```
+
+### 5. Never create DB sessions inside a task directly
+```python
+# ✅ Use the service layer which manages its own session
+def send_reminder_email_task(self, payload: dict) -> None:
+    data = ReminderEmailPayload.model_validate(payload)
+    # Service opens its own session internally
+    asyncio.run(reminder_service.process(data))
+
+# ❌ Never
+async with AsyncSessionLocal() as session:   # not thread-safe in Celery workers
+```

package/templates/fastapi/.claude/rules/security.md

@@ -0,0 +1,102 @@
+---
+paths:
+  - "src/runtime/**/*.py"
+  - "src/repo/**/*.py"
+---
+
+# Security Rules — Auto-injected on runtime and repo file edits
+
+## Runtime: Every Protected Route Requires This Structure
+
+```python
+@router.get("/{app_id}")
+async def get_application(
+    app_id: UUID,
+    auth: AuthContext = Depends(require_auth),        # 1. Auth FIRST
+    session: AsyncSession = Depends(get_session),     # 2. DB session
+    _: None = Depends(user_rate_limit),               # 3. Rate limit
+) -> ApplicationResponse:
+    # 4. Service call with domain types only
+    return await application_service.get(session, auth.user_id, app_id)
+    # 5. Errors handled by global exception handlers — not here
+```
+
+## Repo: Validation at Every Boundary
+
+```python
+# ✅ REQUIRED — validate every DB result
+async def find_by_id(session: AsyncSession, app_id: UUID, user_id: UUID) -> ApplicationResponse:
+    result = await session.execute(
+        select(Application).where(
+            Application.id == app_id,
+            Application.user_id == user_id,   # ownership enforced HERE
+            Application.deleted_at.is_(None)
+        )
+    )
+    row = result.scalar_one_or_none()
+    if not row:
+        raise ApplicationNotFoundError(f"Application {app_id} not found")
+    return ApplicationResponse.model_validate(row.__dict__)
+
+# ❌ FORBIDDEN — no ownership check
+row = await session.get(Application, app_id)   # anyone can access
+
+# ❌ FORBIDDEN — raw dict returned
+return row.__dict__
+```
+
+## SQL Injection Prevention
+
+```python
+# ✅ SQLAlchemy ORM — always parameterised
+await session.execute(select(Application).where(Application.user_id == user_id))
+
+# ✅ Raw SQL with bound parameters
+await session.execute(text("SELECT * FROM applications WHERE user_id = :uid"), {"uid": user_id})
+
+# ❌ BLOCKED — string interpolation
+await session.execute(text(f"SELECT * FROM applications WHERE user_id = '{user_id}'"))
+```
+
+## Auth — Always via Depends(), Never Inline
+
+```python
+# ✅ Provider injected
+from src.providers.auth.middleware import require_auth
+
+@router.post("/")
+async def create(auth: AuthContext = Depends(require_auth), ...):
+    ...
+
+# ❌ Never roll your own inline
+token = request.headers.get("Authorization")
+payload = jwt.decode(token, os.environ["JWT_SECRET"])  # multiple violations (PyJWT used inline + os.environ)
+```
+
+## Error Responses — Never Expose Internals
+
+```python
+# ✅ Global exception handler maps DomainError → HTTPException
+# In src/runtime/exception_handlers.py:
+@app.exception_handler(ApplicationNotFoundError)
+async def not_found_handler(request, exc):
+    return JSONResponse(status_code=404, content={"error": {"code": "NOT_FOUND", "message": str(exc)}})
+
+# ❌ Never in handlers
+raise HTTPException(status_code=500, detail=str(exc))   # exposes internals
+```
+
+## Password Hashing — argon2id via pwdlib Only
+
+```python
+# ✅ pwdlib with argon2id (passlib is BROKEN on Python 3.13+ — never use it)
+from pwdlib import PasswordHash
+password_hash = PasswordHash.recommended()   # argon2id
+hashed = password_hash.hash(plain_password)
+verified = password_hash.verify(plain_password, hashed)
+
+# ❌ Never — passlib (broken on 3.13+), bcrypt (GPU-vulnerable), or hashlib
+from passlib.context import CryptContext        # FORBIDDEN — broken on Python 3.13+
+import hashlib
+hashlib.md5(password.encode()).hexdigest()      # FORBIDDEN
+```