@clubedge/create-clubedge-app 0.39.0 → 0.40.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to `create-clubedge-app` are documented here.
 
+## 0.40.0
+
+- **Every module on React + Vite with FastAPI**: default to Starter `v0.26.0` (#126). `--framework vite --api fastapi` now offers the module options Hono got in 0.39.0, each written in Python:
+  - `--storage s3` (or a local folder with `--infra local`) and `--storage supabase`.
+  - `--cache redis`, for the rate limits and cache.
+  - `--email smtp` and `--email resend`.
+  - `--observability otel` and `--observability sentry`, with browser error reporting.
+  - `--payments stripe`, on the same tables as the Hono API.
+  - `--jobs bullmq` and `--jobs inngest`. `--jobs pg-boss` is still refused for FastAPI: pg-boss has no Python version.
+  - The account settings page in full: display name, password change, and account deletion.
+  - New Vite + FastAPI projects get the same defaults as the other stacks: S3 storage, Redis cache, and SMTP email.
+  - Each module has its own uv dependency group: every project keeps the same `uv.lock`, and its production image installs only the selected modules' libraries.
+- Rendered Python files keep the two blank lines PEP 8 and `ruff format` want between top-level definitions when a conditional block is removed (#121). Generating FastAPI projects from Starter `v0.26.0` needs this release.
+- The README says the decoupled stacks with Hono support every module (#120).
+
 ## 0.39.0
 
 - **Every module on React + Vite with Hono**: default to Starter `v0.25.0` (#118). `--framework vite --api hono` now offers every module option the full-stack apps have, each running in the API with the matching UI in the frontend:

package/README.md

@@ -141,7 +141,7 @@ They meet at one HTTP contract, `packages/contract/openapi.yaml`: the frontend c
 
 With `--auth supabase`, the Vite app owns the browser session and attaches its access token to contract requests. Hono or FastAPI verifies that token with Supabase Auth and returns the contract's shared user shape. Configure `VITE_SUPABASE_URL`, `VITE_SUPABASE_PUBLISHABLE_KEY`, `SUPABASE_URL`, and `SUPABASE_PUBLISHABLE_KEY` in the generated env examples; no Supabase service-role key goes to the browser.
 
-The decoupled stacks support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache, any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
+With the Hono API, the decoupled stacks support every module option the full-stack frameworks do (since Starter v0.26.0), each running in the API with the matching UI in the frontend; with FastAPI, they support Supabase Auth, Better Auth, Firebase, Appwrite, or `none`, plus memory cache. Both work with any local infrastructure (the API's `apps/api/.env.local` holds `DATABASE_URL`, since the API owns the database), and Docker or Railway deployment. With Docker, `pnpm clubedge deploy` writes a `compose.yaml` that builds the frontend and API as separate services; copy the variables of `.env.example` and `apps/api/.env.example` to `.env.production`, fill in their values, and run `docker compose --env-file .env.production up --build -d`. The frontend's `VITE_*` values are build arguments, compiled into its bundle; with Better Auth, its Node server also gets the auth variables (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and the email settings). With Railway, deploy provisions a public frontend and a private API, wires the frontend proxy to the API, and runs migrations before releasing the API. See [docs/stack-packs.md](docs/stack-packs.md) for how stacks and deployment facts are described.
 
 ## Choosing modules
 
@@ -207,7 +207,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.25.0
+pnpm dlx @clubedge/create-clubedge-app my-app --ref v0.26.0
 pnpm dlx @clubedge/create-clubedge-app my-app --ref <commit-sha>
 
 # Test local Starter changes before releasing them
@@ -226,7 +226,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.25.0 # or a specific tag, branch, or commit
+pnpm dlx @clubedge/create-clubedge-app upgrade --ref v0.26.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.
@@ -337,27 +337,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.39.0
+create-clubedge-app v0.40.0
         |
         v
-Clubedge Starter v0.25.0
-commit 17f4e82dca42884e7bfc3c66991110d00c7428a8
+Clubedge Starter v0.26.0
+commit 7c01a0295bea53adc72bda5b843a478ddd04f892
 ```
 
 The current relationship is:
 
 | CLI release | Default Starter release | Meaning |
 | --- | --- | --- |
-| `create-clubedge-app@0.39.0` | `clubedge-starter@v0.25.0` | The CLI's required, tested default |
+| `create-clubedge-app@0.40.0` | `clubedge-starter@v0.26.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.25.0` tag is expected to resolve to commit
-`17f4e82dca42884e7bfc3c66991110d00c7428a8`. The CLI verifies this before
+The `v0.26.0` tag is expected to resolve to commit
+`7c01a0295bea53adc72bda5b843a478ddd04f892`. 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.25.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.26.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`.
 
@@ -412,7 +412,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.25.0`, and publish the Starter release.
+4. Commit `main`, create a release tag such as `v0.26.0`, and publish the Starter release.
 
 ### CLI maintainers
 
@@ -462,6 +462,7 @@ Each phase ends with a Starter release and a CLI release pinned to it. The full
 | 0.37.0 | v0.24.1 | An MCP server (capabilities, validate, plan, create) and an agent skill for coding agents |
 | 0.38.0 | v0.24.2 | Starter v0.24.2: Next.js security update (critical RCE advisories); database URLs, Neon, and deploy variables for a frontend and its API |
 | 0.39.0 | v0.25.0 | Starter v0.25.0: every module on React + Vite with Hono, and account settings on React + Vite |
+| 0.40.0 | v0.26.0 | Starter v0.26.0: every module on React + Vite with FastAPI (pg-boss excepted) |
 
 ## Community
 

package/dist/core/customize.js

@@ -229,8 +229,12 @@ export function applyConditionals(source, selection, path = "file") {
     if (!removed)
         return text;
     // A removed block can leave two blank lines in a row, or blank lines at the start or end of
-    // the file; formatted sources never have them.
-    const collapsed = text.replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+    // the file; formatted sources never have them. Python is the exception: two blank lines come
+    // before a top-level definition (PEP 8, which ruff format enforces), one inside indented code.
+    const squeezed = path.endsWith(".py")
+        ? text.replace(/\n{4,}/g, "\n\n\n").replace(/\n{3,}(?=[ \t])/g, "\n\n")
+        : text.replace(/\n{3,}/g, "\n\n");
+    const collapsed = squeezed.replace(/^\n+/, "");
     return source.endsWith("\n") ? collapsed.replace(/\n+$/, "\n") : collapsed;
 }
 /** Removes dependencies on workspace packages that were left out of the project. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clubedge/create-clubedge-app",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Create React apps from Clubedge Starter with a CLI or local MCP server.",
   "type": "module",
   "packageManager": "pnpm@10.9.0",
@@ -24,8 +24,8 @@
   },
   "clubedge": {
     "starterRepository": "Clubedge/clubedge-starter",
-    "starterRef": "v0.25.0",
-    "starterCommit": "17f4e82dca42884e7bfc3c66991110d00c7428a8"
+    "starterRef": "v0.26.0",
+    "starterCommit": "7c01a0295bea53adc72bda5b843a478ddd04f892"
   },
   "license": "Apache-2.0",
   "repository": {

package/template/README.md

@@ -68,8 +68,7 @@ Every combination in the CI matrix is generated as a real project and runs its f
 - Password reset by email, and email verification that can be required before sign-in. <!-- clubedge:only auth=better-auth && email!=none -->
 - Password reset by email, sent by Supabase. <!-- clubedge:only auth=supabase -->
 - An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none && framework!=vite -->
-- An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none && framework=vite && api=hono -->
-- An account settings page with password change; the FastAPI API does not keep display names or delete accounts yet. <!-- clubedge:only auth!=none && framework=vite && api=fastapi -->
+- An account settings page: display name, password change, and account deletion. <!-- clubedge:only auth!=none && framework=vite && api=hono|fastapi -->
 - Email over SMTP, for any provider or a local inbox; development prints emails to the server log until SMTP is configured. <!-- clubedge:only email=smtp -->
 - Email through Resend; development prints emails to the server log until the API key is set. <!-- clubedge:only email=resend -->
 - S3-compatible storage adapter for AWS S3, Cloudflare R2, and MinIO. <!-- clubedge:only storage=s3 -->

package/template/SETUP.md

@@ -72,7 +72,7 @@ The app is available at <http://localhost:3000>, the liveness endpoint at <http:
 
 Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase, and the publishable key is all sign-in needs. To let users delete their account from the settings page, also set `SUPABASE_SECRET_KEY` to a secret key from the same settings; it stays on the server, so never give it a `NEXT_PUBLIC_` prefix. <!-- clubedge:only framework=next -->
 Create or select a Supabase project and copy its URL and publishable key from the project's API settings into the Supabase variables above. Authentication runs on the server, which validates every user with Supabase, and the publishable key is all sign-in needs. To let users delete their account from the settings page, also set `SUPABASE_SECRET_KEY` to a secret key from the same settings; it stays on the server. <!-- clubedge:only framework=tanstack-start -->
-To let users delete their account from the settings page, set `SUPABASE_SECRET_KEY` in `apps/api/.env.local` to a secret key from the project's API settings; only the API uses it. <!-- clubedge:only framework=vite && api=hono -->
+To let users delete their account from the settings page, set `SUPABASE_SECRET_KEY` in `apps/api/.env.local` to a secret key from the project's API settings; only the API uses it. <!-- clubedge:only framework=vite && api=hono|fastapi -->
 
 In Supabase Auth URL configuration, add this redirect URL for local email confirmation and password reset links:
 
@@ -247,7 +247,7 @@ Use `rediss://` for TLS connections such as Upstash and `redis://` for an unencr
 
 Without `REDIS_URL`, the rate limiter and cache use process memory. Memory limits apply per server process, so configure Redis when you run several instances or serverless functions. Never commit a real Redis URL or password.
 
-The API's rate limits use Redis, so `REDIS_URL` belongs in `apps/api/.env.local` and on the API's service. A limit answers `429` with `Retry-After`; when Redis is unreachable, requests go through and the failure is reported. <!-- clubedge:only api=hono -->
+The API's rate limits use Redis, so `REDIS_URL` belongs in `apps/api/.env.local` and on the API's service. A limit answers `429` with `Retry-After`; when Redis is unreachable, requests go through and the failure is reported. <!-- clubedge:only api!=none -->
 
 <!-- clubedge:end -->
 <!-- clubedge:if cache=memory -->
@@ -262,7 +262,8 @@ The rate limiter and cache keep their state in process memory, which suits a sin
 ## Email
 
 The app sends email through the `EmailProvider` in `apps/web/src/server/email.ts`. Server code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`. <!-- clubedge:only api=none -->
-The API sends email through the `EmailProvider` in `apps/api/src/server/email.ts`: its code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`. <!-- clubedge:only api!=none -->
+The API sends email through the `EmailProvider` in `apps/api/src/server/email.ts`: its code imports `email` from `@/server/email` and calls `email.send({ to, subject, text, html })`. <!-- clubedge:only api=hono -->
+The API sends email through the `EmailProvider` in `apps/api/src/clubedge_api/email.py`: its code imports `email` from `clubedge_api.email` and awaits `email.send({"to": ..., "subject": ..., "text": ..., "html": ...})`. <!-- clubedge:only api=fastapi -->
 Better Auth runs in the frontend's server (`apps/web/auth.server.mjs`), which sends its emails with the same provider, so set the email variables in both `apps/web/.env.local` and `apps/api/.env.local`. <!-- clubedge:only api!=none && auth=better-auth -->
 
 <!-- clubedge:end -->
@@ -287,12 +288,13 @@ Without a provider configured, development prints each email to the server log,
 
 The plans users can buy are in `apps/web/src/config/plans.ts`, with the app's own ids. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management. Server code reads a user's plan with `getBilling().subscriptionFor(userId)` and `isEntitled` from `@/server/payments`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`. <!-- clubedge:only api=none -->
 The plans users can buy are in `apps/api/src/config/plans.ts`, with the app's own ids, and the API serves them at `/api/billing`. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management; checkout and the portal send the user back to `FRONTEND_URL`. API code reads a user's plan with `getBilling().subscriptionFor(await getUserProfileId(user))` and `isEntitled` from `@/server/payments` and `@/server/users`, and the `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`, which the frontend forwards to the API. <!-- clubedge:only api=hono -->
+The plans users can buy are in `apps/api/src/clubedge_api/plans.py`, with the app's own ids, and the API serves them at `/api/billing`. The dashboard's billing card offers checkout for each plan, then shows the subscription and opens billing management; checkout and the portal send the user back to `FRONTEND_URL`. API code checks a user's plan with `has_active_subscription(await ensure_user_id(user))` from `clubedge_api.payments` and `clubedge_api.users`, or reads it with `find_subscription` and `is_entitled`. The `subscriptions` table keeps it in sync through the provider's webhook at `/api/webhooks/payments`, which the frontend forwards to the API; its tables and migrations are those of `packages/payments`, applied by `pnpm db:migrate` and by the image's `node migrate.mjs`. <!-- clubedge:only api=fastapi -->
 
 <!-- clubedge:end -->
 <!-- clubedge:if payments=stripe -->
 
 [Stripe](https://stripe.com) runs checkout and billing management. In test mode: <!-- clubedge:only api=none -->
-[Stripe](https://stripe.com) runs checkout and billing management. The Stripe variables go in `apps/api/.env.local`. In test mode: <!-- clubedge:only api=hono -->
+[Stripe](https://stripe.com) runs checkout and billing management. The Stripe variables go in `apps/api/.env.local`. In test mode: <!-- clubedge:only api!=none -->
 
 1. Copy the secret key from the dashboard's API keys into `STRIPE_SECRET_KEY`.
 2. Create a recurring price for each plan and put its id in `STRIPE_PRICE_<PLAN>`, such as `STRIPE_PRICE_PRO`.
@@ -302,7 +304,7 @@ The plans users can buy are in `apps/api/src/config/plans.ts`, with the app's ow
 stripe listen --forward-to localhost:3000/api/webhooks/payments
 ```
 
-The Stripe CLI posts to the frontend on port 3000, which forwards the webhook, body untouched, to the API; the API itself stays private. <!-- clubedge:only api=hono -->
+The Stripe CLI posts to the frontend on port 3000, which forwards the webhook, body untouched, to the API; the API itself stays private. <!-- clubedge:only api!=none -->
 
 Turn on the customer portal in the dashboard's billing settings, so "Manage billing" works. In production, add a webhook endpoint for `https://<your-domain>/api/webhooks/payments` with the events `checkout.session.completed` and `customer.subscription.created`, `.updated`, `.deleted`, `.paused`, and `.resumed`, and use its signing secret. Every webhook's signature is verified, each event is applied once, and subscription events read the subscription's current state from Stripe, so retried or out-of-order deliveries are safe.
 
@@ -311,6 +313,7 @@ Turn on the customer portal in the dashboard's billing settings, so "Manage bill
 
 Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/web/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same. <!-- clubedge:only api=none -->
 Payments go through the provider-neutral `PaymentProvider` interface in `packages/payments`. To use another provider, implement that interface in a new package and return it from `apps/api/src/server/payments.ts`; billing logic, the tables, the routes, and the billing card stay the same. <!-- clubedge:only api=hono -->
+Payments go through the provider-neutral `PaymentProvider` protocol in `apps/api/src/clubedge_api/payments.py`, which follows `packages/payments` and reads and writes the same tables. To use another provider, implement that protocol in a new module and build its `Billing` in place of `stripe_billing` (`apps/api/src/clubedge_api/payments_stripe.py`); billing logic, the tables, the routes, and the billing card stay the same. <!-- clubedge:only api=fastapi -->
 
 <!-- clubedge:end -->
 <!-- clubedge:if jobs!=none -->
@@ -320,12 +323,16 @@ Payments go through the provider-neutral `PaymentProvider` interface in `package
 Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the app starts. <!-- clubedge:only jobs=pg-boss && api=none -->
 Jobs run outside requests, with retries, in a worker that starts inside the API: `pnpm dev` and the API's production server both run it, so there is no separate process to deploy. [pg-boss](https://github.com/timgit/pg-boss) stores them in your PostgreSQL, and creates and upgrades its own tables in the `pgboss` schema when the API starts. <!-- clubedge:only jobs=pg-boss && api=hono -->
 Jobs run outside requests, with retries, in a worker that starts inside the app server: `pnpm dev` and the production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq && api=none -->
-Jobs run outside requests, with retries, in a worker that starts inside the API: `pnpm dev` and the API's production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL` in `apps/api/.env.local`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq && api=hono -->
+Jobs run outside requests, with retries, in a worker that starts inside the API: `pnpm dev` and the API's production server both run it, so there is no separate process to deploy. [BullMQ](https://docs.bullmq.io) stores them in Redis (`REDIS_URL` in `apps/api/.env.local`, Redis 6.2 or newer), which the cache also uses; keep it on a Redis that doesn't evict keys, since jobs are data. <!-- clubedge:only jobs=bullmq && api=hono|fastapi -->
 [Inngest](https://www.inngest.com) runs the jobs: the app sends an event for each one, and Inngest calls the app's `/api/inngest` to run it, with retries and schedules, so nothing runs between requests and serverless hosts need no cron. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` points the app at it. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`, remove `INNGEST_DEV`, and sync the deployed `/api/inngest` URL in Inngest's dashboard (Inngest's Vercel and Netlify integrations do it on each deploy). <!-- clubedge:only jobs=inngest && api=none -->
-[Inngest](https://www.inngest.com) runs the jobs: the API sends an event for each one, and Inngest calls `/api/inngest` to run it, with retries and schedules. Inngest reaches the API through the frontend, which forwards `/api/inngest` to it, so the API stays private; the API tells Inngest its address from `FRONTEND_URL`. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` in `apps/api/.env.local` points the API at it, and the API syncs its jobs once the frontend answers. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY` on the API, remove `INNGEST_DEV`, and sync `https://<your-frontend>/api/inngest` in Inngest's dashboard. <!-- clubedge:only jobs=inngest && api=hono -->
+[Inngest](https://www.inngest.com) runs the jobs: the API sends an event for each one, and Inngest calls `/api/inngest` to run it, with retries and schedules. Inngest reaches the API through the frontend, which forwards `/api/inngest` to it, so the API stays private; the API tells Inngest its address from `FRONTEND_URL`. In development, start Inngest's Dev Server next to `pnpm dev` with `pnpm jobs:dev`, and open its dashboard at <http://localhost:8288> to see every run; `INNGEST_DEV=1` in `apps/api/.env.local` points the API at it, and the API syncs its jobs once the frontend answers. In production, create an app in Inngest, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY` on the API, remove `INNGEST_DEV`, and sync `https://<your-frontend>/api/inngest` in Inngest's dashboard. <!-- clubedge:only jobs=inngest && api=hono|fastapi -->
 
 Define a job in `apps/web/src/jobs` and add it to the list in `apps/web/src/jobs/index.ts`: <!-- clubedge:only api=none -->
 Define a job in `apps/api/src/jobs` and add it to the list in `apps/api/src/jobs/index.ts`: <!-- clubedge:only api=hono -->
+Define a job in `apps/api/src/clubedge_api/jobs.py` and add it to `JOBS` there: <!-- clubedge:only api=fastapi -->
+
+<!-- clubedge:end -->
+<!-- clubedge:if jobs!=none && api!=fastapi -->
 
 ```ts
 import { defineJob } from "@clubedge/jobs";
@@ -339,20 +346,41 @@ export const welcomeEmail = defineJob<{ userId: string }>({
 });
 ```
 
+<!-- clubedge:end -->
+<!-- clubedge:if jobs!=none && api=fastapi -->
+
+```python
+async def _welcome_email(data: JobData, context: JobContext) -> None:
+    # Look the user up by data["userId"] and send the email.
+    ...
+
+welcome_email = JobDefinition(name="welcome-email", run=_welcome_email, retry_limit=3)
+```
+
+<!-- clubedge:end -->
+<!-- clubedge:if jobs!=none -->
+
 Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message, as the auth emails do. <!-- clubedge:only email!=none && api=none -->
 Queue it from the API's code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. To send any email in the background, enqueue `sendEmailJob` from `@/jobs` with the message. <!-- clubedge:only email!=none && api=hono -->
 Queue it from server code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none && api=none -->
 Queue it from the API's code with `getJobs().enqueue(welcomeEmail, { userId })`, from `@/server/jobs`. <!-- clubedge:only email=none && api=hono -->
+Queue it from the API's code with `await get_jobs().enqueue(welcome_email, {"userId": user_id})`, from `clubedge_api.background_jobs`. To send any email in the background, enqueue `send_email_job` from `clubedge_api.jobs` with the message. <!-- clubedge:only email!=none && api=fastapi -->
+Queue it from the API's code with `await get_jobs().enqueue(welcome_email, {"userId": user_id})`, from `clubedge_api.background_jobs`. <!-- clubedge:only email=none && api=fastapi -->
 
 A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart `pnpm dev` after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/web/src/jobs/sample.ts` and lists its recent runs; remove both when you add your own. <!-- clubedge:only api=none -->
 A thrown error fails the attempt and the job is retried (`retryLimit`, `retryDelaySeconds`, `retryBackoff`). An attempt that runs past `timeoutSeconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule: "0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart the API after adding or changing a job. The dashboard's jobs card queues the sample job from `apps/api/src/jobs/sample.ts` through `/api/jobs` and lists its recent runs; remove both when you add your own. <!-- clubedge:only api=hono -->
+A raised exception fails the attempt and the job is retried (`retry_limit`, `retry_delay_seconds`, `retry_backoff`). An attempt that runs past `timeout_seconds`, or whose server stops, is retried too, so make jobs safe to run twice. Add `schedule="0 3 * * *"` (cron syntax, UTC) to run a job on a schedule. Restart the API after adding or changing a job. The dashboard's jobs card queues `sample_job` from `apps/api/src/clubedge_api/jobs.py` through `/api/jobs` and lists its recent runs; remove both when you add your own. <!-- clubedge:only api=fastapi -->
 
 Where no server keeps running, as on Vercel and Netlify, there is no worker: `JOBS_WORKER` defaults to `off` there, and you can set it yourself anywhere. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` every minute or so with the header `Authorization: Bearer <CRON_SECRET>`, from Vercel Cron, a Netlify scheduled function, or any scheduler. Each call runs the jobs that are due. <!-- clubedge:only jobs=pg-boss|bullmq && api=none -->
-To run the jobs elsewhere, set `JOBS_WORKER=off` on the API: it then runs no worker. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` on the frontend, which forwards it to the API, every minute or so with the header `Authorization: Bearer <CRON_SECRET>`. Each call runs the jobs that are due. The API stops its worker on `SIGTERM`, letting running jobs finish. <!-- clubedge:only jobs=pg-boss|bullmq && api=hono -->
+To run the jobs elsewhere, set `JOBS_WORKER=off` on the API: it then runs no worker. Set `CRON_SECRET` to 16 or more random characters and call `GET /api/jobs/run` on the frontend, which forwards it to the API, every minute or so with the header `Authorization: Bearer <CRON_SECRET>`. Each call runs the jobs that are due. The API stops its worker on `SIGTERM`, letting running jobs finish. <!-- clubedge:only jobs=pg-boss|bullmq && api=hono|fastapi -->
 Inngest keeps the job history: the jobs card reads it from Inngest's API (the Dev Server's locally), and Inngest's dashboard shows each run's attempts, output, and errors. <!-- clubedge:only jobs=inngest -->
 
 Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/web/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do: <!-- clubedge:only api=none -->
 Jobs go through the provider-neutral `JobQueue` interface in `packages/jobs`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs pg-boss`, `bullmq`, or `inngest`. To add another, implement `JobQueue` in a new package, return it from `apps/api/src/server/jobs.ts`, and prove it with the shared conformance suite, as each provider's tests do: <!-- clubedge:only api=hono -->
+Jobs go through the provider-neutral `JobQueue` protocol in `apps/api/src/clubedge_api/job_queue.py`, so job definitions, the routes, and the jobs card stay the same whichever provider runs them. Switch providers with `pnpm clubedge add jobs bullmq` or `inngest`; pg-boss, which the TypeScript stacks offer, is not available with the FastAPI API. To add another, implement `JobQueue` in a new module and return it from `apps/api/src/clubedge_api/background_jobs.py`. <!-- clubedge:only api=fastapi -->
+
+<!-- clubedge:end -->
+<!-- clubedge:if jobs!=none && api!=fastapi -->
 
 ```ts
 import { describeJobQueue } from "@clubedge/jobs/conformance";
@@ -385,7 +413,8 @@ docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:latest
 
 Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. The spans Next.js and pg-boss create join the same traces. <!-- clubedge:only framework=next -->
 Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` to its DSN. `SENTRY_TRACES_SAMPLE_RATE` is the share of requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=tanstack-start -->
-Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` in `apps/api/.env.local` to its DSN; the frontend reads it from the API at runtime. `SENTRY_TRACES_SAMPLE_RATE` is the share of API requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=vite -->
+Create a Node.js project in [Sentry](https://sentry.io) and set `SENTRY_DSN` in `apps/api/.env.local` to its DSN; the frontend reads it from the API at runtime. `SENTRY_TRACES_SAMPLE_RATE` is the share of API requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies. <!-- clubedge:only framework=vite && api=hono -->
+Create a Python project in [Sentry](https://sentry.io) and set `SENTRY_DSN` in `apps/api/.env.local` to its DSN; the frontend reads it from the API at runtime. `SENTRY_TRACES_SAMPLE_RATE` is the share of API requests traced, from 0 to 1 (default 0.1; use 1 while trying it out), and `SENTRY_ENVIRONMENT` labels events (default `NODE_ENV`). The SDK sends no user details, cookies, query strings, or request bodies, and its integrations trace what FastAPI, httpx, and Redis do in the same traces. <!-- clubedge:only api=fastapi -->
 
 To see your own code in browser stack traces, give the build `SENTRY_AUTH_TOKEN` (an auth token with the `project:releases` scope), `SENTRY_ORG`, and `SENTRY_PROJECT`. The build then makes source maps for the browser bundle, uploads them to Sentry, and deletes them, so they are never served. Without the token the build makes no source maps. Set the three variables where the build runs: in CI, or as build-time variables on your platform. <!-- clubedge:only framework!=vite -->
 The React + Vite build does not upload source maps to Sentry yet, so browser stack traces point into the minified bundle. <!-- clubedge:only framework=vite -->
@@ -399,6 +428,7 @@ On Vercel and Netlify, a function can stop right after it responds, so spans sti
 
 Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/web/src/server/observability.ts`; error reports and spans across the app stay the same. <!-- clubedge:only api=none -->
 Observability goes through the provider-neutral `ObservabilityProvider` interface in `packages/observability` and the telemetry hooks in `@clubedge/core`. To use another tool, implement that interface in a new package and install it from `apps/api/src/server/observability.ts`; error reports and spans across the API stay the same. The API stops taking requests on `SIGTERM` and sends what is still buffered before it exits. <!-- clubedge:only api=hono -->
+Observability goes through the `Observability` protocol in `apps/api/src/clubedge_api/telemetry.py`: each API request is traced (`tracing.py`), and every error the API logs at the `ERROR` level, such as with `logger.exception(...)`, reaches the provider, with the `extra` it was logged with as its attributes. To use another tool, implement that protocol and start it from `apps/api/src/clubedge_api/observability.py`; error reports and spans across the API stay the same. The API stops taking requests on `SIGTERM` and sends what is still buffered before it exits. <!-- clubedge:only api=fastapi -->
 
 <!-- clubedge:end -->
 <!-- clubedge:if storage!=none -->
@@ -421,6 +451,12 @@ The storage adapter uses Supabase Storage through the signed-in user's Supabase
 The API holds the storage adapter: set its variables in `apps/api/.env.local`, and in a route call `getStorage(c.req.raw)` from `apps/api/src/server/storage.ts`. `pnpm check:services` uploads, reads back, and deletes a test file. <!-- clubedge:only storage=s3 -->
 The API holds the storage adapter: set `SUPABASE_STORAGE_BUCKET` in `apps/api/.env.local`, and in a route call `getStorage(c.req.raw)` from `apps/api/src/server/storage.ts`. It acts as the user whose Supabase access token the request carries (the `Authorization: Bearer` header the frontend sends), and as anonymous without one. <!-- clubedge:only storage=supabase -->
 
+<!-- clubedge:end -->
+<!-- clubedge:if storage!=none && api=fastapi -->
+
+The API holds the storage adapter: set its variables in `apps/api/.env.local`, and in a route call `get_storage(request)` from `apps/api/src/clubedge_api/storage.py`, then await its `upload`, `download`, `delete`, `exists`, or `get_signed_url`. `pnpm check:services` uploads, reads back, and deletes a test file. <!-- clubedge:only storage=s3 -->
+The API holds the storage adapter: set `SUPABASE_STORAGE_BUCKET` in `apps/api/.env.local`, and in a route call `get_storage(request)` from `apps/api/src/clubedge_api/storage.py`, then await its `upload`, `download`, `delete`, `exists`, or `get_signed_url`. It acts as the user whose Supabase access token the request carries (the `Authorization: Bearer` header the frontend sends), and as anonymous without one. <!-- clubedge:only storage=supabase -->
+
 <!-- clubedge:end -->
 <!-- clubedge:if storage!=none -->
 
@@ -646,8 +682,7 @@ API_URL=http://127.0.0.1:3001 pnpm exec vitest run packages/contract/src/remote.
 
 Some endpoints are an optional part of a module, a capability (`x-clubedge-capability` in `openapi.yaml`): the account settings page's display name and account deletion are the `account` capability of the auth module. An API without a capability answers its endpoints with 404, and the suite checks that unless `API_CAPABILITIES` lists it (such as `API_CAPABILITIES=account`).
 
-The settings page changes passwords with the auth provider, in the browser or in Better Auth's server, which signs out the user's other sessions and applies the provider's rate limits. The display name and account deletion go through the API, which keeps the app's data: deletion checks the password (10 tries a minute per user, refused while the limit cannot be checked), removes the user's app data, then deletes the user from the provider. <!-- clubedge:only auth!=none && api=hono -->
-The FastAPI API does not implement the `account` capability yet, so the settings page offers only the password change. <!-- clubedge:only auth!=none && api=fastapi -->
+The settings page changes passwords with the auth provider, in the browser or in Better Auth's server, which signs out the user's other sessions and applies the provider's rate limits. The display name and account deletion go through the API, which keeps the app's data: deletion checks the password (10 tries a minute per user, refused while the limit cannot be checked), removes the user's app data, then deletes the user from the provider. <!-- clubedge:only auth!=none && api=hono|fastapi -->
 
 In production, run each app's image: `apps/vite/Dockerfile` (the frontend, served by Node with `API_URL` set to the API's address) and the selected API image (`apps/api/Dockerfile` or `apps/api-fastapi/Dockerfile`). `docker compose up --build` runs both.
 

package/template/apps/api/package.json

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

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

@@ -21,6 +21,8 @@ DATABASE_URL_DIRECT=
 # clubedge:if auth=supabase
 SUPABASE_URL=
 SUPABASE_PUBLISHABLE_KEY=
+# Optional: the project's secret key (server-side only), which deleting accounts needs.
+SUPABASE_SECRET_KEY=
 # clubedge:end
 
 # Firebase Authentication. The Firebase API key is public; no service account is needed here.
@@ -34,9 +36,107 @@ FIREBASE_API_KEY=
 # clubedge:if auth=appwrite
 APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
 APPWRITE_PROJECT_ID=
+# Optional: an API key with the sessions.write and users.write scopes, to delete accounts.
+APPWRITE_API_KEY=
 # clubedge:end
 
 # Better Auth service origin (the frontend origin when it hosts /api/auth).
 # clubedge:if auth=better-auth
 BETTER_AUTH_URL=http://localhost:3000
 # clubedge:end
+
+# clubedge:if cache=redis
+# Optional rate limits and cache (Redis protocol; rediss:// enables TLS). Without it, both use
+# process memory. Upstash example: rediss://default:YOUR_PASSWORD@your-database.upstash.io:6379
+REDIS_URL= # clubedge:only infra!=docker
+REDIS_URL=redis://localhost:6379 # clubedge:only infra=docker
+# clubedge:end
+
+# clubedge:if storage=s3
+# S3-compatible storage (AWS S3, Cloudflare R2, MinIO)
+STORAGE_BUCKET= # clubedge:only infra!=docker
+STORAGE_REGION=auto # clubedge:only infra!=docker
+STORAGE_ENDPOINT= # clubedge:only infra!=docker
+STORAGE_ACCESS_KEY_ID= # clubedge:only infra!=docker
+STORAGE_SECRET_ACCESS_KEY= # clubedge:only infra!=docker
+# Local S3-compatible storage from docker-compose.dev.yml; it accepts any credentials. # clubedge:only infra=docker
+STORAGE_BUCKET=app # clubedge:only infra=docker
+STORAGE_REGION=us-east-1 # clubedge:only infra=docker
+STORAGE_ENDPOINT=http://localhost:9090 # clubedge:only infra=docker
+STORAGE_ACCESS_KEY_ID=local # clubedge:only infra=docker
+STORAGE_SECRET_ACCESS_KEY=local-secret # clubedge:only infra=docker
+STORAGE_PUBLIC_URL=
+# Without an S3 service, files are stored in this folder (relative to the API). # clubedge:only infra=local
+STORAGE_DIRECTORY=../../.data/storage # clubedge:only infra=local
+# clubedge:end
+
+# clubedge:if storage=supabase
+# Supabase Storage bucket, accessed as the user whose access token the request carries
+SUPABASE_STORAGE_BUCKET= # clubedge:only infra!=supabase
+SUPABASE_STORAGE_BUCKET=app # clubedge:only infra=supabase
+# clubedge:end
+
+# clubedge:if email=smtp
+# Email over SMTP: any provider's SMTP endpoint (smtps:// for TLS). Without it, development
+# prints emails to the server log and production refuses to send.
+SMTP_URL= # clubedge:only infra!=docker|supabase
+# Mailpit from docker-compose.dev.yml; read the emails at http://localhost:8025. # clubedge:only infra=docker
+SMTP_URL=smtp://localhost:1025 # clubedge:only infra=docker
+# The local Supabase inbox; read the emails at http://127.0.0.1:54324. # clubedge:only infra=supabase
+SMTP_URL=smtp://127.0.0.1:54325 # clubedge:only infra=supabase
+EMAIL_FROM=App <no-reply@example.com>
+# clubedge:end
+
+# clubedge:if email=resend
+# Resend (https://resend.com). EMAIL_FROM must use a domain verified in Resend. Without the
+# key, development prints emails to the server log and production refuses to send.
+RESEND_API_KEY=
+EMAIL_FROM=App <no-reply@example.com>
+# clubedge:end
+
+# clubedge:if payments=stripe
+# Stripe (https://dashboard.stripe.com/apikeys): use test-mode keys during development. The
+# webhook secret comes from `stripe listen` locally, or from the endpoint's settings in production;
+# Stripe calls the webhook through the frontend, at FRONTEND_URL/api/webhooks/payments.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+# The Stripe price for each plan in src/clubedge_api/plans.py (STRIPE_PRICE_<PLAN>).
+STRIPE_PRICE_PRO=
+# Tests can send Stripe API requests to a stand-in, such as stripe-mock or the fake in
+# e2e/stripe-fake.ts: STRIPE_API_BASE=http://127.0.0.1:12111. Leave it unset otherwise.
+# clubedge:end
+
+# clubedge:if jobs=bullmq
+# Background jobs are stored in Redis (REDIS_URL) through BullMQ and run by a worker inside the
+# API. JOBS_WORKER=off turns the worker off; a scheduler then calls /api/jobs/run with CRON_SECRET
+# (16 or more characters) instead.
+JOBS_WORKER=
+CRON_SECRET=
+# clubedge:end
+
+# clubedge:if jobs=inngest
+# Background jobs run by Inngest (https://www.inngest.com), which calls /api/inngest through the
+# frontend (FRONTEND_URL above), so the API stays private. In development, start its Dev Server
+# with pnpm jobs:dev (http://localhost:8288); INNGEST_DEV=1 points the API at it. In production,
+# remove INNGEST_DEV and set the keys of your Inngest app.
+INNGEST_DEV=1
+INNGEST_EVENT_KEY=
+INNGEST_SIGNING_KEY=
+# clubedge:end
+
+# clubedge:if observability=otel
+# OpenTelemetry: where traces and error logs go over OTLP/HTTP, such as a collector, Grafana
+# Cloud, or Honeycomb. Empty sends nothing. Headers are key=value pairs separated by commas.
+OTEL_EXPORTER_OTLP_ENDPOINT=
+OTEL_EXPORTER_OTLP_HEADERS=
+OTEL_SERVICE_NAME=
+# clubedge:end
+
+# clubedge:if observability=sentry
+# Sentry (https://sentry.io): the DSN from the project's Client Keys settings. Empty sends nothing.
+# The browser reads it from the API at runtime. The traces sample rate is the share of requests
+# traced, from 0 to 1 (default 0.1).
+SENTRY_DSN=
+SENTRY_ENVIRONMENT=
+SENTRY_TRACES_SAMPLE_RATE=
+# clubedge:end

package/template/apps/api-fastapi/Dockerfile

@@ -22,17 +22,28 @@ 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.
+# Dependencies first, so their layers stay cached until pyproject.toml (or uv.lock) changes: the
+# API's own, then the dependency group (pyproject.toml) of each module option the project uses.
+# The development tools stay out of the image.
 COPY ${APP_DIR}/pyproject.toml ${APP_DIR}/uv.lock ./
-RUN uv sync --locked --no-dev --no-install-project
+RUN uv sync --locked --no-default-groups --no-install-project
+RUN uv sync --locked --no-default-groups --group storage-s3 --inexact --no-install-project # clubedge:only storage=s3
+RUN uv sync --locked --no-default-groups --group cache-redis --inexact --no-install-project # clubedge:only cache=redis
+RUN uv sync --locked --no-default-groups --group email-smtp --inexact --no-install-project # clubedge:only email=smtp
+RUN uv sync --locked --no-default-groups --group observability-otel --inexact --no-install-project # clubedge:only observability=otel
+RUN uv sync --locked --no-default-groups --group observability-sentry --inexact --no-install-project # clubedge:only observability=sentry
+RUN uv sync --locked --no-default-groups --group payments-stripe --inexact --no-install-project # clubedge:only payments=stripe
+RUN uv sync --locked --no-default-groups --group jobs-bullmq --inexact --no-install-project # clubedge:only jobs=bullmq
+RUN uv sync --locked --no-default-groups --group jobs-inngest --inexact --no-install-project # clubedge:only jobs=inngest
 COPY ${APP_DIR}/src ./src
-RUN uv sync --locked --no-dev
+# --inexact keeps the groups installed above.
+RUN uv sync --locked --no-default-groups --inexact
 
 # Bundle the shared Node migrator so deploy platforms can run it before release.
 COPY --from=migrator-builder /tmp/.migrator/ ./
 
 RUN useradd --system --uid 1001 app
 USER app
-ENV HOST=0.0.0.0 PORT=3001 PATH="/app/.venv/bin:$PATH"
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=3001 PATH="/app/.venv/bin:$PATH"
 EXPOSE 3001
 CMD ["python", "-m", "clubedge_api"]