@robhowley/py-pit-skills 3.1.1

package/skills/dockerize-service/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: dockerize-service
+description: Generate a local-development Docker Compose setup for an existing Python project. Produces a multi-stage Dockerfile, Compose file, env config, and dockerignore based on detected project signals.
+---
+
+# Skill: dockerize-service
+
+## Core position
+
+This skill produces a **local-development Docker Compose setup** that reflects the project as-is. It does not introduce backing services the repo doesn't already use, and it does not create a second Docker pattern if one already exists.
+
+---
+
+## Trigger
+
+Use this skill when the user wants to:
+- Containerize an existing Python project
+- Add Docker Compose to a project
+- Add a Dockerfile to a project
+- "Dockerize" a service
+
+---
+
+## Variables
+
+- `{pkg_name}` — snake_case package name (matches the project directory and Python package)
+- `{PKG_NAME}_` — env var prefix, only used if a pydantic-settings `env_prefix` is detected in the repo (e.g., `MY_SERVICE_`); otherwise plain names are used
+
+---
+
+## Step 1 — Inspect the repo
+
+Inspect before asking. Work through each check in order and record findings.
+
+**1. Check for existing Docker artifacts**
+
+Look for `Dockerfile`, `docker-compose.yml`, `docker-compose.yaml`, `.dockerignore`. If any are present, extend them — do not create a competing setup. Note what was found.
+
+**2. Check for repo tooling**
+
+- `uv.lock` present → uv-native project; use uv base image in Dockerfile
+- No `uv.lock` → pip-based project; use `python:3.12-slim` with `pip install`
+
+**3. Check for service signals**
+
+Inspect `pyproject.toml` dependencies and any settings/config files for:
+- `sqlalchemy` + a non-sqlite database URL pattern, or `psycopg`, `psycopg2`, `asyncpg` in deps → Postgres
+- `redis` in deps → Redis
+- No signals → **app-only** (do not add Postgres as a default)
+
+If Postgres is signaled, also note which driver is already present (`psycopg2-binary`, `psycopg[binary]`, `asyncpg`, etc.) — this determines what to add in Step 6.
+
+**4. Check for an existing health endpoint**
+
+Grep routes for `/health`, `/healthz`, `/ping`, `/api/v1/health`, or similar. Record the exact path if found.
+
+**5. Detect app entrypoint**
+
+Look for the ASGI `app` object in `{pkg_name}/main.py`, `{pkg_name}/app.py`, or `{pkg_name}/application.py`. Record the module path (e.g., `{pkg_name}.main:app`). Also check `[project.scripts]` in `pyproject.toml` for any uvicorn/gunicorn invocations. This becomes the `CMD` in the Dockerfile — default to `{pkg_name}.main:app` only if no entrypoint is found elsewhere.
+
+**6. Detect env prefix**
+
+Grep for `env_prefix` in `core/config.py`, `config.py`, `settings.py`, or similar. If a pydantic-settings prefix is found (e.g., `env_prefix="MY_SERVICE_"`), use it in `.env.compose`. If no prefix is detected, use plain variable names (`DATABASE_URL`, `REDIS_URL`, `DEBUG`) without a package prefix.
+
+**7. Present inference summary**
+
+Tell the user what was found and what will be generated. Ask for confirmation only if something is genuinely ambiguous (e.g., multiple config files with conflicting signals, or an existing `Dockerfile` with unclear extension points).
+
+---
+
+## Step 2 — Generate `Dockerfile`
+
+Multi-stage build. Base image depends on repo tooling detected in Step 1.
+
+**If `uv.lock` is present:**
+
+```dockerfile
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY {pkg_name}/ ./{pkg_name}/
+RUN uv sync --frozen --no-dev
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/{pkg_name} /app/{pkg_name}
+ENV PATH="/app/.venv/bin:$PATH"
+EXPOSE 8000
+{HEALTHCHECK}
+CMD ["/app/.venv/bin/uvicorn", "{detected_entrypoint|pkg_name.main:app}", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+**If no `uv.lock`:**
+
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY pyproject.toml ./
+COPY {pkg_name}/ ./{pkg_name}/
+RUN pip install --no-cache-dir --prefix=/install .
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /install /usr/local
+EXPOSE 8000
+{HEALTHCHECK}
+CMD ["uvicorn", "{detected_entrypoint|pkg_name.main:app}", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+**HEALTHCHECK selection:**
+
+- If a health endpoint was detected in Step 1:
+  ```dockerfile
+  HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000{detected_path}')"
+  ```
+- If no health endpoint exists, use a TCP liveness check and note that a health endpoint should be added:
+  ```dockerfile
+  HEALTHCHECK --interval=10s --timeout=3s --retries=3 \
+    CMD python -c "import socket; s=socket.socket(); s.settimeout(2); s.connect(('localhost', 8000)); s.close()"
+  ```
+  > Note: No health route was found. This is a **liveness-only** check — it confirms the server is accepting TCP connections but does not verify app readiness. Add a `/health` endpoint for a proper readiness check.
+
+---
+
+## Step 3 — Generate `docker-compose.yml`
+
+Always include the `app` service. Add `db` (Postgres) and/or `cache` (Redis) only based on signals found in Step 1.
+
+```yaml
+# Local development only — not a production deployment target
+services:
+  app:
+    build: .
+    ports:
+      - "8000:8000"
+    env_file: .env.compose
+    depends_on:
+      db:                          # only if postgres signaled
+        condition: service_healthy
+      cache:                       # only if redis signaled
+        condition: service_healthy
+    restart: unless-stopped
+
+  db:                              # only if postgres signaled
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: {pkg_name}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  cache:                           # only if redis signaled
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:                   # only if postgres signaled
+```
+
+---
+
+## Step 4 — Generate `.env.compose`
+
+Environment variables for the running containers. Use the env prefix detected in Step 1 if a pydantic-settings prefix was found; otherwise use plain variable names. Generate **one** `.env.compose` — not both variants.
+
+If prefix detected (e.g. `MY_SERVICE_`):
+```
+# docker compose environment — do not commit real secrets
+MY_SERVICE_DATABASE_URL=postgresql+psycopg2://postgres:postgres@db:5432/{pkg_name}  # only if postgres signaled
+MY_SERVICE_REDIS_URL=redis://cache:6379/0                                            # only if redis signaled
+MY_SERVICE_DEBUG=false
+```
+
+If no prefix detected:
+```
+# docker compose environment — do not commit real secrets
+DATABASE_URL=postgresql+psycopg2://postgres:postgres@db:5432/{pkg_name}             # only if postgres signaled
+REDIS_URL=redis://cache:6379/0                                                       # only if redis signaled
+DEBUG=false
+```
+
+Also create `.env.compose.example` with the same content — this file IS committed to version control as a template.
+
+Add `.env.compose` to `.gitignore`:
+
+```
+echo ".env.compose" >> .gitignore
+```
+
+---
+
+## Step 5 — Generate `.dockerignore`
+
+Skip if `.dockerignore` already exists and covers these patterns.
+
+```
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+.env*
+!.env.compose.example
+```
+
+---
+
+## Step 6 — Update dependencies if needed
+
+**Postgres driver** — only if Postgres was signaled and no postgres driver is already present in `pyproject.toml`:
+
+Inspect the existing stack first:
+- Async stack (uses `asyncpg` elsewhere, or `AsyncSession`) → add `asyncpg`
+- Sync stack with modern psycopg → add `psycopg[binary]`
+- Sync stack with legacy psycopg2 → add `psycopg2-binary`
+- Do not introduce a second driver if one already exists
+
+Follow the repo's dependency management workflow:
+- `uv.lock` present → `uv add <driver>`
+- No `uv.lock` → add `<driver>` to `[project.dependencies]` in `pyproject.toml` and follow the project's dependency-management workflow
+
+**Redis** — only if Redis was signaled and `redis` is not already in deps:
+- `uv.lock` present → `uv add redis`
+- No `uv.lock` → add `redis` to `[project.dependencies]` in `pyproject.toml` and follow the project's dependency-management workflow
+
+---
+
+## Step 7 — Verify
+
+```bash
+docker compose up --build -d
+docker compose ps          # all services healthy
+curl http://localhost:8000{detected_health_path_or_omit_if_none}
+docker compose down
+```
+
+If no health endpoint exists, omit the `curl` line and note that one should be added before moving to production.
+
+---
+
+## Hard constraints
+
+1. Always use multi-stage builds — keep the final image lean by excluding build tooling and intermediate artifacts
+2. Never embed real credentials in `docker-compose.yml` — always use `env_file`
+3. Always include a `HEALTHCHECK` in the Dockerfile and `healthcheck:` on backing services
+4. Use `depends_on: condition: service_healthy` — not plain `depends_on`
+5. Add `.env.compose` to `.gitignore`; provide `.env.compose.example` as a committed template
+6. Never introduce a backing service (Postgres, Redis) unless the repo or user request shows it is needed — no signals → app-only
+7. If Docker artifacts already exist, extend them; do not create a parallel competing setup
+8. Match the project's existing dependency management workflow — do not assume uv if `uv.lock` is absent
+9. Do not invent or hardcode a health endpoint path — detect from existing routes or use the TCP liveness fallback
+
+---
+
+## Completion checklist
+
+- [ ] `Dockerfile` present, multi-stage, appropriate base image for repo tooling
+- [ ] `docker-compose.yml` scoped to inferred services only; no uninferred backing services added
+- [ ] `HEALTHCHECK` uses detected path or TCP liveness fallback — no invented path
+- [ ] `.env.compose` present, `.gitignore` updated, `.env.compose.example` committed
+- [ ] No existing Docker artifacts replaced without user confirmation
+- [ ] No new backing services introduced without repo evidence or explicit user request
+- [ ] No hardcoded credentials in `docker-compose.yml`
+- [ ] `docker compose up --build` succeeds

package/skills/fastapi-errors/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: fastapi-errors
+description: Opinionated error architecture for FastAPI services. Enforces a single internal exception hierarchy, constructor-based messages, consistent API error responses, and centralized logging for unexpected failures.
+disable-model-invocation: false
+---
+
+# fastapi-errors
+
+Defines a **simple, consistent error architecture** for FastAPI backend services.
+
+This skill standardizes the flow:
+
+```text
+service/domain failure
+→ application exception
+→ global FastAPI exception handler
+→ consistent JSON response
+```
+
+The goal is to prevent common FastAPI problems:
+
+- `HTTPException` raised deep in service logic
+- inconsistent error response formats
+- duplicated status code logic
+- domain failures implemented with builtin exceptions
+- unexpected exceptions leaking poor diagnostics
+
+---
+
+# Apply this Skill When
+
+Apply when the user:
+
+- asks how to structure FastAPI error handling
+- is adding domain exceptions
+- is designing service-layer failures
+- is implementing API error responses
+- is building a new FastAPI service
+- is adding new domain errors in an existing repo
+
+Do **not** apply when:
+
+- the task is unrelated to application error handling
+- the user explicitly wants a different architecture
+
+---
+
+# Base Exception
+
+The service defines one base exception for intentional application failures.
+
+Preferred naming pattern:
+
+```text
+<PackageName>Error
+```
+
+Examples:
+
+```text
+BillingError
+UserServiceError
+InventoryError
+```
+
+If the package name cannot be determined, use:
+
+```text
+AppError
+```
+
+Define all exceptions in a single module — `errors.py` or `exceptions.py` at the package root. Do not scatter them across feature files.
+
+Example base implementation:
+
+```python
+class AppError(Exception):
+    status_code = 500
+
+    def __init__(self, message: str | None = None, **context):
+        self.message = message or "Unhandled application error"
+        self.context = context
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        return self.message
+```
+
+Key characteristics:
+
+- default HTTP status = **500**
+- default message provided in the constructor
+- optional context data for logging
+- subclasses override `status_code` or pass formatted messages
+
+---
+
+# Domain Exception Pattern
+
+Application/domain errors should subclass the base error.
+
+Example:
+
+```python
+class UserNotFoundError(AppError):
+    status_code = 404
+
+    def __init__(self, user_id: int):
+        super().__init__(f"User {user_id} not found", user_id=user_id)
+```
+
+Example usage in service code:
+
+```python
+if user is None:
+    raise UserNotFoundError(user_id)
+```
+
+---
+
+# Global FastAPI Exception Handler
+
+The API boundary converts internal exceptions into HTTP responses.
+
+Example:
+
+```python
+@app.exception_handler(AppError)
+async def handle_app_error(request: Request, exc: AppError):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"error": str(exc)},
+    )
+```
+
+Response format is intentionally simple:
+
+```json
+{
+  "error": "User 123 not found"
+}
+```
+
+---
+
+# Unexpected Exception Handling
+
+Unexpected exceptions should be handled consistently.
+
+Use a fallback handler for uncaught exceptions:
+
+```python
+@app.exception_handler(Exception)
+async def handle_unexpected_error(request: Request, exc: Exception):
+    wrapped = AppError()
+
+    logger.exception(
+        "Unhandled exception",
+        extra={
+            "path": str(request.url.path),
+            "method": request.method,
+            "error_type": type(exc).__name__,
+        },
+    )
+
+    return JSONResponse(
+        status_code=wrapped.status_code,
+        content={"error": str(wrapped)},
+    )
+```
+
+This does three things:
+
+- preserves a stable client-facing response
+- ensures unexpected failures are logged centrally
+- treats uncaught exceptions consistently through the base application-error contract
+
+Do not leak raw internal exception details to clients.
+
+Log at minimum: request path, HTTP method, exception type, and correlation ID if the repo uses one. Follow existing structured logging conventions if present.
+
+---
+
+# Existing Repository Strategy
+
+In existing repositories, **inspect current error patterns before introducing new ones**.
+
+Follow these rules:
+
+- Look for an existing internal base exception.
+- If one exists and is coherent, **extend it instead of creating a new base class**.
+- Integrate with existing exception handlers when possible.
+- Only introduce the recommended base-exception pattern if the repo lacks a clear contract or the user asks to refactor.
+
+Do **not** create parallel exception hierarchies in a mature codebase.
+
+---
+
+# Validation Errors
+
+FastAPI raises `RequestValidationError` for malformed or invalid request bodies. This is framework-level — it does not subclass your app's base exception. Without a handler, FastAPI emits its default 422 response with a raw Pydantic error blob, which breaks response shape consistency.
+
+Add a dedicated handler:
+
+```python
+from fastapi.exceptions import RequestValidationError
+
+@app.exception_handler(RequestValidationError)
+async def handle_validation_error(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=422,
+        content={"error": "Invalid request data", "details": exc.errors()},
+    )
+```
+
+Including `exc.errors()` in a `details` field is recommended — validation errors are client-fixable and surfacing them helps the caller correct the request.
+
+---
+
+# Auth Errors
+
+Auth handling involves two distinct cases. Don't conflate them.
+
+**FastAPI security dependencies** (`HTTPBearer`, `OAuth2PasswordBearer`, `Depends(security_scheme)`, etc.) raise `HTTPException` internally. This is expected framework behavior — do not fight it or try to wrap it in domain exceptions.
+
+**Custom auth logic** (token validation, permission checks) belongs in service code and should use domain exceptions:
+
+```python
+class UnauthenticatedError(AppError):
+    status_code = 401
+
+    def __init__(self):
+        super().__init__("Authentication required")
+
+
+class UnauthorizedError(AppError):
+    status_code = 403
+
+    def __init__(self, action: str | None = None):
+        msg = f"Not authorized to {action}" if action else "Not authorized"
+        super().__init__(msg)
+```
+
+These flow through the global `AppError` handler like any other domain exception.
+
+---
+
+# Error Codes (Optional)
+
+For APIs consumed by clients that need to branch on error type — public APIs, client SDKs, multi-error workflows — a machine-readable `code` field is useful. Skip this for internal services or simple CRUD APIs where string parsing is acceptable.
+
+Pattern: add an optional `code` class attribute to the base exception; domain subclasses override it.
+
+```python
+class AppError(Exception):
+    status_code = 500
+    code: str | None = None  # add this
+    ...
+
+class UserNotFoundError(AppError):
+    status_code = 404
+    code = "user_not_found"  # subclasses set a value
+    ...
+```
+
+Update the global handler to include `code` when present:
+
+```python
+@app.exception_handler(AppError)
+async def handle_app_error(request: Request, exc: AppError):
+    content = {"error": str(exc)}
+    if exc.code:
+        content["code"] = exc.code
+    return JSONResponse(status_code=exc.status_code, content=content)
+```
+
+Response shape when `code` is set:
+
+```json
+{
+  "error": "User 123 not found",
+  "code": "user_not_found"
+}
+```
+
+---
+
+# Hard Rules
+
+**MUST**
+
+- Define a single internal base exception for application failures.
+- Subclass that base exception for domain errors.
+- Declare `status_code` on exception classes.
+- Handle the internal exception hierarchy in one global FastAPI handler.
+- Return a consistent JSON error response.
+- Log unexpected exceptions centrally in the fallback handler.
+- Add a `RequestValidationError` handler when response shape consistency matters.
+
+**MUST NOT**
+
+- Raise `HTTPException` in service or domain code. Exception: `HTTPException` raised internally by FastAPI security dependencies (`HTTPBearer`, `OAuth2PasswordBearer`, etc.) is acceptable — that is the framework's designed behavior.
+- Use builtin exceptions (`ValueError`, `RuntimeError`, etc.) for intentional domain failures.
+- Invent new error response formats per endpoint.
+- Duplicate HTTP status logic outside the exception classes.
+- Introduce a second application error hierarchy when one already exists.
+- Leak raw internal exception messages or stack traces to clients.
+
+---
+
+# Outcome
+
+Applying this skill results in:
+
+- one coherent application error hierarchy
+- clear separation between service failures and HTTP responses
+- consistent API error responses
+- centralized logging for true unexpected failures
+- predictable error handling across the entire service