claude-code-pilot 3.2.0 → 3.3.0

package/src/skills/error-handling/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: error-handling
+description: Patterns for robust error handling across TypeScript, Python, and Go. Covers typed errors, error boundaries, retries, circuit breakers, and user-facing error messages.
+origin: ECC
+---
+
+# Error Handling Patterns
+
+Consistent, robust error handling patterns for production applications.
+
+## When to Activate
+
+- Designing error types or exception hierarchies for a new module or service
+- Adding retry logic or circuit breakers for unreliable external dependencies
+- Reviewing API endpoints for missing error handling
+- Implementing user-facing error messages and feedback
+- Debugging cascading failures or silent error swallowing
+
+## Core Principles
+
+1. **Fail fast and loudly** — surface errors at the boundary where they occur; don't bury them
+2. **Typed errors over string messages** — errors are first-class values with structure
+3. **User messages ≠ developer messages** — show friendly text to users, log full context server-side
+4. **Never swallow errors silently** — every `catch` block must either handle, re-throw, or log
+5. **Errors are part of your API contract** — document every error code a client may receive
+
+## TypeScript / JavaScript
+
+### Typed Error Classes
+
+```typescript
+// Define an error hierarchy for your domain
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public readonly code: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: unknown,
+  ) {
+    super(message)
+    this.name = this.constructor.name
+    // Maintain correct prototype chain in transpiled ES5 JavaScript.
+    // Required for `instanceof` checks (e.g., `error instanceof NotFoundError`)
+    // to work correctly when extending the built-in Error class.
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404)
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details: { field: string; message: string }[]) {
+    super(message, 'VALIDATION_ERROR', 422, details)
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(reason = 'Authentication required') {
+    super(reason, 'UNAUTHORIZED', 401)
+  }
+}
+
+export class RateLimitError extends AppError {
+  constructor(public readonly retryAfterMs: number) {
+    super('Rate limit exceeded', 'RATE_LIMITED', 429)
+  }
+}
+```
+
+### Result Pattern (no-throw style)
+
+For operations where failure is expected and common (parsing, external calls):
+
+```typescript
+type Result<T, E = AppError> =
+  | { ok: true; value: T }
+  | { ok: false; error: E }
+
+function ok<T>(value: T): Result<T> {
+  return { ok: true, value }
+}
+
+function err<E>(error: E): Result<never, E> {
+  return { ok: false, error }
+}
+
+// Usage
+async function fetchUser(id: string): Promise<Result<User>> {
+  try {
+    const user = await db.users.findUnique({ where: { id } })
+    if (!user) return err(new NotFoundError('User', id))
+    return ok(user)
+  } catch (e) {
+    return err(new AppError('Database error', 'DB_ERROR'))
+  }
+}
+
+const result = await fetchUser('abc-123')
+if (!result.ok) {
+  // TypeScript knows result.error here
+  logger.error('Failed to fetch user', { error: result.error })
+  return
+}
+// TypeScript knows result.value here
+console.log(result.value.email)
+```
+
+### API Error Handler (Next.js / Express)
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server'
+
+function handleApiError(error: unknown): NextResponse {
+  // Known application error
+  if (error instanceof AppError) {
+    return NextResponse.json(
+      {
+        error: {
+          code: error.code,
+          message: error.message,
+          ...(error.details ? { details: error.details } : {}),
+        },
+      },
+      { status: error.statusCode },
+    )
+  }
+
+  // Zod validation error
+  if (error instanceof z.ZodError) {
+    return NextResponse.json(
+      {
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Request validation failed',
+          details: error.issues.map(i => ({
+            field: i.path.join('.'),
+            message: i.message,
+          })),
+        },
+      },
+      { status: 422 },
+    )
+  }
+
+  // Unexpected error — log details, return generic message
+  console.error('Unexpected error:', error)
+  return NextResponse.json(
+    { error: { code: 'INTERNAL_ERROR', message: 'An unexpected error occurred' } },
+    { status: 500 },
+  )
+}
+
+export async function POST(req: NextRequest) {
+  try {
+    // ... handler logic
+  } catch (error) {
+    return handleApiError(error)
+  }
+}
+```
+
+### React Error Boundary
+
+```typescript
+import { Component, ErrorInfo, ReactNode } from 'react'
+
+interface Props {
+  fallback: ReactNode
+  onError?: (error: Error, info: ErrorInfo) => void
+  children: ReactNode
+}
+
+interface State {
+  hasError: boolean
+  error: Error | null
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false, error: null }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError?.(error, info)
+    console.error('Unhandled React error:', error, info)
+  }
+
+  render() {
+    if (this.state.hasError) return this.props.fallback
+    return this.props.children
+  }
+}
+
+// Usage
+<ErrorBoundary fallback={<p>Something went wrong. Please refresh.</p>}>
+  <MyComponent />
+</ErrorBoundary>
+```
+
+## Python
+
+### Custom Exception Hierarchy
+
+```python
+class AppError(Exception):
+    """Base application error."""
+    def __init__(self, message: str, code: str, status_code: int = 500):
+        super().__init__(message)
+        self.code = code
+        self.status_code = status_code
+
+class NotFoundError(AppError):
+    def __init__(self, resource: str, id: str):
+        super().__init__(f"{resource} not found: {id}", "NOT_FOUND", 404)
+
+class ValidationError(AppError):
+    def __init__(self, message: str, details: list[dict] | None = None):
+        super().__init__(message, "VALIDATION_ERROR", 422)
+        self.details = details or []
+```
+
+### FastAPI Global Exception Handler
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.exception_handler(AppError)
+async def app_error_handler(request: Request, exc: AppError) -> JSONResponse:
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": {"code": exc.code, "message": str(exc)}},
+    )
+
+@app.exception_handler(Exception)
+async def generic_error_handler(request: Request, exc: Exception) -> JSONResponse:
+    # Log full details, return generic message
+    logger.exception("Unexpected error", exc_info=exc)
+    return JSONResponse(
+        status_code=500,
+        content={"error": {"code": "INTERNAL_ERROR", "message": "An unexpected error occurred"}},
+    )
+```
+
+## Go
+
+### Sentinel Errors and Error Wrapping
+
+```go
+package domain
+
+import "errors"
+
+// Sentinel errors for type-checking
+var (
+    ErrNotFound    = errors.New("not found")
+    ErrUnauthorized = errors.New("unauthorized")
+    ErrConflict     = errors.New("conflict")
+)
+
+// Wrap errors with context — never lose the original
+func (r *UserRepository) FindByID(ctx context.Context, id string) (*User, error) {
+    user, err := r.db.QueryRow(ctx, "SELECT * FROM users WHERE id = $1", id)
+    if errors.Is(err, sql.ErrNoRows) {
+        return nil, fmt.Errorf("user %s: %w", id, ErrNotFound)
+    }
+    if err != nil {
+        return nil, fmt.Errorf("querying user %s: %w", id, err)
+    }
+    return user, nil
+}
+
+// At the handler level, unwrap to determine response
+func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
+    user, err := h.service.GetUser(r.Context(), chi.URLParam(r, "id"))
+    if err != nil {
+        switch {
+        case errors.Is(err, domain.ErrNotFound):
+            writeError(w, http.StatusNotFound, "not_found", err.Error())
+        case errors.Is(err, domain.ErrUnauthorized):
+            writeError(w, http.StatusForbidden, "forbidden", "Access denied")
+        default:
+            slog.Error("unexpected error", "err", err)
+            writeError(w, http.StatusInternalServerError, "internal_error", "An unexpected error occurred")
+        }
+        return
+    }
+    writeJSON(w, http.StatusOK, user)
+}
+```
+
+## Retry with Exponential Backoff
+
+```typescript
+interface RetryOptions {
+  maxAttempts?: number
+  baseDelayMs?: number
+  maxDelayMs?: number
+  retryIf?: (error: unknown) => boolean
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const {
+    maxAttempts = 3,
+    baseDelayMs = 500,
+    maxDelayMs = 10_000,
+    retryIf = () => true,
+  } = options
+
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn()
+    } catch (error) {
+      lastError = error
+      if (attempt === maxAttempts || !retryIf(error)) throw error
+
+      const jitter = Math.random() * baseDelayMs
+      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1) + jitter, maxDelayMs)
+      await new Promise(resolve => setTimeout(resolve, delay))
+    }
+  }
+
+  throw lastError
+}
+
+// Usage: retry transient network errors, not 4xx
+const data = await withRetry(() => fetch('/api/data').then(r => r.json()), {
+  maxAttempts: 3,
+  retryIf: (error) => !(error instanceof AppError && error.statusCode < 500),
+})
+```
+
+## User-Facing Error Messages
+
+Map error codes to human-readable messages. Keep technical details out of user-visible text.
+
+```typescript
+const USER_ERROR_MESSAGES: Record<string, string> = {
+  NOT_FOUND: 'The requested item could not be found.',
+  UNAUTHORIZED: 'Please sign in to continue.',
+  FORBIDDEN: "You don't have permission to do that.",
+  VALIDATION_ERROR: 'Please check your input and try again.',
+  RATE_LIMITED: 'Too many requests. Please wait a moment and try again.',
+  INTERNAL_ERROR: 'Something went wrong on our end. Please try again later.',
+}
+
+export function getUserMessage(code: string): string {
+  return USER_ERROR_MESSAGES[code] ?? USER_ERROR_MESSAGES.INTERNAL_ERROR
+}
+```
+
+## Error Handling Checklist
+
+Before merging any code that touches error handling:
+
+- [ ] Every `catch` block handles, re-throws, or logs — no silent swallowing
+- [ ] API errors follow the standard envelope `{ error: { code, message } }`
+- [ ] User-facing messages contain no stack traces or internal details
+- [ ] Full error context is logged server-side
+- [ ] Custom error classes extend a base `AppError` with a `code` field
+- [ ] Async functions surface errors to callers — no fire-and-forget without fallback
+- [ ] Retry logic only retries retriable errors (not 4xx client errors)
+- [ ] React components are wrapped in `ErrorBoundary` for rendering errors

