@clubedge/create-clubedge-app 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.34.0
+
+- **A FastAPI API**: default to Starter `v0.23.0` (#101). `--framework vite --api fastapi` creates the React + Vite frontend with an API in Python, managed with [uv](https://docs.astral.sh/uv/):
+  - The Starter added it as one folder that describes itself, and this CLI generates it without a code change: the API lands in `apps/api` as `@clubedge/api`, and the CLI runs `uv sync` after `pnpm install`.
+  - Its `package.json` scripts call uv, ruff, mypy, and pytest, so `pnpm dev`, `pnpm lint`, `pnpm typecheck`, and `pnpm test` run it like the other apps. `pnpm lint` and `pnpm test` now also run each app's own scripts, so apps in other languages are always checked.
+  - It passes the same contract suite as the Hono API, against the live server, through `clubedge-contract-check`.
+  - A first version: the app modules are `none` (cache: memory, deploy: Docker). Install uv first.
+- CI generates the pair from the packed CLI. The smoke check waits for a separate API that starts after its frontend (#100).
+
 ## 0.33.0
 
 - **A frontend and a separate API**: default to Starter `v0.22.0` (#98). `--framework vite --api hono` creates a React + Vite frontend in `apps/web` and a Hono API in `apps/api`, joined by one HTTP contract:

package/README.md

@@ -78,6 +78,9 @@ pnpm dlx @clubedge/create-clubedge-app my-app --framework vite --api hono
 | ------------------ | ----------------------------------------------------- | ----------- |
 | `--framework vite` | React + Vite single-page app (TanStack Router)        | `apps/web`  |
 | `--api hono`       | Hono API on Node, reusing the Starter's packages      | `apps/api`  |
+| `--api fastapi`    | FastAPI API in Python, managed with [uv](https://docs.astral.sh/uv/) | `apps/api`  |
+
+A Python API needs uv; the CLI installs its dependencies with it after `pnpm install`, and its `package.json` scripts call uv, so `pnpm dev`, `pnpm lint`, and `pnpm test` run it like the other apps.
 
 They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend calls the API only through the client generated from it, and every API passes the same conformance suite. `pnpm dev` starts both, and the frontend forwards `/api` to the API. A full-stack framework (`next`, `tanstack-start`) has its own server, so it takes no `--api`.
 
@@ -120,7 +123,7 @@ Usage:
 
 Options:
   --framework <id>        App framework, such as next or tanstack-start (or vite, a frontend)
-  --api <id>              A separate API for a frontend, such as hono
+  --api <id>              A separate API for a frontend, such as hono or fastapi
   --<module> <option>     A module option, such as --auth none; the Starter lists its modules
   --ref <ref>             Download this Starter tag, branch, or commit from GitHub instead
                           (upgrade: the Starter to upgrade to)
@@ -147,7 +150,7 @@ pnpm dlx @clubedge/create-clubedge-app my-app --yes --no-git --framework tanstac
 pnpm dlx @clubedge/create-clubedge-app my-app --ref main
 
 # Reproduce a specific Starter release or commit
-pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.22.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.23.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -166,7 +169,7 @@ pnpm clubedge add email resend payments stripe              # several modules as
 pnpm clubedge remove storage payments
 pnpm dlx @clubedge/create-clubedge-app add infra local --dry-run
 pnpm dlx @clubedge/create-clubedge-app@latest upgrade        # to the newest CLI's Starter release
-pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.22.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.23.0 # or a specific tag, branch, or commit
 ```
 
 The CLI renders the project twice, from the Starter commit and modules recorded in your `package.json` and from the new state, and merges the difference into your project. The new state has other modules for `add` and `remove`, and the newer Starter with the same modules for `upgrade`. Modules a newer Starter introduces start as `none` where possible, so an upgrade never adds a service on its own.
@@ -277,27 +280,27 @@ Projects created with `--infra neon` also have `.github/workflows/preview.yml`,
 Each CLI release is tested against one specific Starter release:
 
 ```text
-create-clubedge-app v0.33.0
+create-clubedge-app v0.34.0
         |
         v
-Clubedge Starter v0.22.0
-commit d0f3f9cdd4d568504cec4cf4681c7faf97842405
+Clubedge Starter v0.23.0
+commit 0183d091b7bffac92cd0073f12b5329e96fc183f
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.33.0` | `clubedge-starter@v0.22.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.34.0` | `clubedge-starter@v0.23.0` | The CLI's required, tested default |
 
 This means the same CLI version always scaffolds the same Starter revision by default. The CLI does not silently follow Starter `main`.
 
-The `v0.22.0` tag is expected to resolve to commit
-`d0f3f9cdd4d568504cec4cf4681c7faf97842405`. The CLI verifies this before
+The `v0.23.0` tag is expected to resolve to commit
+`0183d091b7bffac92cd0073f12b5329e96fc183f`. The CLI verifies this before
 scaffolding with the default reference and fails rather than silently using a
 moved tag.
 
-When the Starter changes, its maintainers first publish a new versioned release, such as `v0.22.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
+When the Starter changes, its maintainers first publish a new versioned release, such as `v0.23.0`. The CLI is then updated to use that release, all generated-project checks must pass, and a new CLI version is published. This keeps Starter and CLI releases independently versioned while preserving a tested compatibility relationship.
 
 Every generated project records its CLI version, Starter repository, Starter ref, Starter commit, framework, and modules in `package.json` and `README.md`.
 
@@ -352,7 +355,7 @@ CI packs the CLI with `npm pack`, scaffolds clean projects from the packed tarba
 1. Make and validate changes in `clubedge-starter`.
 2. Run lint, typecheck, unit tests, browser tests, and production build.
 3. Update the Starter package versions.
-4. Commit `main`, create a release tag such as `v0.22.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.23.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -396,6 +399,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.31.0 | v0.20.0 | Pluggable background jobs: `--jobs bullmq` and `--jobs inngest` next to pg-boss, and a conformance suite every provider passes |
 | 0.32.0 | v0.21.0 | Pluggable authentication: `--auth firebase` and `--auth appwrite` next to Supabase and Better Auth, and a conformance suite every provider passes |
 | 0.33.0 | v0.22.0 | Starter v0.22.0: stack packs (template schema 4), and a React + Vite frontend with a separate Hono API (`--framework vite --api hono`) |
+| 0.34.0 | v0.23.0 | Starter v0.23.0: a FastAPI API in Python (`--framework vite --api fastapi`), generated with no CLI change |
 | next | | Show the Starter's version of a conflicted file next to yours |
 
 ## Community

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Create a Next.js or TanStack Start application from the Clubedge Starter reference implementation.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -22,8 +22,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.22.0",
-    "starterCommit": "d0f3f9cdd4d568504cec4cf4681c7faf97842405"
+    "starterRef": "v0.23.0",
+    "starterCommit": "0183d091b7bffac92cd0073f12b5329e96fc183f"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/.github/workflows/ci.yml

@@ -31,6 +31,9 @@ jobs:
         with:
           node-version: 22
           cache: pnpm
+      # Apps in other languages run their lint, typecheck, and tests with their own tools.
+      - uses: astral-sh/setup-uv@v10.3.0
+        if: ${{ hashFiles('apps/*/pyproject.toml') != '' }}
       - run: pnpm install --frozen-lockfile
       - run: pnpm format:check
       - run: pnpm lint

package/template/SETUP.md

@@ -612,7 +612,10 @@ To change the API, edit `openapi.yaml` first, run `pnpm --filter @clubedge/contr
 API_URL=http://127.0.0.1:3001 pnpm exec vitest run packages/contract/src/remote.test.ts
 ```
 
-In production, run each app's image: the root `Dockerfile` (the frontend, served by Caddy, with `API_URL` set to the API's address) and `apps/api/Dockerfile`. `docker compose up --build` runs both. Run `node migrate.mjs` in the API's image before a new version starts.
+In production, run each app's image: the root `Dockerfile` (the frontend, served by Caddy, with `API_URL` set to the API's address) and `apps/api/Dockerfile`. `docker compose up --build` runs both.
+
+Run `node migrate.mjs` in the API's image before a new version starts. <!-- clubedge:only api=hono -->
+The API is in Python and managed with [uv](https://docs.astral.sh/uv/): its `package.json` scripts call uv, ruff, mypy, and pytest, so `pnpm dev`, `pnpm lint`, `pnpm typecheck`, and `pnpm test` run it like the other apps. The database schema and migrations stay in `packages/db`: run `pnpm db:migrate` against the production database before a new version starts. <!-- clubedge:only api=fastapi -->
 
 <!-- clubedge:end -->
 

package/template/_gitignore

@@ -25,3 +25,10 @@ supabase/.branches/
 # Build output of the Vercel and Netlify presets
 .vercel/
 .netlify/
+
+# Python apps
+.venv/
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

package/template/apps/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/api",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/api-fastapi/.env.example

@@ -0,0 +1,8 @@
+# The API. The frontend's dev server proxies /api here (its API_URL).
+HOST=127.0.0.1
+PORT=3001
+
+# PostgreSQL. `pnpm infra:up` starts one on this URL.
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres
+# Optional: the direct (unpooled) URL, for migrations behind a pooler.
+DATABASE_URL_DIRECT=

package/template/apps/api-fastapi/.python-version

@@ -0,0 +1 @@
+3.12

package/template/apps/api-fastapi/Dockerfile

@@ -0,0 +1,24 @@
+# Production image for the API. Build it from the repository root.
+# Generated projects keep the API in apps/api; the starter repository builds it with
+#   docker build -f apps/api-fastapi/Dockerfile --build-arg APP_DIR=apps/api-fastapi .
+# The database schema and its migrations live in packages/db: run `pnpm db:migrate` against
+# the production database before a new version starts.
+ARG APP_DIR=apps/api
+
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:0.13 /uv /uvx /bin/
+ARG APP_DIR
+WORKDIR /app
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never
+
+# Dependencies first, so their layer stays cached until pyproject.toml (or uv.lock) changes.
+COPY ${APP_DIR}/pyproject.toml ${APP_DIR}/uv.lock* ./
+RUN uv sync --no-dev --no-install-project
+COPY ${APP_DIR}/src ./src
+RUN uv sync --no-dev
+
+RUN useradd --system --uid 1001 app
+USER app
+ENV HOST=0.0.0.0 PORT=3001 PATH="/app/.venv/bin:$PATH"
+EXPOSE 3001
+CMD ["python", "-m", "clubedge_api"]

package/template/apps/api-fastapi/clubedge.stack.json

@@ -0,0 +1,39 @@
+{
+  "id": "fastapi",
+  "name": "FastAPI (Python)",
+  "role": "api",
+  "envExample": ".env.example",
+  "dockerfile": "Dockerfile",
+  "toolchain": {
+    "name": "uv",
+    "check": ["uv", "--version"],
+    "install": ["uv", "sync"],
+    "url": "https://docs.astral.sh/uv/getting-started/installation/"
+  },
+  "modules": {
+    "auth": {
+      "none": {}
+    },
+    "storage": {
+      "none": {}
+    },
+    "cache": {
+      "memory": {}
+    },
+    "email": {
+      "none": {}
+    },
+    "payments": {
+      "none": {}
+    },
+    "jobs": {
+      "none": {}
+    },
+    "observability": {
+      "none": {}
+    },
+    "deploy": {
+      "docker": {}
+    }
+  }
+}

package/template/apps/api-fastapi/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@clubedge/api-fastapi",
+  "version": "0.23.0",
+  "private": true,
+  "license": "Apache-2.0",
+  "type": "module",
+  "scripts": {
+    "dev": "uv run python -m clubedge_api --reload",
+    "build": "uv run python -m compileall -q src",
+    "start": "uv run python -m clubedge_api",
+    "lint": "uv run ruff check . && uv run ruff format --check .",
+    "typecheck": "uv run mypy",
+    "test": "uv run pytest && clubedge-contract-check -- uv run python -m clubedge_api",
+    "check:services": "uv run python -m clubedge_api.check_services",
+    "check:env": "uv run python -m clubedge_api.check_env"
+  },
+  "dependencies": {
+    "@clubedge/contract": "workspace:*"
+  }
+}

package/template/apps/api-fastapi/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "clubedge-api"
+version = "0.23.0"
+description = "The project's API, implementing packages/contract/openapi.yaml."
+requires-python = ">=3.12"
+dependencies = [
+  "fastapi==0.146.0",
+  "psycopg[binary]==3.3.6",
+  "uvicorn==0.54.0",
+]
+
+[dependency-groups]
+dev = [
+  "httpx==0.28.1",
+  "mypy==2.4.0",
+  "pytest==9.1.1",
+  "ruff==0.17.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/clubedge_api"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests"]
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/template/apps/api-fastapi/src/clubedge_api/__init__.py

@@ -0,0 +1 @@
+"""The project's API: a FastAPI app implementing packages/contract/openapi.yaml."""

package/template/apps/api-fastapi/src/clubedge_api/__main__.py

@@ -0,0 +1,16 @@
+"""Runs the API: `python -m clubedge_api`, with `--reload` in development."""
+
+import sys
+
+import uvicorn
+
+from clubedge_api.settings import get_settings
+
+if __name__ == "__main__":
+    settings = get_settings()
+    uvicorn.run(
+        "clubedge_api.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload="--reload" in sys.argv,
+    )

package/template/apps/api-fastapi/src/clubedge_api/app.py

@@ -0,0 +1,68 @@
+"""The routes, implementing packages/contract/openapi.yaml.
+
+They receive what they need from the composition root (server.py), so tests can pass stand-ins.
+"""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any, TypedDict
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException
+
+
+class User(TypedDict):
+    id: str
+    email: str
+    displayName: str | None
+
+
+@dataclass(frozen=True)
+class ApiDependencies:
+    service_id: str
+    is_ready: Callable[[], Awaitable[bool]]
+    get_current_user: Callable[[Request], Awaitable[User | None]]
+
+
+def error(code: str, message: str, status: int) -> JSONResponse:
+    return JSONResponse({"error": {"code": code, "message": message}}, status_code=status)
+
+
+def create_app(dependencies: ApiDependencies) -> FastAPI:
+    # The contract is openapi.yaml, so FastAPI's generated schema and docs are not served.
+    app = FastAPI(openapi_url=None, docs_url=None, redoc_url=None)
+
+    @app.get("/api/health")
+    async def health() -> dict[str, Any]:
+        return {
+            "status": "ok",
+            "service": dependencies.service_id,
+            "timestamp": datetime.now(UTC).isoformat(),
+        }
+
+    @app.get("/api/ready")
+    async def ready() -> JSONResponse:
+        is_ready = await dependencies.is_ready()
+        return JSONResponse(
+            {"status": "ok" if is_ready else "unavailable"},
+            status_code=200 if is_ready else 503,
+            headers={"Cache-Control": "no-store"},
+        )
+
+    @app.get("/api/session")
+    async def session(request: Request) -> dict[str, Any]:
+        return {"user": await dependencies.get_current_user(request)}
+
+    @app.exception_handler(HTTPException)
+    async def http_error(request: Request, exc: HTTPException) -> JSONResponse:
+        if exc.status_code == 404:
+            return error("not_found", "No such API endpoint.", 404)
+        return error("http_error", str(exc.detail), exc.status_code)
+
+    @app.exception_handler(Exception)
+    async def internal_error(request: Request, exc: Exception) -> JSONResponse:
+        return error("internal_error", "Something went wrong.", 500)
+
+    return app

package/template/apps/api-fastapi/src/clubedge_api/auth.py

@@ -0,0 +1,13 @@
+"""The signed-in user for a request.
+
+This API has no authentication module yet, so nobody is signed in; an auth provider replaces
+this module the way the full-stack apps' variants do.
+"""
+
+from fastapi import Request
+
+from clubedge_api.app import User
+
+
+async def get_current_user(request: Request) -> User | None:
+    return None

package/template/apps/api-fastapi/src/clubedge_api/check_env.py

@@ -0,0 +1,12 @@
+"""Validates the API's production environment before a deploy: `pnpm check:env`."""
+
+import sys
+
+from clubedge_api.settings import get_settings
+
+if __name__ == "__main__":
+    settings = get_settings()
+    if not settings.database_url:
+        print("DATABASE_URL is required.", file=sys.stderr)
+        sys.exit(1)
+    print("API environment is valid.")

package/template/apps/api-fastapi/src/clubedge_api/check_services.py

@@ -0,0 +1,18 @@
+"""Checks that the services the API needs answer: `pnpm check:services`."""
+
+import asyncio
+import sys
+
+from clubedge_api.db import is_database_ready
+from clubedge_api.settings import get_settings
+
+if __name__ == "__main__":
+    if asyncio.run(is_database_ready(get_settings().database_url)):
+        print("Database: reachable.")
+        sys.exit(0)
+    print(
+        "Database: not reachable. Check DATABASE_URL in apps/api/.env.local, "
+        "then start it (pnpm infra:up).",
+        file=sys.stderr,
+    )
+    sys.exit(1)

package/template/apps/api-fastapi/src/clubedge_api/db.py

@@ -0,0 +1,19 @@
+"""PostgreSQL readiness. The schema and its migrations live in packages/db (pnpm db:migrate)."""
+
+import asyncio
+
+import psycopg
+
+
+async def is_database_ready(url: str | None, timeout: float = 2.0) -> bool:
+    """Whether the database answers `select 1` in time; no URL is not ready either."""
+    if not url:
+        return False
+    try:
+        async with asyncio.timeout(timeout):
+            connection = await psycopg.AsyncConnection.connect(url, connect_timeout=2)
+            async with connection:
+                await connection.execute("select 1")
+        return True
+    except (OSError, TimeoutError, psycopg.Error):
+        return False

package/template/apps/api-fastapi/src/clubedge_api/main.py

@@ -0,0 +1,6 @@
+"""The ASGI app uvicorn serves: clubedge_api.main:app."""
+
+from clubedge_api.app import create_app
+from clubedge_api.server import dependencies
+
+app = create_app(dependencies())

package/template/apps/api-fastapi/src/clubedge_api/server.py

@@ -0,0 +1,31 @@
+"""The composition root: the only place that reads the environment and picks providers."""
+
+import json
+from pathlib import Path
+from typing import Any
+
+from clubedge_api.app import ApiDependencies
+from clubedge_api.auth import get_current_user
+from clubedge_api.db import is_database_ready
+from clubedge_api.settings import get_settings
+
+# create-clubedge-app names the project here, like the frontend's site config.
+SITE_CONFIG = Path(__file__).resolve().parents[1] / "config" / "site.json"
+
+
+def site_config() -> dict[str, Any]:
+    config: dict[str, Any] = json.loads(SITE_CONFIG.read_text(encoding="utf-8"))
+    return config
+
+
+def dependencies() -> ApiDependencies:
+    settings = get_settings()
+
+    async def is_ready() -> bool:
+        return await is_database_ready(settings.database_url)
+
+    return ApiDependencies(
+        service_id=str(site_config()["serviceId"]),
+        is_ready=is_ready,
+        get_current_user=get_current_user,
+    )

package/template/apps/api-fastapi/src/clubedge_api/settings.py

@@ -0,0 +1,35 @@
+"""The API's environment, read once. Locally, .env.local fills in what the shell doesn't set."""
+
+import os
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+
+
+def load_env_file(path: Path) -> None:
+    """Sets KEY=value lines from `path` that the environment doesn't already have."""
+    if not path.is_file():
+        return
+    for line in path.read_text(encoding="utf-8").splitlines():
+        key, sep, value = line.strip().partition("=")
+        if not sep or key.startswith("#"):
+            continue
+        os.environ.setdefault(key.strip(), value.strip().strip("\"'"))
+
+
+@dataclass(frozen=True)
+class Settings:
+    # The frontend proxies /api here in development; containers listen on every interface.
+    host: str
+    port: int
+    database_url: str | None
+
+
+@cache
+def get_settings() -> Settings:
+    load_env_file(Path(".env.local"))
+    return Settings(
+        host=os.environ.get("HOST") or "127.0.0.1",
+        port=int(os.environ.get("PORT") or "3001"),
+        database_url=os.environ.get("DATABASE_URL") or None,
+    )

package/template/apps/api-fastapi/src/config/site.json

@@ -0,0 +1,11 @@
+{
+  "name": "Clubedge Starter",
+  "shortName": "Clubedge",
+  "description": "A production-minded foundation for Clubedge applications.",
+  "serviceId": "clubedge-starter",
+  "workspaceLabel": "Starter workspace",
+  "links": {
+    "repository": "https://github.com/Clubedge/clubedge-starter",
+    "setupGuide": "https://github.com/Clubedge/clubedge-starter/blob/main/SETUP.md"
+  }
+}

package/template/apps/api-fastapi/tests/test_app.py

@@ -0,0 +1,46 @@
+"""The routes in process. The shared contract suite also runs against the live server
+(`pnpm test`, through clubedge-contract-check)."""
+
+from fastapi import Request
+from fastapi.testclient import TestClient
+
+from clubedge_api.app import ApiDependencies, User, create_app
+
+
+def client(ready: bool) -> TestClient:
+    async def is_ready() -> bool:
+        return ready
+
+    async def no_user(request: Request) -> User | None:
+        return None
+
+    return TestClient(create_app(ApiDependencies("my-product", is_ready, no_user)))
+
+
+def test_health_reports_the_service_and_the_time() -> None:
+    response = client(ready=False).get("/api/health")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["status"] == "ok"
+    assert body["service"] == "my-product"
+    assert body["timestamp"]
+
+
+def test_ready_matches_the_database_and_is_never_cached() -> None:
+    for ready, status, text in [(True, 200, "ok"), (False, 503, "unavailable")]:
+        response = client(ready).get("/api/ready")
+        assert response.status_code == status
+        assert response.json() == {"status": text}
+        assert "no-store" in response.headers["cache-control"]
+
+
+def test_session_has_no_user_when_signed_out() -> None:
+    response = client(ready=False).get("/api/session")
+    assert response.status_code == 200
+    assert response.json() == {"user": None}
+
+
+def test_unknown_paths_are_json_not_found_errors() -> None:
+    response = client(ready=False).get("/api/no-such-endpoint")
+    assert response.status_code == 404
+    assert response.json()["error"]["code"] == "not_found"

package/template/apps/start/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/start",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/vite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/vite",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/web",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "scripts": {

package/template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clubedge-starter-v1",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "packageManager": "pnpm@10.9.0",
@@ -11,7 +11,7 @@
     "dev": "turbo run dev --filter=@clubedge/web",
     "build": "turbo run build",
     "start": "turbo run start --env-mode=loose --filter=@clubedge/web",
-    "lint": "eslint .",
+    "lint": "eslint . && turbo run lint",
     "typecheck": "turbo run typecheck",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -21,7 +21,7 @@
     "db:studio": "pnpm --filter @clubedge/db db:studio",
     "db:check": "pnpm -r --if-present run db:check",
     "db:seed": "pnpm --filter @clubedge/db db:seed",
-    "test": "vitest run",
+    "test": "vitest run && turbo run test",
     "test:watch": "vitest",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",

package/template/packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/auth-appwrite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-appwrite",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Appwrite provider for @clubedge/auth, run from the server with an API key and session cookies.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-better-auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-better-auth",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Better Auth adapter for @clubedge/auth, storing users and sessions in your own PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-firebase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-firebase",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Firebase Authentication provider for @clubedge/auth, run from the server with session cookies.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/auth-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/auth-supabase",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Supabase Auth adapter for @clubedge/auth.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/cache-redis",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Redis rate limiter and cache for @clubedge/cache.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/contract/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@clubedge/contract",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
+  "bin": {
+    "clubedge-contract-check": "./scripts/check-api.mjs"
+  },
   "exports": {
     ".": "./src/index.ts",
     "./conformance": "./src/conformance.ts",

package/template/packages/contract/scripts/check-api.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Proves an API in any language against the contract: starts it, waits for /api/health, runs
+// the conformance suite over HTTP (src/remote.test.ts), and stops it. An API's test script:
+//
+//   clubedge-contract-check -- uv run python -m clubedge_api
+//
+// The API listens where HOST and PORT say; --port picks one that is free (default 3991).
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const windows = process.platform === "win32";
+const args = process.argv.slice(2);
+const separator = args.indexOf("--");
+const command = separator === -1 ? [] : args.slice(separator + 1);
+if (command.length === 0) {
+  console.error("Usage: clubedge-contract-check [--port <port>] -- <command that starts the API>");
+  process.exit(2);
+}
+const options = args.slice(0, separator);
+const port = options.includes("--port") ? options[options.indexOf("--port") + 1] : "3991";
+const url = `http://127.0.0.1:${port}`;
+// scripts/ → packages/contract → packages → the workspace root, where Vitest runs.
+const root = fileURLToPath(new URL("../../..", import.meta.url));
+
+const server = spawn(command[0], command.slice(1), {
+  env: { ...process.env, HOST: "127.0.0.1", PORT: port },
+  stdio: "inherit",
+  // Its own process group, so stopping it also stops what it started (uv, then python).
+  detached: !windows,
+  shell: windows,
+});
+
+function stop() {
+  if (server.exitCode !== null || server.pid === undefined) return;
+  if (windows) spawnSync("taskkill", ["/pid", String(server.pid), "/t", "/f"], { stdio: "ignore" });
+  else {
+    try {
+      process.kill(-server.pid, "SIGTERM");
+    } catch {
+      // Already gone.
+    }
+  }
+}
+process.on("exit", stop);
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => process.exit(130));
+}
+
+async function waitForHealth(timeoutMs = 90_000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (server.exitCode !== null)
+      throw new Error(`The API exited (${server.exitCode}) before it answered.`);
+    try {
+      const response = await fetch(`${url}/api/health`, { signal: AbortSignal.timeout(2_000) });
+      if (response.ok) return;
+    } catch {
+      // Not listening yet.
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+  throw new Error(`The API did not answer ${url}/api/health in time.`);
+}
+
+try {
+  await waitForHealth();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}
+
+const suite = spawnSync("pnpm", ["exec", "vitest", "run", "packages/contract/src/remote.test.ts"], {
+  cwd: root,
+  env: { ...process.env, API_URL: url },
+  stdio: "inherit",
+  shell: windows,
+});
+process.exit(suite.status ?? 1);

package/template/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/core",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/db",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/email/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Email interface, console and in-memory providers, and message templates.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-resend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-resend",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Resend provider for @clubedge/email, through Resend's HTTP API.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/email-smtp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/email-smtp",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "SMTP provider for @clubedge/email, for any SMTP server.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Background jobs interface: job definitions, a queue contract, and an in-memory queue.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-bullmq/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-bullmq",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "BullMQ provider for @clubedge/jobs: a job queue stored in Redis.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-inngest/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-inngest",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Inngest provider for @clubedge/jobs: jobs run by Inngest, which calls the app for each one.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/jobs-pg-boss/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/jobs-pg-boss",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "pg-boss provider for @clubedge/jobs: a job queue stored in the project's PostgreSQL.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/local-db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/local-db",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "PostgreSQL for development without Docker: PGlite served over the PostgreSQL protocol.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Observability interface: error reports and spans for @clubedge/core's telemetry hooks, and an in-memory provider for tests.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-otel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-otel",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "OpenTelemetry provider for @clubedge/observability: traces and error logs exported over OTLP to any collector.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/observability-sentry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/observability-sentry",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Sentry provider for @clubedge/observability: server and browser errors, traces, and source map uploads.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Provider-neutral payments: the PaymentProvider interface, billing logic, and subscription tables.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/payments-stripe/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/payments-stripe",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Stripe provider for @clubedge/payments: Checkout, the customer portal, and verified webhooks.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/packages/storage-s3/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-s3",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "S3-compatible adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/storage-supabase/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/storage-supabase",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Supabase Storage adapter for @clubedge/storage.",
   "private": true,
   "license": "Apache-2.0",

package/template/packages/ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/ui",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "Apache-2.0",
   "type": "module",

package/template/pnpm-lock.yaml

@@ -74,6 +74,12 @@ importers:
         specifier: ^5.9.2
         version: 5.9.3
 
+  apps/api-fastapi:
+    dependencies:
+      '@clubedge/contract':
+        specifier: workspace:*
+        version: link:../../packages/contract
+
   apps/start:
     dependencies:
       '@clubedge/auth':

package/template/turbo.json

@@ -13,6 +13,12 @@
       "cache": false,
       "persistent": true
     },
+    "lint": {
+      "outputs": []
+    },
+    "test": {
+      "cache": false
+    },
     "typecheck": {
       "dependsOn": ["^typecheck"],
       "outputs": []

package/template.lock.json

@@ -1,7 +1,7 @@
 {
   "repository": "Clubedge/clubedge-starter",
-  "ref": "v0.22.0",
-  "commit": "d0f3f9cdd4d568504cec4cf4681c7faf97842405",
+  "ref": "v0.23.0",
+  "commit": "0183d091b7bffac92cd0073f12b5329e96fc183f",
   "files": [
     ".dockerignore",
     ".env.example",
@@ -29,6 +29,24 @@
     "SECURITY.md",
     "SETUP.md",
     "SUPPORT.md",
+    "apps/api-fastapi/.env.example",
+    "apps/api-fastapi/.python-version",
+    "apps/api-fastapi/Dockerfile",
+    "apps/api-fastapi/clubedge.stack.json",
+    "apps/api-fastapi/package.json",
+    "apps/api-fastapi/pyproject.toml",
+    "apps/api-fastapi/src/clubedge_api/__init__.py",
+    "apps/api-fastapi/src/clubedge_api/__main__.py",
+    "apps/api-fastapi/src/clubedge_api/app.py",
+    "apps/api-fastapi/src/clubedge_api/auth.py",
+    "apps/api-fastapi/src/clubedge_api/check_env.py",
+    "apps/api-fastapi/src/clubedge_api/check_services.py",
+    "apps/api-fastapi/src/clubedge_api/db.py",
+    "apps/api-fastapi/src/clubedge_api/main.py",
+    "apps/api-fastapi/src/clubedge_api/server.py",
+    "apps/api-fastapi/src/clubedge_api/settings.py",
+    "apps/api-fastapi/src/config/site.json",
+    "apps/api-fastapi/tests/test_app.py",
     "apps/api/.env.example",
     "apps/api/Dockerfile",
     "apps/api/build.mjs",
@@ -344,6 +362,7 @@
     "packages/cache/tsconfig.json",
     "packages/contract/openapi.yaml",
     "packages/contract/package.json",
+    "packages/contract/scripts/check-api.mjs",
     "packages/contract/src/conformance.ts",
     "packages/contract/src/index.ts",
     "packages/contract/src/remote.test.ts",