package/src/skills/fastapi-patterns/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: fastapi-patterns
+description: FastAPI patterns for async APIs, dependency injection, Pydantic request and response models, OpenAPI docs, tests, security, and production readiness.
+origin: community
+---
+
+# FastAPI Patterns
+
+Production-oriented patterns for FastAPI services.
+
+## When to Use
+
+- Building or reviewing a FastAPI app.
+- Splitting routers, schemas, dependencies, and database access.
+- Writing async endpoints that call a database or external service.
+- Adding authentication, authorization, OpenAPI docs, tests, or deployment settings.
+- Checking a FastAPI PR for copy-pasteable examples and production risks.
+
+## How It Works
+
+Treat the FastAPI app as a thin HTTP layer over explicit dependencies and service code:
+
+- `main.py` owns app construction, middleware, exception handlers, and router registration.
+- `schemas/` owns Pydantic request and response models.
+- `dependencies.py` owns database, auth, pagination, and request-scoped dependencies.
+- `services/` or `crud/` owns business and persistence operations.
+- `tests/` overrides dependencies instead of opening production resources.
+
+Prefer small routers and explicit `response_model` declarations. Keep raw ORM objects, secrets, and framework globals out of response schemas.
+
+## Project Layout
+
+```text
+app/
+|-- main.py
+|-- config.py
+|-- dependencies.py
+|-- exceptions.py
+|-- api/
+|   `-- routes/
+|       |-- users.py
+|       `-- health.py
+|-- core/
+|   |-- security.py
+|   `-- middleware.py
+|-- db/
+|   |-- session.py
+|   `-- crud.py
+|-- models/
+|-- schemas/
+`-- tests/
+```
+
+## Application Factory
+
+Use a factory so tests and workers can build the app with controlled settings.
+
+```python
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from app.api.routes import health, users
+from app.config import settings
+from app.db.session import close_db, init_db
+from app.exceptions import register_exception_handlers
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await init_db()
+    yield
+    await close_db()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title=settings.api_title,
+        version=settings.api_version,
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins,
+        allow_credentials=bool(settings.cors_origins),
+        allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
+        allow_headers=["Authorization", "Content-Type"],
+    )
+
+    register_exception_handlers(app)
+    app.include_router(health.router, prefix="/health", tags=["health"])
+    app.include_router(users.router, prefix="/api/v1/users", tags=["users"])
+    return app
+
+
+app = create_app()
+```
+
+Do not use `allow_origins=["*"]` with `allow_credentials=True`; browsers reject that combination and Starlette disallows it for credentialed requests.
+
+## Pydantic Schemas
+
+Keep request, update, and response models separate.
+
+```python
+from datetime import datetime
+from typing import Annotated
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, EmailStr, Field
+
+
+class UserBase(BaseModel):
+    email: EmailStr
+    full_name: Annotated[str, Field(min_length=1, max_length=100)]
+
+
+class UserCreate(UserBase):
+    password: Annotated[str, Field(min_length=12, max_length=128)]
+
+
+class UserUpdate(BaseModel):
+    email: EmailStr | None = None
+    full_name: Annotated[str | None, Field(min_length=1, max_length=100)] = None
+
+
+class UserResponse(UserBase):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: UUID
+    created_at: datetime
+    updated_at: datetime
+```
+
+Response models must never include password hashes, access tokens, refresh tokens, or internal authorization state.
+
+## Dependencies
+
+Use dependency injection for request-scoped resources.
+
+```python
+from collections.abc import AsyncIterator
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.security import decode_token
+from app.db.session import session_factory
+from app.models.user import User
+
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+
+async def get_db() -> AsyncIterator[AsyncSession]:
+    async with session_factory() as session:
+        try:
+            yield session
+            await session.commit()
+        except Exception:
+            await session.rollback()
+            raise
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    payload = decode_token(token)
+    user_id = UUID(payload["sub"])
+    user = await db.get(User, user_id)
+    if user is None:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")
+    return user
+```
+
+Avoid creating sessions, clients, or credentials inline inside route handlers.
+
+## Async Endpoints
+
+Keep route handlers async when they perform I/O, and use async libraries inside them.
+
+```python
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_current_user, get_db
+from app.models.user import User
+from app.schemas.user import UserResponse
+
+
+router = APIRouter()
+
+
+@router.get("/", response_model=list[UserResponse])
+async def list_users(
+    limit: int = Query(default=50, ge=1, le=100),
+    offset: int = Query(default=0, ge=0),
+    db: AsyncSession = Depends(get_db),
+    current_user: User = Depends(get_current_user),
+):
+    result = await db.execute(
+        select(User).order_by(User.created_at.desc()).limit(limit).offset(offset)
+    )
+    return result.scalars().all()
+```
+
+Use `httpx.AsyncClient` for external HTTP calls from async handlers. Do not call `requests` in an async route.
+
+## Error Handling
+
+Centralize domain exceptions and keep response shapes stable.
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+
+class ApiError(Exception):
+    def __init__(self, status_code: int, code: str, message: str):
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    @app.exception_handler(ApiError)
+    async def api_error_handler(request: Request, exc: ApiError):
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={"error": {"code": exc.code, "message": exc.message}},
+        )
+```
+
+## OpenAPI Customization
+
+Assign the custom OpenAPI callable to `app.openapi`; do not just call the function once.
+
+```python
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+
+def install_openapi(app: FastAPI) -> None:
+    def custom_openapi():
+        if app.openapi_schema:
+            return app.openapi_schema
+        app.openapi_schema = get_openapi(
+            title="Service API",
+            version="1.0.0",
+            routes=app.routes,
+        )
+        return app.openapi_schema
+
+    app.openapi = custom_openapi
+```
+
+## Testing
+
+Override the dependency used by `Depends`, not an internal helper that route handlers never reference.
+
+```python
+import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.dependencies import get_db
+from app.main import create_app
+
+
+@pytest.fixture
+async def client(test_session: AsyncSession):
+    app = create_app()
+
+    async def override_get_db():
+        yield test_session
+
+    app.dependency_overrides[get_db] = override_get_db
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as test_client:
+        yield test_client
+    app.dependency_overrides.clear()
+```
+
+## Security Checklist
+
+- Hash passwords with `argon2-cffi`, `bcrypt`, or a current passlib-compatible hasher.
+- Validate JWT issuer, audience, expiry, and signing algorithm.
+- Keep CORS origins environment-specific.
+- Put rate limits on auth and write-heavy endpoints.
+- Use Pydantic models for all request bodies.
+- Use ORM parameter binding or SQLAlchemy Core expressions; never build SQL with f-strings.
+- Redact tokens, authorization headers, cookies, and passwords from logs.
+- Run dependency audit tooling in CI.
+
+## Performance Checklist
+
+- Configure database connection pooling explicitly.
+- Add pagination to list endpoints.
+- Watch for N+1 queries and use eager loading intentionally.
+- Use async HTTP/database clients in async paths.
+- Add compression only after checking payload size and CPU tradeoffs.
+- Cache stable expensive reads behind explicit invalidation.
+
+## Examples
+
+Use these examples as patterns, not as project-wide templates:
+
+- Application factory: configure middleware and routers once in `create_app`.
+- Schema split: `UserCreate`, `UserUpdate`, and `UserResponse` have different responsibilities.
+- Dependency override: tests override `get_db` directly.
+- OpenAPI customization: assign `app.openapi = custom_openapi`.
+
+## See Also
+
+- Agent: `fastapi-reviewer`
+- Command: `/fastapi-review`
+- Skill: `python-patterns`
+- Skill: `python-testing`
+- Skill: `api-design`