diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 00000000..470dc845
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,3 @@
+docs/ export-ignore
+zensical.toml export-ignore
+.github/ISSUE_TEMPLATE/ export-ignore
diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml
index e12a747a..cf4670bd 100644
--- a/.github/workflows/linting.yml
+++ b/.github/workflows/linting.yml
@@ -28,7 +28,13 @@ jobs:
- name: Ruff check
# --no-sync skips uv run's implicit sync: the step above already installed
# every member and extra, and skipping it keeps each step from re-resolving.
- run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools
+ run: uv run --no-sync ruff check backend/src backend/tests backend/scripts backend/migrations blueprint/tests
- name: Ruff format
- run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations cli/src cli/tests tools
+ run: uv run --no-sync ruff format --check backend/src backend/tests backend/scripts backend/migrations blueprint/tests
+
+ - name: Wiring in sync
+ run: uv run --no-sync fastro sync --check
+
+ - name: Blueprint lint
+ run: uv run --no-sync fastro blueprint lint
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 1c94f005..b0f469aa 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -31,10 +31,10 @@ jobs:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only
- - name: Pytest (cli)
- run: cd cli && uv run --no-sync pytest
+ - name: Pytest (blueprint)
+ run: uv run --no-sync pytest blueprint/tests
- removal-drills:
+ verify:
runs-on: ubuntu-latest
strategy:
fail-fast: false
@@ -48,6 +48,9 @@ jobs:
- accounts-api-keys
- accounts-rbac-tiers
- accounts-cache-taskiq
+ - minimal
+ - standard
+ - full
- everything
steps:
- uses: actions/checkout@v4
@@ -64,8 +67,5 @@ jobs:
- name: Sync workspace
run: uv sync --all-packages --all-extras --locked --python 3.11
- - name: Removal drill
- run: uv run --no-sync python tools/removal_drill.py ${{ matrix.preset }}
- env:
- ENVIRONMENT: local
- SECRET_KEY: test-secret-key-for-testing-only
+ - name: Verify
+ run: uv run --no-sync fastro blueprint verify ${{ matrix.preset }}
diff --git a/.github/workflows/type-checking.yml b/.github/workflows/type-checking.yml
index 56698fda..dae60fa6 100644
--- a/.github/workflows/type-checking.yml
+++ b/.github/workflows/type-checking.yml
@@ -29,14 +29,8 @@ jobs:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only
- - name: Mypy (cli)
- run: cd cli && uv run --no-sync mypy -p cli
- env:
- ENVIRONMENT: local
- SECRET_KEY: test-secret-key-for-testing-only
-
- - name: Mypy (tools)
- run: uv run --no-sync mypy tools
+ - name: Mypy (blueprint tests)
+ run: uv run --no-sync mypy blueprint/tests
env:
ENVIRONMENT: local
SECRET_KEY: test-secret-key-for-testing-only
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e292631c..9cc1b795 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -46,13 +46,12 @@ repos:
files: ^backend/(src|scripts|migrations|tests)/
types: [python]
- - id: mypy_cli
- name: Mypy (cli)
+ - id: fastro_sync_check
+ name: Wiring in sync (fastro)
language: system
- entry: bash -c 'cd cli && uv run --no-sync mypy -p cli'
+ entry: uv run --no-sync fastro sync --check
pass_filenames: false
- files: ^cli/src/
- types: [python]
+ files: ^(blueprint\.toml|fastro\.toml|pyproject\.toml|uv\.lock|backend/src/wiring/.*|backend/scripts/seeders\.py|backend/tests/wiring\.py)$
- id: unit_test
name: Unit test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 03de15b1..79d263ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,8 +24,13 @@ cd FastAPI-boilerplate
uv sync --all-packages --all-extras
```
-`--all-packages` installs both workspace members, and `--all-extras` brings in the
-dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest.
+`--all-packages` installs the backend, the workspace's one member, and `--all-extras`
+brings in the dev tools: a plain `uv sync` leaves you without ruff, mypy or pytest.
+
+The sync also installs fastro, the CLI that generates projects from this blueprint
+and checks it. The root `pyproject.toml` pins fastro to one commit in its `dev`
+group. `uv.lock` is at lock revision 5, which uv 0.13.8 wrote, so use uv 0.13.8 or
+newer.
### Activating the Virtual Environment
@@ -85,6 +90,7 @@ It helps in identifying simple issues before submission to code review. By runni
1. **Committing Your Changes**:
After making your changes, use `git commit -am 'Add some fooBar'` to commit them. Pre-commit will run automatically on your files when you commit, ensuring that they meet the required standards.
Note: If pre-commit identifies issues, it may block your commit. Fix these issues and commit again. This ensures that all contributions are of high quality.
+ A commit that touches `blueprint.toml`, `fastro.toml`, a wiring file fastro generates, the root `pyproject.toml`, or `uv.lock` also runs `uv run --no-sync fastro sync --check`, which fails when the wiring in the commit differs from what fastro generates. Run `uv run --no-sync fastro sync` to regenerate the wiring, then commit the result.
1. **Pushing Changes and Creating Pull Request**:
Push your changes to the branch using `git push origin feature/fooBar`.
Visit your fork on GitHub and create a new Pull Request to the main repository.
diff --git a/README.md b/README.md
index d0af0a05..b58ae108 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,13 @@
-
@@ -47,8 +47,8 @@
* **SQLAdmin**-based admin panel (optional, env-toggled)
* [Taskiq](https://taskiq-python.github.io/) workers (Redis or RabbitMQ broker)
* Redis or Memcached caching (`@cache` decorator + provider API)
-* **Plugin-ready `bp` CLI** - generate compose files, audit env, mount third-party command/feature plugins
-* Docker Compose for local / prod / nginx-fronted (generated by the CLI)
+* **fastro** - generates the compose files and audits the env
+* Docker Compose for local / prod / nginx-fronted (generated by fastro)
* Runs on any Postgres - the bundled container, or serverless via [Neon](https://neon.com) ([guide](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/database/neon/))
## Why and When to use it
@@ -57,7 +57,7 @@
* A pragmatic starter with auth, CRUD, jobs, caching and rate-limits
* **Sensible defaults** with the freedom to opt-out of modules
-* **A foundation that grows** - vertical-slice modules + a plugin-aware CLI for code generators
+* **A foundation that grows** - vertical-slice modules, one folder per domain
* **Docs over boilerplate** in this README - depth lives on the [docs site](https://benavlabs.github.io/FastAPI-boilerplate/)
> **Not a fit** if you need a monorepo microservices scaffold - [see the docs](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/project-structure/) for pointers.
@@ -72,20 +72,20 @@
* **Queues**: [Taskiq workers](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/background-tasks/) (Redis or RabbitMQ)
* **Rate limits**: [per-tier + per-path rules](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/rate-limiting/)
* **Admin**: [SQLAdmin views](https://benavlabs.github.io/FastAPI-boilerplate/user-guide/admin-panel/) (optional, env-toggled)
-* **CLI**: [`bp` tool](https://benavlabs.github.io/FastAPI-boilerplate/cli/) for compose scaffolding, env audits, and plugin extensions
+* **fastro**: compose scaffolding and env audits
-## Fastro vs FastroAI
+## FastAPI-boilerplate vs FastroAI
-This boilerplate - **Fastro** - is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well.
+**FastAPI-boilerplate** is the free, open-source **foundation**: everything you need for a production FastAPI backend. **[FastroAI](https://fastro.ai)** is the paid template built on the same foundation for shipping a **complete SaaS** - Stripe billing (subscriptions, credits, discounts), entitlements, transactional email, and a frontend, all wired together. Building an **AI** product? The PydanticAI agent layer is included too - but every paid feature fits a regular SaaS just as well.
-| | **Fastro** (this repo · free) | **FastroAI** (paid) |
+| | **FastAPI-boilerplate** (this repo · free) | **FastroAI** (paid) |
|---|:---:|:---:|
| FastAPI + SQLAlchemy 2.0, Pydantic v2 | ✓ | ✓ |
| Auth - sessions, OAuth, API keys | ✓ | ✓ **+ JWT** |
| FastCRUD · SQLAdmin · Alembic | ✓ | ✓ |
| Caching · rate limiting · Taskiq jobs | ✓ | ✓ |
| Docker (local / prod / nginx) | ✓ | ✓ |
-| `bp` CLI - scaffolding, env audit, plugins | ✓ | |
+| fastro - compose scaffolding, env audit | ✓ | |
| **Payments** - Stripe: subscriptions, credits, discounts, webhooks | | ✓ |
| **Entitlements** - feature gating by plan/tier | | ✓ |
| **Transactional email** & notifications | | ✓ |
@@ -98,27 +98,25 @@ This boilerplate - **Fastro** - is the free, open-source **foundation**: everyth
-
+
-**Stick with Fastro** if you want a clean, hackable FastAPI backend to build on.
+**Stick with FastAPI-boilerplate** if you want a clean, hackable FastAPI backend to build on.
**[Get FastroAI →](https://fastro.ai)** if you're shipping a SaaS - AI or not - and want billing, entitlements, email, auth, and a frontend ready out of the box.
## Repo Layout
-This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with two members. One venv at the root covers both.
+This is a [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) with one member, `backend/`. One venv at the root holds it and fastro.
```text
fastapi-boilerplate/
├── pyproject.toml # workspace root (uv workspace metadata)
-├── backend/ # the deployable application
-│ ├── src/ # interfaces/, infrastructure/, modules/
-│ ├── pyproject.toml
-│ └── Dockerfile # multi-stage: dev / migrate / prod
-└── cli/ # `bp` - developer/operator tool (never ships in prod)
- └── src/cli/
+└── backend/ # the deployable application
+ ├── src/ # interfaces/, infrastructure/, modules/
+ ├── pyproject.toml
+ └── Dockerfile # multi-stage: dev / migrate / prod
```
## Quickstart
@@ -126,23 +124,23 @@ fastapi-boilerplate/
```bash
git clone https://github.com//FastAPI-boilerplate
cd FastAPI-boilerplate
-uv sync --all-packages --all-extras # one venv at the root, both members installed
+uv sync --all-packages --all-extras # one venv at the root: the backend, plus fastro
```
Generate a compose file for the deployment shape you want:
```bash
-uv run --no-sync bp deploy generate local # hot-reload dev stack
-# or: uv run --no-sync bp deploy generate prod # production single-host
-# or: uv run --no-sync bp deploy generate nginx # production behind nginx
+uv run --no-sync fastro make deploy local # hot-reload dev stack
+# or: uv run --no-sync fastro make deploy prod # production single-host
+# or: uv run --no-sync fastro make deploy nginx # production behind nginx
```
-Configure your env (the CLI helps with secrets and validation):
+Configure your env (fastro helps with secrets and validation):
```bash
cp backend/.env.example backend/.env
-uv run --no-sync bp env gen-secret # print a fresh SECRET_KEY
-uv run --no-sync bp env validate # audit .env against the production validator
+uv run --no-sync fastro env secret # print a fresh SECRET_KEY
+uv run --no-sync fastro env validate # audit .env against the production validator
```
Bring it up:
@@ -168,22 +166,19 @@ uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker
```bash
# generate a fresh production-ready compose file
-uv run --no-sync bp deploy generate prod --workers 8
+uv run --no-sync fastro make deploy prod --workers 8
# audit your .env against the production security validator
-uv run --no-sync bp env validate
+uv run --no-sync fastro env validate
# run Alembic migrations
cd backend && uv run --no-sync alembic revision --autogenerate -m "" && uv run --no-sync alembic upgrade head
# run tests
cd backend && uv run --no-sync pytest
-
-# install bp as a global tool (optional)
-uv tool install --editable ./cli
```
-More examples (superuser creation, tiers, rate limits, admin usage, plugin authoring) in the [docs](https://benavlabs.github.io/FastAPI-boilerplate/).
+More examples (superuser creation, tiers, rate limits, admin usage) in the [docs](https://benavlabs.github.io/FastAPI-boilerplate/).
## Sponsors
diff --git a/backend/.env.example b/backend/.env.example
index 03b82981..2263cf62 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -23,7 +23,7 @@ POSTGRES_ASYNC_PREFIX=postgresql+asyncpg://
# CREATE_TABLES_ON_STARTUP=true
# Hosted / serverless Postgres (Neon, RDS, Cloud SQL, ...): DATABASE_URL overrides
-# every POSTGRES_* value above. Mind the asyncpg spelling — the driver prefix is
+# every POSTGRES_* value above. Mind the asyncpg spelling: the driver prefix is
# postgresql+asyncpg:// and TLS is ssl=require, NOT libpq's sslmode=require.
# Guide: https://benavlabs.github.io/FastAPI-boilerplate/user-guide/database/neon/
# DATABASE_URL=postgresql+asyncpg://user:password@host.example.com/dbname?ssl=require
@@ -40,14 +40,12 @@ POSTGRES_POOL_RECYCLE=-1
# ===================================
# Cache Configuration
# ===================================
+# @fastro if=cache
CACHE_ENABLED=true
# Options: memcached, redis
+# @fastro option=cache.backend
CACHE_BACKEND=redis
-# Client-side cache settings
-CLIENT_CACHE_ENABLED=true
-CLIENT_CACHE_MAX_AGE=60
-
# Cache Memcached settings (when using CACHE_BACKEND=memcached)
CACHE_MEMCACHED_HOST=localhost
CACHE_MEMCACHED_PORT=11211
@@ -64,18 +62,29 @@ CACHE_REDIS_PASSWORD=
CACHE_REDIS_CONNECT_TIMEOUT=5
CACHE_REDIS_POOL_SIZE=10
+# Before production: set CACHE_REDIS_PASSWORD, and keep CACHE_REDIS_DB to this service
+# alone, so a flush here leaves every other service's keys where they were.
+
# ===================================
# Rate Limiting Configuration
# ===================================
-# Provided by crudauth (Redis-backed). Limits are resolved per request from the
+# @fastro if=ratelimit
+# The per-caller throttle on the API routes. Limits are resolved per request from the
# user's tier and path, falling back to the defaults below.
RATE_LIMITER_ENABLED=true
+DEFAULT_RATE_LIMIT_LIMIT=100
+DEFAULT_RATE_LIMIT_PERIOD=60
+
+# ===================================
+# Rate Limiter Store
+# ===================================
+# @fastro if=accounts
+# Where the counters live: the login lockout keeps its own here, and the API throttle,
+# where it is selected, shares them.
# redis (default), database or memory. Memory counters are per process, so each worker
# counts a login lockout on its own; database keeps them in two tables of this project's
# database, which every worker shares without a Redis.
RATE_LIMITER_BACKEND=redis
-DEFAULT_RATE_LIMIT_LIMIT=100
-DEFAULT_RATE_LIMIT_PERIOD=60
# Rate Limiter Redis settings
# Uses DB 1 by default to separate from cache (which uses DB 0)
@@ -88,6 +97,9 @@ RATE_LIMITER_REDIS_PASSWORD=
RATE_LIMITER_REDIS_CONNECT_TIMEOUT=5
RATE_LIMITER_REDIS_POOL_SIZE=10
+# Before production: set RATE_LIMITER_REDIS_PASSWORD, and keep RATE_LIMITER_REDIS_DB to
+# the counters alone.
+
# ===================================
# Email Configuration
# ===================================
@@ -117,6 +129,7 @@ EMAIL_SMTP_TIMEOUT_SECONDS=10
# ===================================
# API Keys
# ===================================
+# @fastro if=api_keys
# How many days of key usage rows to keep. Each row carries the caller's address and
# user agent, one row per request. 0 keeps every row and prunes nothing, and a value
# below 0 is refused at startup. The analytics
@@ -131,7 +144,9 @@ KEY_USAGE_RETENTION_DAYS=90
# ===================================
# Taskiq Configuration
# ===================================
+# @fastro if=taskiq
# Broker type: 'redis' or 'rabbitmq'
+# @fastro option=taskiq.broker
TASKIQ_BROKER_TYPE=redis
# How many times a task labelled retry_on_error=True runs in all, the first attempt
@@ -158,6 +173,9 @@ TASKIQ_RABBITMQ_USER=guest
TASKIQ_RABBITMQ_PASSWORD=guest
TASKIQ_RABBITMQ_VHOST=/
+# Before production: give RabbitMQ credentials of the project's own rather than
+# guest/guest, and keep TASKIQ_REDIS_DB to the broker alone.
+
# ===================================
# Web Server Configuration
@@ -177,12 +195,22 @@ CORS_ALLOW_HEADERS=*
GZIP_ENABLED=true
GZIP_MINIMUM_SIZE=1000
+# Client-side caching: the Cache-Control headers responses carry
+CLIENT_CACHE_ENABLED=true
+CLIENT_CACHE_MAX_AGE=60
+
+# Which peers uvicorn accepts X-Forwarded-For and X-Forwarded-Proto from. Read by
+# uvicorn, not by the app, and it decides what request.client and the access logs
+# say. Name your proxy's address or subnet; a wildcard lets any client claim any
+# address. Leave unset when nothing sits in front of the app.
+# FORWARDED_ALLOW_IPS=172.31.240.0/24
+
# API documentation settings
ENABLE_DOCS_IN_PRODUCTION=false
OPENAPI_PREFIX=
# ===================================
-# Authentication & Security
+# Security
# ===================================
SECRET_KEY=insecure-secret-key-change-this-in-production
@@ -190,6 +218,10 @@ SECRET_KEY=insecure-secret-key-change-this-in-production
# Automatically validates security settings in production environments
PRODUCTION_SECURITY_VALIDATION_ENABLED=true
+# ===================================
+# Authentication & Security
+# ===================================
+# @fastro if=accounts
# Session Management
SESSION_TIMEOUT_MINUTES=30
SESSION_CLEANUP_INTERVAL_MINUTES=15
@@ -217,10 +249,18 @@ SESSION_SECURE_COOKIES=true
# workers share them with no Redis; it adds the crudauth_store and crudauth_counters
# tables, which need one migration.
SESSION_BACKEND=redis
-# Sessions, CSRF tokens, OAuth state and login lockout counters use the cache Redis
-# connection (CACHE_REDIS_*) on their own DB, so a cache flush doesn't log everyone out.
+# Sessions, CSRF tokens, OAuth state and login lockout counters keep their own DB on the
+# session Redis connection, so a cache flush doesn't log everyone out.
SESSION_REDIS_DB=2
-# Optional full URL for a dedicated session Redis; overrides the cache connection and SESSION_REDIS_DB.
+# The connection itself. Left unset, each of these reads the cache's CACHE_REDIS_* where the
+# cache is selected, and localhost:6379 with no password otherwise, which is not the compose
+# stack's Redis. Set them when there is no cache, or to point sessions somewhere else. Setting
+# SESSION_REDIS_PASSWORD overrides the cache's password rather than adding to it.
+# SESSION_REDIS_HOST=redis
+# SESSION_REDIS_PORT=6379
+# SESSION_REDIS_PASSWORD=
+# Optional full URL for a dedicated session Redis; overrides the connection above and
+# SESSION_REDIS_DB.
# SESSION_REDIS_URL=rediss://user:password@sessions-redis.example.com:6380/0
# CSRF Protection
@@ -231,12 +271,6 @@ CSRF_ENABLED=true
# IP for login lockout. 0 = direct (socket peer); set 1 behind a single nginx/Caddy.
TRUSTED_PROXY_HOPS=0
-# Which peers uvicorn accepts X-Forwarded-For and X-Forwarded-Proto from. Read by
-# uvicorn, not by the app, and it decides what request.client and the access logs
-# say. Name your proxy's address or subnet; a wildcard lets any client claim any
-# address. Leave unset when nothing sits in front of the app.
-# FORWARDED_ALLOW_IPS=172.31.240.0/24
-
# Password policy (crudauth applies this to every password-writing path)
PASSWORD_MIN_LENGTH=8
PASSWORD_REQUIRE_UPPERCASE=true
@@ -244,17 +278,24 @@ PASSWORD_REQUIRE_LOWERCASE=true
PASSWORD_REQUIRE_DIGIT=true
PASSWORD_REQUIRE_SPECIAL=true
+# Before production: read the session timeouts above against what you need, keep
+# SESSION_REDIS_DB to the session store alone, and make sure the session Redis has a
+# password, whether it comes from the cache's or from SESSION_REDIS_PASSWORD.
+
# ===================================
# Admin Interface (SQLAdmin)
# ===================================
-# Enable/disable the admin interface
-ADMIN_ENABLED=true
+# @fastro if=admin
+# The panel is off until a project asks for it. Set this to true, with credentials of your
+# own below, to serve it.
+ADMIN_ENABLED=false
# Where the panel is mounted; the admin session cookie is scoped to this path
ADMIN_BASE_URL=/admin
# ===================================
# OAuth Configuration
# ===================================
+# @fastro if=accounts
OAUTH_REDIRECT_BASE_URL=http://localhost:8000
# Google OAuth
@@ -309,15 +350,25 @@ API_TERMS_OF_SERVICE=
# DOCS_URL=/docs
# REDOC_URL=/redoc
+# ===================================
+# Tiers
+# ===================================
+# @fastro if=tiers
+# The tier the initial-data step creates, if it isn't there already.
+DEFAULT_TIER_NAME=free
+
# ===================================
# Initial Setup Configuration
# ===================================
+# @fastro if=accounts
# Admin user settings (for initial setup)
ADMIN_NAME=Admin User
ADMIN_EMAIL=admin@example.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=Change-Me-Now-1!
+# Before production: set ADMIN_USERNAME and ADMIN_PASSWORD to credentials of your own.
+
# ===================================
# Production Security Checklist
# ===================================
@@ -325,16 +376,6 @@ ADMIN_PASSWORD=Change-Me-Now-1!
# 1. Generate strong SECRET_KEY with high entropy
# Example: python -c "import secrets; print(secrets.token_urlsafe(64))"
# 2. Set unique database passwords (avoid defaults like 'postgres')
-# 3. Set Redis passwords for all instances:
-# - CACHE_REDIS_PASSWORD (for cache operations and sessions)
-# - RATE_LIMITER_REDIS_PASSWORD (for rate limiting)
-# 4. Use separate Redis instances/databases for different services:
-# - Cache: CACHE_REDIS_DB=0 (default)
-# - Rate Limiter: RATE_LIMITER_REDIS_DB=1 (default)
-# - Sessions: SESSION_REDIS_DB=2 (default)
-# - Taskiq: TASKIQ_REDIS_DB=3 (default)
-# 5. Restrict CORS_ORIGINS to specific domains (avoid *)
-# 6. Set strong admin credentials (ADMIN_USERNAME, ADMIN_PASSWORD)
-# 7. Review session timeout settings for your security requirements
-# 8. Set ENVIRONMENT=production to enable security validation
-# 9. Configure RabbitMQ with strong credentials (avoid guest/guest)
+# 3. Restrict CORS_ORIGINS to specific domains (avoid *)
+# 4. Set ENVIRONMENT=production to enable security validation
+# Each selected feature carries its own checks beside the settings they are about.
diff --git a/backend/Dockerfile b/backend/Dockerfile
index 7636160b..a38d1a23 100644
--- a/backend/Dockerfile
+++ b/backend/Dockerfile
@@ -10,7 +10,6 @@ COPY --from=ghcr.io/astral-sh/uv:0.9.9 /uv /usr/local/bin/uv
# Copy the workspace manifests and uv.lock for deterministic export
COPY pyproject.toml uv.lock ./
COPY backend/pyproject.toml backend/pyproject.toml
-COPY cli/pyproject.toml cli/pyproject.toml
# Export from lock file (not re-resolving dependencies!)
# Filter out the local project line and keep only external dependencies
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index 2f016c69..27fad392 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -12,19 +12,15 @@ readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"aiomcache>=0.8.2",
- "aiosqlite>=0.21.0",
"alembic>=1.16.4",
"anyio>=4.15.1",
"asyncpg>=0.30.0",
"crudauth[all]>=0.8.2,<0.9.0",
"cryptography>=42.0.0",
- "faker>=37.1.0",
- "fastapi[standard]>=0.115.8",
+ "fastapi[standard]>=0.115.8,<0.140.7",
"fastcrud>=0.21.0",
"greenlet>=3.1.1",
- "httpx>=0.28.1",
"itsdangerous>=2.2.0",
- "jinja2>=3.1.6",
"pydantic>=2.10.6",
"pydantic-settings>=2.14.2",
"redis>=6.1.0",
@@ -48,6 +44,9 @@ dev = [
"pytest-xdist[psutil]>=3.8.0",
"taskiq[reload]>=0.11.20",
"pre-commit>=4.0.0",
+ "faker>=37.1.0",
+ "httpx>=0.28.1",
+ "jinja2>=3.1.6",
]
[tool.setuptools.packages.find]
diff --git a/backend/scripts/baseline.py b/backend/scripts/baseline.py
new file mode 100644
index 00000000..cc5dbb91
--- /dev/null
+++ b/backend/scripts/baseline.py
@@ -0,0 +1,182 @@
+"""Write this project's baseline migration, and check that it recreates the models.
+
+Run it once, from ``backend/``:
+
+ python -m scripts.baseline
+ python -m scripts.baseline --check
+
+It starts a throwaway Postgres, autogenerates the revision against it, applies it to that
+empty database, and compares the tables and indexes it created with the ones the models
+declare. The revision is left in ``migrations/versions/`` to be committed. ``--check`` deletes
+it again, so a project can be checked without gaining a migration.
+
+A project that already has a revision is refused: a baseline is a project's first migration,
+and autogenerating one against an empty database beside a history writes a revision that
+recreates what the history already created.
+"""
+
+import argparse
+import asyncio
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+backend_dir = Path(__file__).parent.parent
+sys.path.append(str(backend_dir))
+
+from sqlalchemy import Connection, inspect # noqa: E402
+from testcontainers.postgres import PostgresContainer # noqa: E402
+
+from src.infrastructure.database.registry import import_models # noqa: E402
+from src.infrastructure.database.session import Base, build_engine # noqa: E402
+
+IMAGE = "postgres:16-alpine"
+
+MESSAGE = "baseline"
+"""What the revision is named after, which alembic turns into the slug its file is named with."""
+
+VERSIONS = Path("migrations/versions")
+
+EXPOSED_PORT = 5432
+
+
+class BaselineError(Exception):
+ """What went wrong, as the line the script exits with."""
+
+
+def alembic(*arguments: str) -> subprocess.CompletedProcess[str]:
+ return subprocess.run([sys.executable, "-m", "alembic", *arguments], capture_output=True, text=True)
+
+
+def connection_settings(postgres: PostgresContainer) -> dict[str, str]:
+ """The container, as the settings an alembic run reads the database from.
+
+ ``DATABASE_URL`` is blanked because it wins over these: a configured one would send the
+ autogenerate at the database the project really uses.
+ """
+ return {
+ "POSTGRES_SERVER": postgres.get_container_host_ip(),
+ "POSTGRES_PORT": str(postgres.get_exposed_port(EXPOSED_PORT)),
+ "POSTGRES_USER": postgres.username,
+ "POSTGRES_PASSWORD": postgres.password,
+ "POSTGRES_DB": postgres.dbname,
+ "DATABASE_URL": "",
+ }
+
+
+def database_url(postgres: PostgresContainer) -> str:
+ details = connection_settings(postgres)
+
+ return (
+ f"postgresql+asyncpg://{details['POSTGRES_USER']}:{details['POSTGRES_PASSWORD']}"
+ f"@{details['POSTGRES_SERVER']}:{details['POSTGRES_PORT']}/{details['POSTGRES_DB']}"
+ )
+
+
+def declared_schema() -> dict[str, list[str]]:
+ """The tables and named indexes the models declare, beside the one alembic keeps itself."""
+ import_models()
+ declared = {
+ name: sorted(str(index.name) for index in table.indexes if index.name is not None)
+ for name, table in Base.metadata.tables.items()
+ }
+ declared["alembic_version"] = []
+
+ return declared
+
+
+def _reflected(connection: Connection) -> dict[str, list[str]]:
+ """What is really there: an index a constraint brought with it is not counted twice."""
+ inspector = inspect(connection)
+
+ def indexes(table: str) -> list[str]:
+ found = inspector.get_indexes(table)
+ named = [index["name"] for index in found if not index.get("duplicates_constraint")]
+
+ return sorted(name for name in named if name is not None)
+
+ return {table: indexes(table) for table in sorted(inspector.get_table_names())}
+
+
+async def created_schema(url: str) -> dict[str, list[str]]:
+ """What applying the baseline left in the database."""
+ engine = build_engine(url)
+ try:
+ async with engine.connect() as connection:
+ return await connection.run_sync(_reflected)
+ finally:
+ await engine.dispose()
+
+
+def _revisions() -> list[Path]:
+ return sorted(VERSIONS.glob("*.py"))
+
+
+def write_revision() -> Path:
+ """Autogenerate the baseline, and return the one revision it wrote."""
+ before = set(_revisions())
+ autogenerated = alembic("revision", "--autogenerate", "-m", MESSAGE)
+ if autogenerated.returncode != 0:
+ raise BaselineError("autogenerate failed:\n" + autogenerated.stdout + autogenerated.stderr)
+
+ written = [path for path in _revisions() if path not in before]
+ if len(written) != 1:
+ raise BaselineError(f"autogenerate wrote {len(written)} revisions, and a baseline is one")
+
+ if not written[0].name.endswith(f"_{MESSAGE}.py"):
+ raise BaselineError(f"autogenerate wrote {written[0].name}, which is not the baseline")
+
+ return written[0]
+
+
+def write_baseline(url: str, *, keeping: bool) -> str:
+ """Write the baseline and apply it, and say what it recreated."""
+ declared = declared_schema()
+ revision = write_revision()
+ try:
+ applied = alembic("upgrade", "head")
+ if applied.returncode != 0:
+ raise BaselineError("upgrade failed:\n" + applied.stdout + applied.stderr)
+
+ created = asyncio.run(created_schema(url))
+ if created != declared:
+ raise BaselineError(f"the baseline left {created}, while the models declare {declared}")
+ finally:
+ if not keeping:
+ revision.unlink(missing_ok=True)
+
+ indexes = sum(len(names) for names in declared.values())
+
+ return f"a baseline of {len(declared) - 1} tables and {indexes} indexes applies to an empty database"
+
+
+def _refuse_a_history() -> None:
+ history = _revisions()
+ if history:
+ names = ", ".join(path.name for path in history)
+
+ raise BaselineError(f"this project already has {names}, and a baseline is a project's first revision")
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser(description="Write this project's baseline migration against a throwaway database.")
+ parser.add_argument("--check", action="store_true", help="delete the revision afterwards, leaving the tree as it was")
+ arguments = parser.parse_args(argv)
+
+ os.environ["TESTCONTAINERS_RYUK_DISABLED"] = "true"
+ try:
+ _refuse_a_history()
+ with PostgresContainer(IMAGE) as postgres:
+ os.environ.update(connection_settings(postgres))
+ print(write_baseline(database_url(postgres), keeping=not arguments.check))
+ except BaselineError as error:
+ print(error, file=sys.stderr)
+
+ return 1
+
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/backend/scripts/gen_secret.py b/backend/scripts/gen_secret.py
new file mode 100644
index 00000000..4a67b78a
--- /dev/null
+++ b/backend/scripts/gen_secret.py
@@ -0,0 +1,93 @@
+"""Print a secret key the project's own rules accept.
+
+Run it from ``backend/``:
+
+ python -m scripts.gen_secret [--bytes 32]
+
+``SECRET_KEY`` signs the session cookies, the CSRF tokens and the admin panel's session,
+and production refuses a key its rules read as something a person typed. A draw of random
+bytes can land on such a key: about one hex key in twelve million runs through eight
+consecutive digits. So this draws again while the rules refuse what it drew, and prints the
+last draw either way, which keeps it from drawing for ever.
+
+It reads no configuration and touches no database, so it works before there is a ``.env``
+to put the key in. The rules are loaded from their own file rather than through
+``src.infrastructure.security``, whose import configures logging and writes a line to
+stdout: the key is meant to be piped, and a log line would be piped with it.
+"""
+
+import argparse
+import importlib.util
+import secrets
+from pathlib import Path
+from types import ModuleType
+
+RULES_PATH = Path(__file__).parent.parent / "src" / "infrastructure" / "security" / "secret_key.py"
+"""The project's own secret-key rules, the ones production refuses a key by."""
+
+
+def _rules() -> ModuleType:
+ """The rules module, loaded from its file so nothing around it is imported."""
+ spec = importlib.util.spec_from_file_location("secret_key_rules", RULES_PATH)
+ if spec is None or spec.loader is None:
+ raise ImportError(f"No secret-key rules at {RULES_PATH}.")
+
+ module = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(module)
+
+ return module
+
+
+is_weak_secret_key = _rules().is_weak_secret_key
+
+DRAWS = 8
+"""How many keys are drawn at most; the last one is printed whatever the rules say."""
+
+DEFAULT_BYTES = 32
+SMALLEST_BYTES = 16
+LARGEST_BYTES = 128
+
+
+def generate(byte_count: int = DEFAULT_BYTES) -> str:
+ """A hex key of ``byte_count`` random bytes, redrawn while the rules refuse it."""
+ candidate = secrets.token_hex(byte_count)
+ for _ in range(DRAWS - 1):
+ if not is_weak_secret_key(candidate):
+ break
+ candidate = secrets.token_hex(byte_count)
+
+ return candidate
+
+
+def parse_byte_count(value: str) -> int:
+ """``value`` as a byte count the key may be drawn from.
+
+ Raises:
+ argparse.ArgumentTypeError: it isn't a number, or sits outside the range.
+ """
+ try:
+ count = int(value)
+ except ValueError as error:
+ raise argparse.ArgumentTypeError(f"{value!r} is not a number of bytes.") from error
+
+ if not SMALLEST_BYTES <= count <= LARGEST_BYTES:
+ raise argparse.ArgumentTypeError(f"{count} is outside {SMALLEST_BYTES} to {LARGEST_BYTES}.")
+
+ return count
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Print a secret key suitable for SECRET_KEY.")
+ parser.add_argument(
+ "--bytes",
+ dest="byte_count",
+ type=parse_byte_count,
+ default=DEFAULT_BYTES,
+ help=f"Random bytes to draw, {SMALLEST_BYTES} to {LARGEST_BYTES}; the hex output is twice as long.",
+ )
+
+ print(generate(parser.parse_args().byte_count))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/backend/scripts/seeders.py b/backend/scripts/seeders.py
index 80df9ee7..e3beb0bd 100644
--- a/backend/scripts/seeders.py
+++ b/backend/scripts/seeders.py
@@ -1,6 +1,7 @@
"""The initial-data steps ``scripts/setup_initial_data.py`` runs, in order.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from collections.abc import Awaitable, Callable
diff --git a/backend/scripts/validate_env.py b/backend/scripts/validate_env.py
new file mode 100644
index 00000000..b1a1bccf
--- /dev/null
+++ b/backend/scripts/validate_env.py
@@ -0,0 +1,61 @@
+"""Audit this environment the way production would.
+
+Run it from ``backend/``:
+
+ python -m scripts.validate_env
+
+The settings are audited as a copy whose ``ENVIRONMENT`` reads ``production``, whatever the
+configured one says, so a development or staging configuration is held to the gate that
+stops a production boot, and a finding that names an environment names the one it was
+checked for.
+
+It exits 1 when anything critical is found, and 0 otherwise. Warnings are printed and
+exit 0: they are worth reading, not worth refusing a boot over.
+"""
+
+import sys
+from pathlib import Path
+
+backend_dir = Path(__file__).parent.parent
+sys.path.append(str(backend_dir))
+
+from src.infrastructure.config.settings import EnvironmentOption, get_settings # noqa: E402
+from src.infrastructure.security.production_validator import ProductionSecurityValidator # noqa: E402
+
+
+def audit() -> tuple[list[str], list[str]]:
+ """The critical findings and the warnings, for these settings read as production."""
+ as_production = get_settings().model_copy(update={"ENVIRONMENT": EnvironmentOption.PRODUCTION})
+
+ return ProductionSecurityValidator(as_production).audit()
+
+
+def report(critical: list[str], warnings: list[str]) -> None:
+ """Print what the audit found, grouped, or say that it found nothing."""
+ if not critical and not warnings:
+ print("No issues found. Configuration would pass production validation.")
+
+ return
+
+ if critical:
+ print(f"Critical ({len(critical)}):")
+ for finding in critical:
+ print(f" • {finding}")
+
+ if warnings:
+ if critical:
+ print()
+ print(f"Warnings ({len(warnings)}):")
+ for finding in warnings:
+ print(f" • {finding}")
+
+
+def main() -> int:
+ critical, warnings = audit()
+ report(critical, warnings)
+
+ return 1 if critical else 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/backend/src/infrastructure/auth/settings.py b/backend/src/infrastructure/auth/settings.py
index 7099d4b6..fdd21507 100644
--- a/backend/src/infrastructure/auth/settings.py
+++ b/backend/src/infrastructure/auth/settings.py
@@ -1,14 +1,13 @@
"""Settings for the accounts feature: users, sessions, CSRF, login lockout, OAuth."""
from pydantic import AliasChoices, Field
-from pydantic_settings import BaseSettings
-from ..config.base import config
+from ..config.base import EnvSettings
from ..config.enums import RateLimiterBackend, SessionBackend
from ..redis import redis_url
-class AuthSettings(BaseSettings):
+class AuthSettings(EnvSettings):
"""Authentication-related settings.
Sessions have their own Redis connection. Each of its fields falls back to the
@@ -16,54 +15,54 @@ class AuthSettings(BaseSettings):
``CACHE_REDIS_*`` keeps working.
"""
- SESSION_TIMEOUT_MINUTES: int = config("SESSION_TIMEOUT_MINUTES", default=30, cast=int)
- SESSION_ABSOLUTE_TIMEOUT_HOURS: int | None = config("SESSION_ABSOLUTE_TIMEOUT_HOURS", default=None, cast=int)
- FRESH_SIGN_IN_SECONDS: int | None = config("FRESH_SIGN_IN_SECONDS", default=None, cast=int)
+ SESSION_TIMEOUT_MINUTES: int = 30
+ SESSION_ABSOLUTE_TIMEOUT_HOURS: int | None = None
+ FRESH_SIGN_IN_SECONDS: int | None = None
- LOGIN_MAX_ATTEMPTS: int = config("LOGIN_MAX_ATTEMPTS", default=5, cast=int)
- LOGIN_ATTEMPT_WINDOW_SECONDS: int = config("LOGIN_ATTEMPT_WINDOW_SECONDS", default=900, cast=int)
- LOGIN_LOCKOUT_BASE_SECONDS: int = config("LOGIN_LOCKOUT_BASE_SECONDS", default=300, cast=int)
- LOGIN_LOCKOUT_MAX_SECONDS: int = config("LOGIN_LOCKOUT_MAX_SECONDS", default=3600, cast=int)
- SESSION_CLEANUP_INTERVAL_MINUTES: int = config("SESSION_CLEANUP_INTERVAL_MINUTES", default=15, cast=int)
- MAX_SESSIONS_PER_USER: int = config("MAX_SESSIONS_PER_USER", default=5, cast=int)
- SESSION_SECURE_COOKIES: bool = config("SESSION_SECURE_COOKIES", default=True, cast=bool)
- SESSION_BACKEND: str = config("SESSION_BACKEND", default=SessionBackend.REDIS.value)
+ LOGIN_MAX_ATTEMPTS: int = 5
+ LOGIN_ATTEMPT_WINDOW_SECONDS: int = 900
+ LOGIN_LOCKOUT_BASE_SECONDS: int = 300
+ LOGIN_LOCKOUT_MAX_SECONDS: int = 3600
+ SESSION_CLEANUP_INTERVAL_MINUTES: int = 15
+ MAX_SESSIONS_PER_USER: int = 5
+ SESSION_SECURE_COOKIES: bool = True
+ SESSION_BACKEND: str = SessionBackend.REDIS.value
- SESSION_REDIS_DB: int = config("SESSION_REDIS_DB", default=2, cast=int)
+ SESSION_REDIS_DB: int = 2
SESSION_REDIS_URL_OVERRIDE: str | None = Field(
- default=config("SESSION_REDIS_URL", default=None),
+ default=None,
validation_alias="SESSION_REDIS_URL",
)
- CSRF_ENABLED: bool = config("CSRF_ENABLED", default=True, cast=bool)
+ CSRF_ENABLED: bool = True
# Number of trusted reverse proxies in front of the app. crudauth resolves the
# client IP for login lockout from the last hop of X-Forwarded-For; 0 = the socket
# peer (no proxy). Set to 1 behind a single nginx/Caddy, 2 if Cloudflare is also in front.
- TRUSTED_PROXY_HOPS: int = config("TRUSTED_PROXY_HOPS", default=0, cast=int)
+ TRUSTED_PROXY_HOPS: int = 0
- PASSWORD_MIN_LENGTH: int = config("PASSWORD_MIN_LENGTH", default=8, cast=int)
- PASSWORD_REQUIRE_UPPERCASE: bool = config("PASSWORD_REQUIRE_UPPERCASE", default=True, cast=bool)
- PASSWORD_REQUIRE_LOWERCASE: bool = config("PASSWORD_REQUIRE_LOWERCASE", default=True, cast=bool)
- PASSWORD_REQUIRE_DIGIT: bool = config("PASSWORD_REQUIRE_DIGIT", default=True, cast=bool)
- PASSWORD_REQUIRE_SPECIAL: bool = config("PASSWORD_REQUIRE_SPECIAL", default=True, cast=bool)
+ PASSWORD_MIN_LENGTH: int = 8
+ PASSWORD_REQUIRE_UPPERCASE: bool = True
+ PASSWORD_REQUIRE_LOWERCASE: bool = True
+ PASSWORD_REQUIRE_DIGIT: bool = True
+ PASSWORD_REQUIRE_SPECIAL: bool = True
- OAUTH_GOOGLE_CLIENT_ID: str = config("OAUTH_GOOGLE_CLIENT_ID", default="")
- OAUTH_GOOGLE_CLIENT_SECRET: str = config("OAUTH_GOOGLE_CLIENT_SECRET", default="")
- OAUTH_GITHUB_CLIENT_ID: str = config("OAUTH_GITHUB_CLIENT_ID", default="")
- OAUTH_GITHUB_CLIENT_SECRET: str = config("OAUTH_GITHUB_CLIENT_SECRET", default="")
- OAUTH_REDIRECT_BASE_URL: str = config("OAUTH_REDIRECT_BASE_URL", default="http://localhost:8000")
+ OAUTH_GOOGLE_CLIENT_ID: str = ""
+ OAUTH_GOOGLE_CLIENT_SECRET: str = ""
+ OAUTH_GITHUB_CLIENT_ID: str = ""
+ OAUTH_GITHUB_CLIENT_SECRET: str = ""
+ OAUTH_REDIRECT_BASE_URL: str = "http://localhost:8000"
SESSION_REDIS_HOST: str = Field(
- default=config("SESSION_REDIS_HOST", default=config("CACHE_REDIS_HOST", default="localhost")),
+ default="localhost",
validation_alias=AliasChoices("SESSION_REDIS_HOST", "CACHE_REDIS_HOST"),
)
SESSION_REDIS_PORT: int = Field(
- default=config("SESSION_REDIS_PORT", default=config("CACHE_REDIS_PORT", default=6379), cast=int),
+ default=6379,
validation_alias=AliasChoices("SESSION_REDIS_PORT", "CACHE_REDIS_PORT"),
)
SESSION_REDIS_PASSWORD: str | None = Field(
- default=config("SESSION_REDIS_PASSWORD", default=config("CACHE_REDIS_PASSWORD", default=None)),
+ default=None,
validation_alias=AliasChoices("SESSION_REDIS_PASSWORD", "CACHE_REDIS_PASSWORD"),
)
@@ -81,25 +80,25 @@ def SESSION_REDIS_URL(self) -> str:
)
-class LimiterBackendSettings(BaseSettings):
+class LimiterBackendSettings(EnvSettings):
"""The limiter crudauth uses for login lockout, whether or not API routes are throttled."""
- RATE_LIMITER_BACKEND: str = config("RATE_LIMITER_BACKEND", default=RateLimiterBackend.REDIS.value)
- RATE_LIMITER_REDIS_HOST: str = config("RATE_LIMITER_REDIS_HOST", default="localhost")
- RATE_LIMITER_REDIS_PORT: int = config("RATE_LIMITER_REDIS_PORT", default=6379, cast=int)
- RATE_LIMITER_REDIS_DB: int = config("RATE_LIMITER_REDIS_DB", default=1, cast=int)
- RATE_LIMITER_REDIS_PASSWORD: str | None = config("RATE_LIMITER_REDIS_PASSWORD", default=None)
- RATE_LIMITER_REDIS_CONNECT_TIMEOUT: int = config("RATE_LIMITER_REDIS_CONNECT_TIMEOUT", default=5, cast=int)
- RATE_LIMITER_REDIS_POOL_SIZE: int = config("RATE_LIMITER_REDIS_POOL_SIZE", default=10, cast=int)
+ RATE_LIMITER_BACKEND: str = RateLimiterBackend.REDIS.value
+ RATE_LIMITER_REDIS_HOST: str = "localhost"
+ RATE_LIMITER_REDIS_PORT: int = 6379
+ RATE_LIMITER_REDIS_DB: int = 1
+ RATE_LIMITER_REDIS_PASSWORD: str | None = None
+ RATE_LIMITER_REDIS_CONNECT_TIMEOUT: int = 5
+ RATE_LIMITER_REDIS_POOL_SIZE: int = 10
-class FirstSuperuserSettings(BaseSettings):
+class FirstSuperuserSettings(EnvSettings):
"""The first superuser, created by ``scripts/create_first_superuser.py``."""
- ADMIN_NAME: str = config("ADMIN_NAME", default="")
- ADMIN_EMAIL: str = config("ADMIN_EMAIL", default="")
- ADMIN_USERNAME: str = config("ADMIN_USERNAME", default="")
- ADMIN_PASSWORD: str = config("ADMIN_PASSWORD", default="")
+ ADMIN_NAME: str = ""
+ ADMIN_EMAIL: str = ""
+ ADMIN_USERNAME: str = ""
+ ADMIN_PASSWORD: str = ""
class AccountsSettings(AuthSettings, LimiterBackendSettings, FirstSuperuserSettings):
diff --git a/backend/src/infrastructure/auth/setup.py b/backend/src/infrastructure/auth/setup.py
index 770307bc..02f7bdaf 100644
--- a/backend/src/infrastructure/auth/setup.py
+++ b/backend/src/infrastructure/auth/setup.py
@@ -24,6 +24,7 @@
from ...modules.user.constants import NAME_MAX_LENGTH
from ...modules.user.models import User
from ...wiring.email import EMAIL_SENDER
+from ...wiring.signup import NEW_ACCOUNT_FIELDS
from ...wiring.transports import EXTRA_TRANSPORTS
from ..composition import Lifecycle
from ..config.enums import SessionBackend
@@ -101,9 +102,14 @@ def _session_transport() -> SessionTransport:
)
-def _new_user_fields(context: NewUserContext) -> dict[str, Any]:
- """The columns crudauth doesn't fill for an account it creates: the display name."""
- return {"name": context.suggested_name[:NAME_MAX_LENGTH]}
+async def _new_user_fields(context: NewUserContext) -> dict[str, Any]:
+ """The columns crudauth doesn't fill for an account it creates: the display name, and
+ what ``NEW_ACCOUNT_FIELDS`` sets."""
+ fields: dict[str, Any] = {}
+ for contributed in NEW_ACCOUNT_FIELDS:
+ fields.update(await contributed(context.db))
+
+ return {**fields, "name": context.suggested_name[:NAME_MAX_LENGTH]}
def _oauth_providers() -> dict[str, OAuthCredentials]:
diff --git a/backend/src/infrastructure/cache/settings.py b/backend/src/infrastructure/cache/settings.py
index 7d08ca20..e0766078 100644
--- a/backend/src/infrastructure/cache/settings.py
+++ b/backend/src/infrastructure/cache/settings.py
@@ -1,12 +1,10 @@
"""Settings for the cache feature."""
-from pydantic_settings import BaseSettings
-
-from ..config.base import config
+from ..config.base import EnvSettings
from ..config.enums import CacheBackend
-class CacheSettings(BaseSettings):
+class CacheSettings(EnvSettings):
"""Cache-related settings.
This class defines settings for cache connections and behavior across
@@ -34,17 +32,17 @@ class CacheSettings(BaseSettings):
CACHE_REDIS_POOL_SIZE: Maximum number of connections in the pool. Default is 10.
"""
- CACHE_ENABLED: bool = config("CACHE_ENABLED", default=True, cast=bool)
- CACHE_BACKEND: str = config("CACHE_BACKEND", default=CacheBackend.REDIS.value)
+ CACHE_ENABLED: bool = True
+ CACHE_BACKEND: str = CacheBackend.REDIS.value
- CACHE_MEMCACHED_HOST: str = config("CACHE_MEMCACHED_HOST", default="localhost")
- CACHE_MEMCACHED_PORT: int = config("CACHE_MEMCACHED_PORT", default=11211, cast=int)
- CACHE_MEMCACHED_POOL_SIZE: int = config("CACHE_MEMCACHED_POOL_SIZE", default=10, cast=int)
- CACHE_MEMCACHED_CONNECT_TIMEOUT: int = config("CACHE_MEMCACHED_CONNECT_TIMEOUT", default=5, cast=int)
+ CACHE_MEMCACHED_HOST: str = "localhost"
+ CACHE_MEMCACHED_PORT: int = 11211
+ CACHE_MEMCACHED_POOL_SIZE: int = 10
+ CACHE_MEMCACHED_CONNECT_TIMEOUT: int = 5
- CACHE_REDIS_HOST: str = config("CACHE_REDIS_HOST", default="localhost")
- CACHE_REDIS_PORT: int = config("CACHE_REDIS_PORT", default=6379, cast=int)
- CACHE_REDIS_DB: int = config("CACHE_REDIS_DB", default=0, cast=int)
- CACHE_REDIS_PASSWORD: str | None = config("CACHE_REDIS_PASSWORD", default=None)
- CACHE_REDIS_CONNECT_TIMEOUT: int = config("CACHE_REDIS_CONNECT_TIMEOUT", default=5, cast=int)
- CACHE_REDIS_POOL_SIZE: int = config("CACHE_REDIS_POOL_SIZE", default=10, cast=int)
+ CACHE_REDIS_HOST: str = "localhost"
+ CACHE_REDIS_PORT: int = 6379
+ CACHE_REDIS_DB: int = 0
+ CACHE_REDIS_PASSWORD: str | None = None
+ CACHE_REDIS_CONNECT_TIMEOUT: int = 5
+ CACHE_REDIS_POOL_SIZE: int = 10
diff --git a/backend/src/infrastructure/cache/utils.py b/backend/src/infrastructure/cache/utils.py
index ab9f9f24..d0980b58 100644
--- a/backend/src/infrastructure/cache/utils.py
+++ b/backend/src/infrastructure/cache/utils.py
@@ -8,7 +8,7 @@
from pydantic import BaseModel
from starlette.requests import Request
-from ..auth.scope import scope_fingerprint
+from ...wiring.scope import SCOPE_FINGERPRINT
def extract_data_inside_brackets(input_string: str) -> list[str]:
@@ -117,7 +117,7 @@ def caller_marks(caller: Any) -> str | None:
if not isinstance(caller, Principal):
return None
- narrowed = scope_fingerprint(caller)
+ narrowed = SCOPE_FINGERPRINT(caller) if SCOPE_FINGERPRINT is not None else None
return str(caller.user_id) if narrowed is None else f"{caller.user_id}/{narrowed}"
diff --git a/backend/src/infrastructure/composition.py b/backend/src/infrastructure/composition.py
index c43886c8..8b36566c 100644
--- a/backend/src/infrastructure/composition.py
+++ b/backend/src/infrastructure/composition.py
@@ -48,6 +48,11 @@ class Lifecycle:
"""Removes the rows a feature keeps for a tier that a soft delete already took out."""
+NewAccountFields = Callable[[AsyncSession], Awaitable[dict[str, Any]]]
+"""Answers the columns a feature sets on an account as it is created: its own, never the
+account's identity, credentials or privileges, which win over it. It reads, and never commits."""
+
+
@dataclass(frozen=True)
class ReadinessCheck:
"""A dependency the app needs before it can serve, and how to ask whether it is there.
diff --git a/backend/src/infrastructure/config/base.py b/backend/src/infrastructure/config/base.py
index f4522868..03ea18c9 100644
--- a/backend/src/infrastructure/config/base.py
+++ b/backend/src/infrastructure/config/base.py
@@ -5,10 +5,13 @@
import logging
import os
+from collections.abc import Mapping
from enum import StrEnum
+from types import UnionType
+from typing import Any, Union, get_args, get_origin
-from pydantic import Field, field_validator
-from pydantic_settings import BaseSettings
+from pydantic import Field, ValidationInfo, field_validator, model_validator
+from pydantic_settings import BaseSettings, EnvSettingsSource, PydanticBaseSettingsSource, SettingsConfigDict
from sqlalchemy.engine import URL
from starlette.config import Config
@@ -48,6 +51,69 @@ def ini_value(value: str) -> str:
config = Config(env_path)
+FLAG_SPELLINGS = {"true": True, "1": True, "false": False, "0": False}
+"""How a flag may be written: the spellings starlette's ``Config`` casts to a bool."""
+
+
+class _FileAsStarletteReadsIt(EnvSettingsSource):
+ """The environment file, read as starlette's ``Config`` reads it: one ``NAME=value`` a line,
+ names exactly as written, values literally, with no ``${...}`` expansion or ``#`` comments.
+
+ Only the fields of the class being built are taken from it, so each mixin leaves the other
+ mixins' names alone.
+ """
+
+ def __init__(self, settings_cls: type[BaseSettings], env_file: Any) -> None:
+ self.env_file = env_file
+ super().__init__(settings_cls, case_sensitive=True)
+
+ def _load_env_vars(self) -> Mapping[str, str | None]:
+ return Config(self.env_file).file_values if self.env_file else {}
+
+
+class EnvSettings(BaseSettings):
+ """A settings mixin that reads the environment, and the environment file, when it is built.
+
+ The file is the one ``config`` reads, and none under pytest. The environment wins over it.
+ """
+
+ model_config = SettingsConfigDict(env_file=None if running_under_pytest else env_path)
+
+ @field_validator("*", mode="before")
+ @classmethod
+ def _read_as_starlette_cast_it(cls, value: Any, info: ValidationInfo) -> Any:
+ """A flag written as text is one of ``true``, ``false``, ``1`` or ``0`` in any case, and a
+ number written as text is what ``int()`` reads, as when starlette's ``Config`` cast them."""
+ if not isinstance(value, str) or info.field_name is None:
+ return value
+
+ annotation = cls.model_fields[info.field_name].annotation
+ kinds = set(get_args(annotation)) if get_origin(annotation) in (Union, UnionType) else {annotation}
+ if bool in kinds:
+ if value.lower() not in FLAG_SPELLINGS:
+ raise ValueError(f"{value!r} is not a flag: write true, false, 1 or 0")
+
+ return FLAG_SPELLINGS[value.lower()]
+ if int in kinds:
+ return int(value)
+
+ return value
+
+ @classmethod
+ def settings_customise_sources(
+ cls,
+ settings_cls: type[BaseSettings],
+ init_settings: PydanticBaseSettingsSource,
+ env_settings: PydanticBaseSettingsSource,
+ dotenv_settings: PydanticBaseSettingsSource,
+ file_secret_settings: PydanticBaseSettingsSource,
+ ) -> tuple[PydanticBaseSettingsSource, ...]:
+ """The constructor, then the environment, then the file read as starlette reads it."""
+ env_file = getattr(dotenv_settings, "env_file", None)
+
+ return init_settings, env_settings, _FileAsStarletteReadsIt(settings_cls, env_file), file_secret_settings
+
+
class EnvironmentOption(StrEnum):
"""Environment options for the application."""
@@ -57,44 +123,55 @@ class EnvironmentOption(StrEnum):
LOCAL = "local"
-class EnvironmentSettings(BaseSettings):
+class EnvironmentSettings(EnvSettings):
"""Environment-related settings."""
- ENVIRONMENT: EnvironmentOption = config("ENVIRONMENT", default=EnvironmentOption.DEVELOPMENT, cast=EnvironmentOption)
+ ENVIRONMENT: EnvironmentOption = EnvironmentOption.DEVELOPMENT
SCHEMA_BUILT_ON_STARTUP = (EnvironmentOption.LOCAL, EnvironmentOption.DEVELOPMENT)
"""The environments where the app builds its schema from the models as it boots."""
-def _creates_tables_by_default() -> bool:
- """Whether ``CREATE_TABLES_ON_STARTUP`` is on in the environment this process runs in."""
- environment = config("ENVIRONMENT", default=EnvironmentOption.DEVELOPMENT, cast=EnvironmentOption)
-
- return environment in SCHEMA_BUILT_ON_STARTUP
+def _creates_tables_by_default(environment: str | None = None) -> bool:
+ """Whether ``CREATE_TABLES_ON_STARTUP`` is on in ``environment``, or in the one the process runs in."""
+ return EnvironmentOption(environment or EnvironmentSettings().ENVIRONMENT) in SCHEMA_BUILT_ON_STARTUP
-class DatabaseSettings(BaseSettings):
+class DatabaseSettings(EnvSettings):
"""Database-related settings."""
- POSTGRES_USER: str = config("POSTGRES_USER", default="postgres")
- POSTGRES_PASSWORD: str = config("POSTGRES_PASSWORD", default="postgres")
- POSTGRES_SERVER: str = config("POSTGRES_SERVER", default="localhost")
- POSTGRES_PORT: int = config("POSTGRES_PORT", default=5432)
- POSTGRES_DB: str = config("POSTGRES_DB", default="postgres")
- POSTGRES_ASYNC_PREFIX: str = config("POSTGRES_ASYNC_PREFIX", default="postgresql+asyncpg://")
- CREATE_TABLES_ON_STARTUP: bool = config("CREATE_TABLES_ON_STARTUP", default=_creates_tables_by_default(), cast=bool)
+ POSTGRES_USER: str = "postgres"
+ POSTGRES_PASSWORD: str = "postgres"
+ POSTGRES_SERVER: str = "localhost"
+ POSTGRES_PORT: int = 5432
+ POSTGRES_DB: str = "postgres"
+ POSTGRES_ASYNC_PREFIX: str = "postgresql+asyncpg://"
+ CREATE_TABLES_ON_STARTUP: bool = Field(default_factory=_creates_tables_by_default)
- POSTGRES_POOL_SIZE: int = config("POSTGRES_POOL_SIZE", default=20, cast=int)
- POSTGRES_MAX_OVERFLOW: int = config("POSTGRES_MAX_OVERFLOW", default=0, cast=int)
- POSTGRES_POOL_PRE_PING: bool = config("POSTGRES_POOL_PRE_PING", default=True, cast=bool)
- POSTGRES_POOL_RECYCLE: int = config("POSTGRES_POOL_RECYCLE", default=-1, cast=int)
+ POSTGRES_POOL_SIZE: int = 20
+ POSTGRES_MAX_OVERFLOW: int = 0
+ POSTGRES_POOL_PRE_PING: bool = True
+ POSTGRES_POOL_RECYCLE: int = -1
DATABASE_URL_OVERRIDE: str | None = Field(
- default=config("DATABASE_URL", default=None),
+ default=None,
validation_alias="DATABASE_URL",
)
+ @model_validator(mode="before")
+ @classmethod
+ def _tables_follow_the_environment(cls, values: Any) -> Any:
+ """Default ``CREATE_TABLES_ON_STARTUP`` from the ``ENVIRONMENT`` these settings are built with."""
+ if not isinstance(values, dict) or "CREATE_TABLES_ON_STARTUP" in values:
+ return values
+ try:
+ creates = _creates_tables_by_default(values.get("ENVIRONMENT"))
+ except ValueError:
+ return values
+
+ return {**values, "CREATE_TABLES_ON_STARTUP": creates}
+
@property
def DATABASE_URL(self) -> str:
"""Get the full database URL.
@@ -126,12 +203,12 @@ def DATABASE_URL(self) -> str:
).render_as_string(hide_password=False)
-class CORSSettings(BaseSettings):
+class CORSSettings(EnvSettings):
"""CORS-related settings."""
- CORS_ENABLED: bool = config("CORS_ENABLED", default=True, cast=bool)
- CORS_ORIGINS: str = config("CORS_ORIGINS", default="http://localhost:3000,http://localhost:5173")
- CORS_ALLOW_CREDENTIALS: bool = config("CORS_ALLOW_CREDENTIALS", default=True, cast=bool)
+ CORS_ENABLED: bool = True
+ CORS_ORIGINS: str = "http://localhost:3000,http://localhost:5173"
+ CORS_ALLOW_CREDENTIALS: bool = True
@property
def CORS_ORIGINS_LIST(self) -> list[str]:
@@ -142,54 +219,54 @@ def CORS_ORIGINS_LIST(self) -> list[str]:
"""
return [origin.strip() for origin in self.CORS_ORIGINS.split(",") if origin.strip()]
- CORS_ALLOW_METHODS: str = config("CORS_ALLOW_METHODS", default="*")
- CORS_ALLOW_HEADERS: str = config("CORS_ALLOW_HEADERS", default="*")
+ CORS_ALLOW_METHODS: str = "*"
+ CORS_ALLOW_HEADERS: str = "*"
-class CompressionSettings(BaseSettings):
+class CompressionSettings(EnvSettings):
"""Compression-related settings."""
- GZIP_ENABLED: bool = config("GZIP_ENABLED", default=True, cast=bool)
- GZIP_MINIMUM_SIZE: int = config("GZIP_MINIMUM_SIZE", default=1000, cast=int)
+ GZIP_ENABLED: bool = True
+ GZIP_MINIMUM_SIZE: int = 1000
-class ClientCacheSettings(BaseSettings):
+class ClientCacheSettings(EnvSettings):
"""Cache-Control headers the app sets on its own responses."""
- CLIENT_CACHE_ENABLED: bool = config("CLIENT_CACHE_ENABLED", default=True, cast=bool)
- CLIENT_CACHE_MAX_AGE: int = config("CLIENT_CACHE_MAX_AGE", default=60, cast=int)
+ CLIENT_CACHE_ENABLED: bool = True
+ CLIENT_CACHE_MAX_AGE: int = 60
-class APIDocSettings(BaseSettings):
+class APIDocSettings(EnvSettings):
"""API documentation settings."""
- ENABLE_DOCS_IN_PRODUCTION: bool = config("ENABLE_DOCS_IN_PRODUCTION", default=False, cast=bool)
- OPENAPI_PREFIX: str = config("OPENAPI_PREFIX", default="")
- DOCS_URL: str = config("DOCS_URL", default="/docs")
- REDOC_URL: str = config("REDOC_URL", default="/redoc")
- OPENAPI_URL: str = config("OPENAPI_URL", default="/openapi.json")
+ ENABLE_DOCS_IN_PRODUCTION: bool = False
+ OPENAPI_PREFIX: str = ""
+ DOCS_URL: str = "/docs"
+ REDOC_URL: str = "/redoc"
+ OPENAPI_URL: str = "/openapi.json"
- API_TITLE: str = config("API_TITLE", default="")
- API_SUMMARY: str = config("API_SUMMARY", default="")
- API_DESCRIPTION: str = config("API_DESCRIPTION", default="")
- API_VERSION: str = config("API_VERSION", default="")
- API_TERMS_OF_SERVICE: str = config("API_TERMS_OF_SERVICE", default="")
+ API_TITLE: str = ""
+ API_SUMMARY: str = ""
+ API_DESCRIPTION: str = ""
+ API_VERSION: str = ""
+ API_TERMS_OF_SERVICE: str = ""
- API_CONTACT_NAME: str = config("API_CONTACT_NAME", default="")
- API_CONTACT_URL: str = config("API_CONTACT_URL", default="")
- API_CONTACT_EMAIL: str = config("API_CONTACT_EMAIL", default="")
+ API_CONTACT_NAME: str = ""
+ API_CONTACT_URL: str = ""
+ API_CONTACT_EMAIL: str = ""
- API_LICENSE_NAME: str = config("API_LICENSE_NAME", default="")
- API_LICENSE_URL: str = config("API_LICENSE_URL", default="")
- API_LICENSE_IDENTIFIER: str = config("API_LICENSE_IDENTIFIER", default="")
+ API_LICENSE_NAME: str = ""
+ API_LICENSE_URL: str = ""
+ API_LICENSE_IDENTIFIER: str = ""
- API_TAGS_METADATA: str = config("API_TAGS_METADATA", default="[]")
+ API_TAGS_METADATA: str = "[]"
-class APISettings(BaseSettings):
+class APISettings(EnvSettings):
"""API-related settings."""
- API_PREFIX: str = Field(default=config("API_PREFIX", default="/api"), validate_default=True)
+ API_PREFIX: str = Field(default="/api", validate_default=True)
@field_validator("API_PREFIX")
@classmethod
@@ -200,56 +277,56 @@ def _a_prefix_the_router_can_mount(cls, value: str) -> str:
return value
-class AppSettings(BaseSettings):
+class AppSettings(EnvSettings):
"""Application-related settings."""
# Note: For API documentation, prefer using API_* fields in APIDocSettings
- APP_NAME: str = config("APP_NAME", default="FastAPI Boilerplate")
- APP_DESCRIPTION: str = config("APP_DESCRIPTION", default="")
- DEBUG: bool = config("DEBUG", default=False, cast=bool)
- VERSION: str = config("VERSION", default="0.1.0")
+ APP_NAME: str = "FastAPI Boilerplate"
+ APP_DESCRIPTION: str = ""
+ DEBUG: bool = False
+ VERSION: str = "0.1.0"
-class EmailSettings(BaseSettings):
+class EmailSettings(EnvSettings):
"""How the account emails are delivered, and who they come from."""
- EMAIL_BACKEND: str = config("EMAIL_BACKEND", default=EmailBackend.CONSOLE.value)
- EMAIL_FROM: str = config("EMAIL_FROM", default="no-reply@localhost")
- EMAIL_FROM_NAME: str = config("EMAIL_FROM_NAME", default="")
+ EMAIL_BACKEND: str = EmailBackend.CONSOLE.value
+ EMAIL_FROM: str = "no-reply@localhost"
+ EMAIL_FROM_NAME: str = ""
- FRONTEND_URL: str = config("FRONTEND_URL", default="http://localhost:3000")
+ FRONTEND_URL: str = "http://localhost:3000"
- EMAIL_SMTP_HOST: str = config("EMAIL_SMTP_HOST", default="")
- EMAIL_SMTP_PORT: int = config("EMAIL_SMTP_PORT", default=587, cast=int)
- EMAIL_SMTP_USER: str = config("EMAIL_SMTP_USER", default="")
- EMAIL_SMTP_PASSWORD: str = config("EMAIL_SMTP_PASSWORD", default="")
- EMAIL_SMTP_STARTTLS: bool = config("EMAIL_SMTP_STARTTLS", default=True, cast=bool)
- EMAIL_SMTP_TIMEOUT_SECONDS: int = config("EMAIL_SMTP_TIMEOUT_SECONDS", default=10, cast=int)
+ EMAIL_SMTP_HOST: str = ""
+ EMAIL_SMTP_PORT: int = 587
+ EMAIL_SMTP_USER: str = ""
+ EMAIL_SMTP_PASSWORD: str = ""
+ EMAIL_SMTP_STARTTLS: bool = True
+ EMAIL_SMTP_TIMEOUT_SECONDS: int = 10
-class SecuritySettings(BaseSettings):
+class SecuritySettings(EnvSettings):
"""Security validation settings, and the secret every signed value derives from."""
- SECRET_KEY: str = config("SECRET_KEY", default="insecure-secret-key-change-this")
+ SECRET_KEY: str = "insecure-secret-key-change-this"
- PRODUCTION_SECURITY_VALIDATION_ENABLED: bool = config("PRODUCTION_SECURITY_VALIDATION_ENABLED", default=True, cast=bool)
- SECURITY_HEADERS_ENABLED: bool = config("SECURITY_HEADERS_ENABLED", default=True, cast=bool)
+ PRODUCTION_SECURITY_VALIDATION_ENABLED: bool = True
+ SECURITY_HEADERS_ENABLED: bool = True
-class LoggingSettings(BaseSettings):
+class LoggingSettings(EnvSettings):
"""Centralized logging configuration settings."""
- LOG_LEVEL: str = config("LOG_LEVEL", default=LogLevel.INFO.value)
- LOG_FORMAT: str = Field(default=config("LOG_FORMAT", default=""), validate_default=True)
+ LOG_LEVEL: str = LogLevel.INFO.value
+ LOG_FORMAT: str = Field(default="", validate_default=True)
- LOG_CONSOLE_ENABLED: bool = config("LOG_CONSOLE_ENABLED", default=True, cast=bool)
- LOG_FILE_ENABLED: bool = config("LOG_FILE_ENABLED", default=False, cast=bool)
- LOG_FILE_PATH: str = config("LOG_FILE_PATH", default="logs/app.log")
- LOG_FILE_MAX_SIZE: int = config("LOG_FILE_MAX_SIZE", default=10485760, cast=int)
- LOG_FILE_BACKUP_COUNT: int = config("LOG_FILE_BACKUP_COUNT", default=5, cast=int)
+ LOG_CONSOLE_ENABLED: bool = True
+ LOG_FILE_ENABLED: bool = False
+ LOG_FILE_PATH: str = "logs/app.log"
+ LOG_FILE_MAX_SIZE: int = 10485760
+ LOG_FILE_BACKUP_COUNT: int = 5
- LOG_DEVELOPMENT_VERBOSE: bool = config("LOG_DEVELOPMENT_VERBOSE", default=True, cast=bool)
- LOG_PRODUCTION_OPTIMIZE: bool = config("LOG_PRODUCTION_OPTIMIZE", default=True, cast=bool)
+ LOG_DEVELOPMENT_VERBOSE: bool = True
+ LOG_PRODUCTION_OPTIMIZE: bool = True
@field_validator("LOG_FORMAT")
@classmethod
diff --git a/backend/src/infrastructure/ratelimit/settings.py b/backend/src/infrastructure/ratelimit/settings.py
index 08eb30fb..60e72f88 100644
--- a/backend/src/infrastructure/ratelimit/settings.py
+++ b/backend/src/infrastructure/ratelimit/settings.py
@@ -1,13 +1,11 @@
"""Settings for the API rate-limit feature."""
-from pydantic_settings import BaseSettings
+from ..config.base import EnvSettings
-from ..config.base import config
-
-class RateLimitSettings(BaseSettings):
+class RateLimitSettings(EnvSettings):
"""Whether API routes are throttled, and the limit used when no tier row matches."""
- RATE_LIMITER_ENABLED: bool = config("RATE_LIMITER_ENABLED", default=True, cast=bool)
- DEFAULT_RATE_LIMIT_LIMIT: int = config("DEFAULT_RATE_LIMIT_LIMIT", default=100, cast=int)
- DEFAULT_RATE_LIMIT_PERIOD: int = config("DEFAULT_RATE_LIMIT_PERIOD", default=60, cast=int)
+ RATE_LIMITER_ENABLED: bool = True
+ DEFAULT_RATE_LIMIT_LIMIT: int = 100
+ DEFAULT_RATE_LIMIT_PERIOD: int = 60
diff --git a/backend/src/infrastructure/taskiq/settings.py b/backend/src/infrastructure/taskiq/settings.py
index c4556e5e..0f490f0a 100644
--- a/backend/src/infrastructure/taskiq/settings.py
+++ b/backend/src/infrastructure/taskiq/settings.py
@@ -2,31 +2,30 @@
from urllib.parse import quote
-from pydantic_settings import BaseSettings
from sqlalchemy.engine import URL
-from ..config.base import config
+from ..config.base import EnvSettings
from ..config.enums import TaskiqBrokerType
from ..redis import redis_url
-class TaskiqSettings(BaseSettings):
+class TaskiqSettings(EnvSettings):
"""Taskiq async task queue settings."""
- TASKIQ_BROKER_TYPE: str = config("TASKIQ_BROKER_TYPE", default=TaskiqBrokerType.REDIS.value)
- TASKIQ_DEFAULT_RETRY_COUNT: int = config("TASKIQ_DEFAULT_RETRY_COUNT", default=3, cast=int)
- TASKIQ_RETRY_DELAY_SECONDS: int = config("TASKIQ_RETRY_DELAY_SECONDS", default=0, cast=int)
+ TASKIQ_BROKER_TYPE: str = TaskiqBrokerType.REDIS.value
+ TASKIQ_DEFAULT_RETRY_COUNT: int = 3
+ TASKIQ_RETRY_DELAY_SECONDS: int = 0
- TASKIQ_REDIS_HOST: str = config("TASKIQ_REDIS_HOST", default="localhost")
- TASKIQ_REDIS_PORT: int = config("TASKIQ_REDIS_PORT", default=6379, cast=int)
- TASKIQ_REDIS_DB: int = config("TASKIQ_REDIS_DB", default=3, cast=int)
- TASKIQ_REDIS_PASSWORD: str | None = config("TASKIQ_REDIS_PASSWORD", default=None)
+ TASKIQ_REDIS_HOST: str = "localhost"
+ TASKIQ_REDIS_PORT: int = 6379
+ TASKIQ_REDIS_DB: int = 3
+ TASKIQ_REDIS_PASSWORD: str | None = None
- TASKIQ_RABBITMQ_HOST: str = config("TASKIQ_RABBITMQ_HOST", default="localhost")
- TASKIQ_RABBITMQ_PORT: int = config("TASKIQ_RABBITMQ_PORT", default=5672, cast=int)
- TASKIQ_RABBITMQ_USER: str = config("TASKIQ_RABBITMQ_USER", default="guest")
- TASKIQ_RABBITMQ_PASSWORD: str = config("TASKIQ_RABBITMQ_PASSWORD", default="guest")
- TASKIQ_RABBITMQ_VHOST: str = config("TASKIQ_RABBITMQ_VHOST", default="/")
+ TASKIQ_RABBITMQ_HOST: str = "localhost"
+ TASKIQ_RABBITMQ_PORT: int = 5672
+ TASKIQ_RABBITMQ_USER: str = "guest"
+ TASKIQ_RABBITMQ_PASSWORD: str = "guest"
+ TASKIQ_RABBITMQ_VHOST: str = "/"
@property
def TASKIQ_BROKER_URL(self) -> str:
diff --git a/backend/src/interfaces/admin/settings.py b/backend/src/interfaces/admin/settings.py
index 1c09511b..3d263d90 100644
--- a/backend/src/interfaces/admin/settings.py
+++ b/backend/src/interfaces/admin/settings.py
@@ -1,12 +1,10 @@
"""Settings for the SQLAdmin panel."""
-from pydantic_settings import BaseSettings
+from ...infrastructure.config.base import EnvSettings
-from ...infrastructure.config.base import config
-
-class SQLAdminSettings(BaseSettings):
+class SQLAdminSettings(EnvSettings):
"""SQLAdmin interface settings."""
- ADMIN_ENABLED: bool = config("ADMIN_ENABLED", default=False, cast=bool)
- ADMIN_BASE_URL: str = config("ADMIN_BASE_URL", default="/admin")
+ ADMIN_ENABLED: bool = False
+ ADMIN_BASE_URL: str = "/admin"
diff --git a/backend/src/modules/api_keys/settings.py b/backend/src/modules/api_keys/settings.py
index 44e43541..e62436a3 100644
--- a/backend/src/modules/api_keys/settings.py
+++ b/backend/src/modules/api_keys/settings.py
@@ -1,18 +1,15 @@
"""Settings for the API keys feature."""
from pydantic import Field
-from pydantic_settings import BaseSettings
-from ...infrastructure.config.base import config
+from ...infrastructure.config.base import EnvSettings
-class APIKeySettings(BaseSettings):
+class APIKeySettings(EnvSettings):
"""How long the usage rows a key's requests write are kept.
A day count below zero is refused as the settings load, where a typo would otherwise
read as the 0 that keeps every row.
"""
- KEY_USAGE_RETENTION_DAYS: int = Field(
- default=config("KEY_USAGE_RETENTION_DAYS", default=90, cast=int), ge=0, validate_default=True
- )
+ KEY_USAGE_RETENTION_DAYS: int = Field(default=90, ge=0, validate_default=True)
diff --git a/backend/src/modules/tier/hooks.py b/backend/src/modules/tier/hooks.py
new file mode 100644
index 00000000..630daaef
--- /dev/null
+++ b/backend/src/modules/tier/hooks.py
@@ -0,0 +1,15 @@
+"""What the tiers feature plugs into other features, listed in ``wiring.signup``."""
+
+from typing import Any
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from ...infrastructure.config.settings import settings
+from .crud import crud_tiers
+
+
+async def default_tier(db: AsyncSession) -> dict[str, Any]:
+ """The tier ``DEFAULT_TIER_NAME`` names, for a new account, or nothing while there is no such tier."""
+ tier = await crud_tiers.get(db=db, name=settings.DEFAULT_TIER_NAME, is_deleted=False)
+
+ return {"tier_id": tier["id"]} if tier else {}
diff --git a/backend/src/modules/tier/settings.py b/backend/src/modules/tier/settings.py
index 5a4c75b8..e7b748b6 100644
--- a/backend/src/modules/tier/settings.py
+++ b/backend/src/modules/tier/settings.py
@@ -1,11 +1,9 @@
"""Settings for the tiers feature."""
-from pydantic_settings import BaseSettings
+from ...infrastructure.config.base import EnvSettings
-from ...infrastructure.config.base import config
-
-class TierSettings(BaseSettings):
+class TierSettings(EnvSettings):
"""The tier new users are given when none is named."""
- DEFAULT_TIER_NAME: str = config("DEFAULT_TIER_NAME", default="free")
+ DEFAULT_TIER_NAME: str = "free"
diff --git a/backend/src/modules/user/routes.py b/backend/src/modules/user/routes.py
index 8a73326b..3bc926f6 100644
--- a/backend/src/modules/user/routes.py
+++ b/backend/src/modules/user/routes.py
@@ -42,7 +42,8 @@
- Email address
- Password (with security requirements)
- New accounts are automatically assigned to the default tier.
+ Columns other features add to an account are set as it is created, through
+ `src/wiring/signup.py`.
The answer says nothing about whether the address was free. An address that
already has an account is answered the same way as one that did not, and the
diff --git a/backend/src/modules/user/schemas.py b/backend/src/modules/user/schemas.py
index 002c6901..05619f3c 100644
--- a/backend/src/modules/user/schemas.py
+++ b/backend/src/modules/user/schemas.py
@@ -91,7 +91,12 @@ class UserCreate(UserBase):
class UserCreateInternal(UserBase):
- """Internal schema for user creation with hashed password."""
+ """Internal schema for user creation with hashed password.
+
+ It also carries the columns ``wiring.signup`` has other features set on a new account,
+ which the user module doesn't name."""
+
+ model_config = ConfigDict(extra="allow")
hashed_password: str
google_id: str | None = None
diff --git a/backend/src/modules/user/service.py b/backend/src/modules/user/service.py
index a9d85b5a..26dbaef9 100644
--- a/backend/src/modules/user/service.py
+++ b/backend/src/modules/user/service.py
@@ -10,6 +10,7 @@
from ...infrastructure.auth.setup import auth
from ...infrastructure.logging import get_logger
+from ...wiring.signup import NEW_ACCOUNT_FIELDS
from ..common.collisions import refused_constraint
from ..common.exceptions import (
PermissionDeniedError,
@@ -109,11 +110,17 @@ async def create(self, user: UserCreate, db: AsyncSession) -> dict[str, Any]:
if username_exists:
raise UserExistsError("Username already taken")
+ contributed: dict[str, Any] = {}
+ for fields in NEW_ACCOUNT_FIELDS:
+ contributed.update(await fields(db))
user_internal = UserCreateInternal(
- name=user.name,
- username=user.username,
- email=email,
- hashed_password=hashed_password,
+ **{
+ **auth.repo.filter_provisioning_data(contributed),
+ "name": user.name,
+ "username": user.username,
+ "email": email,
+ "hashed_password": hashed_password,
+ }
)
try:
created_user = await crud_users.create(db=db, object=user_internal, schema_to_select=UserRead)
diff --git a/backend/src/wiring/__init__.py b/backend/src/wiring/__init__.py
index 80bd5182..4cc6f27b 100644
--- a/backend/src/wiring/__init__.py
+++ b/backend/src/wiring/__init__.py
@@ -1,5 +1,5 @@
"""The composition root: where the selected features meet.
-Every module here is hand-maintained until the generator exists, and holds only
+Every module beside this one is generated by fastro from ``blueprint.toml``, and holds only
imports and literals, so ruff, mypy and an IDE see exactly what is wired.
"""
diff --git a/backend/src/wiring/admin.py b/backend/src/wiring/admin.py
index 683ae994..263ad262 100644
--- a/backend/src/wiring/admin.py
+++ b/backend/src/wiring/admin.py
@@ -1,6 +1,7 @@
"""The model views the admin panel registers.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from ..modules.role.admin import RoleAdmin, RolePermissionAdmin, UserRoleAdmin
diff --git a/backend/src/wiring/app.py b/backend/src/wiring/app.py
index bda0046e..02e62360 100644
--- a/backend/src/wiring/app.py
+++ b/backend/src/wiring/app.py
@@ -1,7 +1,7 @@
"""The composition root: what the app mounts, starts and installs.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only, so ruff, mypy and an IDE see exactly what is wired.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from collections.abc import Callable
diff --git a/backend/src/wiring/cache.py b/backend/src/wiring/cache.py
index ab4b866e..d53bd5b5 100644
--- a/backend/src/wiring/cache.py
+++ b/backend/src/wiring/cache.py
@@ -1,7 +1,7 @@
"""The decorator a route caches its response with.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from ..infrastructure.cache.decorator import cache as cached
diff --git a/backend/src/wiring/email.py b/backend/src/wiring/email.py
index 723a1086..d472e5c2 100644
--- a/backend/src/wiring/email.py
+++ b/backend/src/wiring/email.py
@@ -1,8 +1,9 @@
"""The sender the account emails go out through.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only. It is its own module because ``hooks`` reaches features that import the
-accounts feature back.
+It is its own module because ``hooks`` reaches features that import the accounts feature back.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from crudauth import EmailSender
diff --git a/backend/src/wiring/hooks.py b/backend/src/wiring/hooks.py
index 6d542e41..434d9f32 100644
--- a/backend/src/wiring/hooks.py
+++ b/backend/src/wiring/hooks.py
@@ -1,18 +1,12 @@
"""The contributions features make to each other's extension points.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from ..infrastructure.auth.health import limiter_readiness, sessions_readiness
from ..infrastructure.cache.health import readiness as cache_readiness
-from ..infrastructure.composition import (
- PermissionSource,
- RateLimitResolver,
- ReadinessCheck,
- TierDeleteGuard,
- TierDeleteRelease,
-)
+from ..infrastructure.composition import PermissionSource, RateLimitResolver, ReadinessCheck, TierDeleteGuard, TierDeleteRelease
from ..infrastructure.database.health import readiness as database_readiness
from ..infrastructure.database.health import schema_readiness
from ..infrastructure.taskiq.health import readiness as broker_readiness
diff --git a/backend/src/wiring/models.py b/backend/src/wiring/models.py
index a32214fa..363c4324 100644
--- a/backend/src/wiring/models.py
+++ b/backend/src/wiring/models.py
@@ -1,6 +1,7 @@
"""Extension points of the user model: what other features add to ``User``.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from ..modules.role.contrib import UserRoleColumns
diff --git a/backend/src/wiring/scope.py b/backend/src/wiring/scope.py
new file mode 100644
index 00000000..d97d4ab2
--- /dev/null
+++ b/backend/src/wiring/scope.py
@@ -0,0 +1,15 @@
+"""What tells a credential that carries a scope apart from its account's others.
+
+It is its own module, importing none of the other wiring, so that whatever keys what it stores by caller can read it.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
+"""
+
+from collections.abc import Callable
+
+from crudauth import Principal
+
+from ..infrastructure.auth.scope import scope_fingerprint
+
+SCOPE_FINGERPRINT: Callable[[Principal], str | None] | None = scope_fingerprint
diff --git a/backend/src/wiring/settings.py b/backend/src/wiring/settings.py
index 1d3d4b89..72a1c347 100644
--- a/backend/src/wiring/settings.py
+++ b/backend/src/wiring/settings.py
@@ -1,7 +1,9 @@
"""The project's settings: each selected feature's mixin on top of the core.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against. Core
-comes last, so a feature can override a core default rather than the other way round.
+Core comes last, so a feature can override a core default rather than the other way round.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
from ..infrastructure.auth.settings import AccountsSettings
diff --git a/backend/src/wiring/signup.py b/backend/src/wiring/signup.py
new file mode 100644
index 00000000..99ef452f
--- /dev/null
+++ b/backend/src/wiring/signup.py
@@ -0,0 +1,12 @@
+"""The columns features set on an account as it is created, on every signup path.
+
+The account setup reads it, so it is its own module: `wiring/hooks.py` reaches features that import the account setup back.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
+"""
+
+from ..infrastructure.composition import NewAccountFields
+from ..modules.tier.hooks import default_tier
+
+NEW_ACCOUNT_FIELDS: tuple[NewAccountFields, ...] = (default_tier,)
diff --git a/backend/src/wiring/tables.py b/backend/src/wiring/tables.py
index 3c9e797c..f18c7cf6 100644
--- a/backend/src/wiring/tables.py
+++ b/backend/src/wiring/tables.py
@@ -1,7 +1,7 @@
"""Modules outside ``src/modules`` that declare tables on ``Base.metadata``.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
TABLE_MODULES: tuple[str, ...] = ("src.infrastructure.auth.store",)
diff --git a/backend/src/wiring/tasks.py b/backend/src/wiring/tasks.py
index 5e529acd..6fd060b2 100644
--- a/backend/src/wiring/tasks.py
+++ b/backend/src/wiring/tasks.py
@@ -1,8 +1,12 @@
"""The modules whose background tasks the worker registers.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against:
-imports and literals only. A task the worker reports as unknown drops its message, so a module
-declaring one belongs in this list.
+A task the worker reports as unknown drops its message, so a module declaring one belongs in this list.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
-TASK_MODULES: tuple[str, ...] = ("src.infrastructure.taskiq.email", "src.modules.api_keys.tasks")
+TASK_MODULES: tuple[str, ...] = (
+ "src.infrastructure.taskiq.email",
+ "src.modules.api_keys.tasks",
+)
diff --git a/backend/src/wiring/transports.py b/backend/src/wiring/transports.py
index 8488ccd3..ffb4998b 100644
--- a/backend/src/wiring/transports.py
+++ b/backend/src/wiring/transports.py
@@ -1,4 +1,8 @@
-"""The authentication transports this project registers beside the session one."""
+"""The authentication transports this project registers beside the session one.
+
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
+"""
from crudauth import Transport
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 665d169b..38f6ab6d 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -16,8 +16,6 @@
os.environ.setdefault("ADMIN_ENABLED", "true")
os.environ.setdefault("ADMIN_USERNAME", "admin")
os.environ.setdefault("ADMIN_PASSWORD", "s3cret")
-os.environ.setdefault("SQLITE_URI", ":memory:")
-os.environ.setdefault("SQLITE_ASYNC_PREFIX", "sqlite+aiosqlite:///")
# Disable the testcontainers Ryuk reaper. Under `pytest -n auto`, each xdist worker
# is a separate process that spins up its own Ryuk container, and Docker Desktop
diff --git a/backend/tests/fixtures/accounts.py b/backend/tests/fixtures/accounts.py
index b08a397a..b6a65c91 100644
--- a/backend/tests/fixtures/accounts.py
+++ b/backend/tests/fixtures/accounts.py
@@ -1,38 +1,40 @@
"""Fixtures of the accounts feature: users, and clients signed in as them."""
import time
+from collections.abc import AsyncIterator
+from uuid import uuid4
import pytest
import pytest_asyncio
-from crudauth import Principal, get_password_hash
+from crudauth import get_password_hash
from crudauth.utils import canonical_email
from faker import Faker
-from httpx import AsyncClient
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import update
from sqlalchemy.ext.asyncio import AsyncSession
-from src.infrastructure.auth.dependencies import (
- get_current_principal,
- get_current_superuser,
- get_current_user,
- get_session_principal,
-)
from src.infrastructure.auth.setup import auth as crud_auth
from src.interfaces.main import app
from src.modules.user.models import User
+def new_user(*, prefix: str = "u", password: str = "Password123!", is_superuser: bool = False, profile_image_url: str) -> User:
+ """A user whose username and email no other fixture user has."""
+ unique = uuid4().hex
+ return User(
+ name=Faker().name(),
+ username=f"{prefix}{unique[:20]}",
+ email=f"{unique}@example.com",
+ hashed_password=get_password_hash(password),
+ is_superuser=is_superuser,
+ profile_image_url=profile_image_url,
+ )
+
+
@pytest_asyncio.fixture
async def test_user(db_session: AsyncSession):
"""Create a test user."""
- fake = Faker()
- user = User(
- name=fake.name(),
- username=f"u{fake.random_int(10000, 99999)}",
- email=fake.email(),
- hashed_password=get_password_hash("Password123!"),
- is_superuser=False,
- profile_image_url="https://example.com/test.jpg",
- )
+ user = new_user(profile_image_url="https://example.com/test.jpg")
db_session.add(user)
await db_session.commit()
await reset_password_budget(user.id)
@@ -51,15 +53,7 @@ async def test_user(db_session: AsyncSession):
@pytest_asyncio.fixture
async def test_user_2(db_session: AsyncSession):
"""Second test user for permission tests."""
- fake = Faker()
- user = User(
- name=fake.name(),
- username=f"u{fake.random_int(10000, 99999)}",
- email=fake.email(),
- hashed_password=get_password_hash("Password123!"),
- is_superuser=False,
- profile_image_url="https://example.com/test2.jpg",
- )
+ user = new_user(profile_image_url="https://example.com/test2.jpg")
db_session.add(user)
await db_session.commit()
await reset_password_budget(user.id)
@@ -77,14 +71,8 @@ async def test_user_2(db_session: AsyncSession):
@pytest_asyncio.fixture
async def test_superuser(db_session: AsyncSession):
"""Create a test superuser."""
- fake = Faker()
- user = User(
- name=fake.name(),
- username=f"su{fake.random_int(10000, 99999)}",
- email=fake.email(),
- hashed_password=get_password_hash("SuperuserPass123!"),
- is_superuser=True,
- profile_image_url="https://example.com/superuser.jpg",
+ user = new_user(
+ prefix="su", password="SuperuserPass123!", is_superuser=True, profile_image_url="https://example.com/superuser.jpg"
)
db_session.add(user)
await db_session.commit()
@@ -100,72 +88,57 @@ async def test_superuser(db_session: AsyncSession):
}
-def _principal_for(user: dict) -> Principal:
- """The crudauth principal the session transport would resolve for this user.
+async def _signed_in_as(user: dict, db: AsyncSession) -> AsyncIterator[AsyncClient]:
+ """A client of its own, signed in as ``user`` through the login route and carrying its CSRF token.
- The auth fixtures override the dict-compat dependencies, so anything reading
- the principal directly (permission checks, session routes) needs it too, the
- session-only dependency included: these clients stand for a signed-in session.
+ The address is marked verified first.
"""
- return Principal(
- user_id=user["id"],
- transport="session",
- is_superuser=user.get("is_superuser", False),
- email_verified=True,
- recovery_verified=True,
- )
+ await db.execute(update(User).where(User.id == user["id"]).values(email_verified=True))
+ await db.commit()
+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as signed_in:
+ response = await signed_in.post("/api/v1/auth/login", data={"username": user["username"], "password": user["password"]})
+ assert response.status_code == 200, response.text
+ signed_in.headers["X-CSRF-Token"] = response.json()["csrf_token"]
+ yield signed_in
@pytest_asyncio.fixture
-async def auth_client(client: AsyncClient, test_user: dict):
- """Authenticated test client (regular user) — overrides get_current_user dependency."""
-
- async def override_get_current_user():
- return test_user
-
- async def override_get_current_principal():
- return _principal_for(test_user)
+async def auth_client(
+ client: AsyncClient, db_session: AsyncSession, test_user: dict, fresh_login_lockout: None
+) -> AsyncIterator[AsyncClient]:
+ """A client signed in as ``test_user``, with a session of its own.
- app.dependency_overrides[get_current_user] = override_get_current_user
- app.dependency_overrides[get_current_principal] = override_get_current_principal
- app.dependency_overrides[get_session_principal] = override_get_current_principal
- return client
+ It takes ``client`` for the database override that fixture installs: without it the login route
+ reaches the app's own database instead of the test one.
+ """
+ async for signed_in in _signed_in_as(test_user, db_session):
+ yield signed_in
@pytest_asyncio.fixture
-async def auth_client_2(client: AsyncClient, test_user_2: dict):
- """Authenticated test client for second user."""
-
- async def override_get_current_user():
- return test_user_2
+async def auth_client_2(
+ client: AsyncClient, db_session: AsyncSession, test_user_2: dict, fresh_login_lockout: None
+) -> AsyncIterator[AsyncClient]:
+ """A client signed in as ``test_user_2``, with a session of its own beside ``auth_client``'s.
- async def override_get_current_principal():
- return _principal_for(test_user_2)
-
- app.dependency_overrides[get_current_user] = override_get_current_user
- app.dependency_overrides[get_current_principal] = override_get_current_principal
- app.dependency_overrides[get_session_principal] = override_get_current_principal
- return client
+ It takes ``client`` for the database override that fixture installs: without it the login route
+ reaches the app's own database instead of the test one.
+ """
+ async for signed_in in _signed_in_as(test_user_2, db_session):
+ yield signed_in
@pytest_asyncio.fixture
-async def superuser_auth_client(client: AsyncClient, test_superuser: dict):
- """Authenticated test client (superuser)."""
+async def superuser_auth_client(
+ client: AsyncClient, db_session: AsyncSession, test_superuser: dict, fresh_login_lockout: None
+) -> AsyncIterator[AsyncClient]:
+ """A client signed in as ``test_superuser``, with a session of its own beside the other two.
- async def override_get_current_user():
- return test_superuser
-
- async def override_get_current_principal():
- return _principal_for(test_superuser)
-
- async def override_get_current_superuser():
- return test_superuser
-
- app.dependency_overrides[get_current_user] = override_get_current_user
- app.dependency_overrides[get_current_principal] = override_get_current_principal
- app.dependency_overrides[get_session_principal] = override_get_current_principal
- app.dependency_overrides[get_current_superuser] = override_get_current_superuser
- return client
+ It takes ``client`` for the database override that fixture installs: without it the login route
+ reaches the app's own database instead of the test one.
+ """
+ async for signed_in in _signed_in_as(test_superuser, db_session):
+ yield signed_in
@pytest.fixture(autouse=True)
diff --git a/backend/tests/integration/api/v1/api_keys/test_read.py b/backend/tests/integration/api/v1/api_keys/test_read.py
index 3dfe4127..5fb6e722 100644
--- a/backend/tests/integration/api/v1/api_keys/test_read.py
+++ b/backend/tests/integration/api/v1/api_keys/test_read.py
@@ -9,8 +9,6 @@
from sqlalchemy import update
from sqlalchemy.ext.asyncio import AsyncSession
-from src.infrastructure.auth.dependencies import get_current_user
-from src.interfaces.main import app
from src.modules.api_keys.models import APIKey
pytestmark = pytest.mark.asyncio
@@ -25,13 +23,12 @@ async def test_a_missing_api_key_returns_the_generic_not_found(auth_client: Asyn
assert body["support_id"]
-async def test_another_users_api_key_is_forbidden_generically(auth_client: AsyncClient, test_user_2: dict):
+async def test_another_users_api_key_is_forbidden_generically(auth_client: AsyncClient, auth_client_2: AsyncClient):
created = await auth_client.post("/api/v1/api-keys/", json={"name": "Cross User Key"})
assert created.status_code == 201
key_id = created.json()["id"]
- app.dependency_overrides[get_current_user] = lambda: test_user_2
- response = await auth_client.get(f"/api/v1/api-keys/{key_id}")
+ response = await auth_client_2.get(f"/api/v1/api-keys/{key_id}")
assert response.status_code == 403
body = response.json()
diff --git a/backend/tests/integration/api/v1/test_read_endpoint_auth.py b/backend/tests/integration/api/v1/test_read_endpoint_auth.py
index 385cb18b..11610c6b 100644
--- a/backend/tests/integration/api/v1/test_read_endpoint_auth.py
+++ b/backend/tests/integration/api/v1/test_read_endpoint_auth.py
@@ -4,6 +4,8 @@
the routes it actually has instead of a list that has to be kept in step.
"""
+from typing import Any
+
import pytest
from fastapi.routing import APIRoute
from httpx import AsyncClient
@@ -19,7 +21,15 @@
)
-@pytest.mark.parametrize("path", COLLECTION_READS)
+def _cases(paths: list[str]) -> list[Any]:
+ """One case per path, or one skipped case that says why when there are none."""
+ if paths:
+ return list(paths)
+
+ return [pytest.param(None, marks=pytest.mark.skip(reason="this project has no collection reads under /api/v1/"))]
+
+
+@pytest.mark.parametrize("path", _cases(COLLECTION_READS))
async def test_read_endpoints_reject_anonymous_callers(client: AsyncClient, path: str):
"""None of the collection reads answer without a session."""
response = await client.get(path)
@@ -27,6 +37,14 @@ async def test_read_endpoints_reject_anonymous_callers(client: AsyncClient, path
assert response.status_code == 401
+async def test_a_project_with_no_collection_reads_says_why_the_rule_is_skipped():
+ (case,) = _cases([])
+ (mark,) = case.marks
+
+ assert mark.name == "skip"
+ assert mark.kwargs["reason"] == "this project has no collection reads under /api/v1/"
+
+
async def test_every_api_collection_read_is_covered():
"""A project with API routes must have found some; one with none has nothing to gate."""
api_routes = [route for route in app.routes if isinstance(route, APIRoute) and route.path.startswith("/api/v1/")]
diff --git a/backend/tests/integration/api/v1/users/test_delete.py b/backend/tests/integration/api/v1/users/test_delete.py
index e802fde7..24cfbb3f 100644
--- a/backend/tests/integration/api/v1/users/test_delete.py
+++ b/backend/tests/integration/api/v1/users/test_delete.py
@@ -2,8 +2,11 @@
import pytest
from httpx import AsyncClient
+from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from src.modules.user.models import User
+
from .test_create import generate_unique_user_data
logging.basicConfig(level=logging.INFO)
@@ -17,7 +20,8 @@ async def test_soft_delete_success(
db_session: AsyncSession,
test_user: dict,
):
- """Test successful soft deletion of user account."""
+ """Deleting one's own account soft-deletes the row, and the session it was signed in with no
+ longer signs it in."""
username = test_user["username"]
logger.info(f"Testing soft deletion for user: {username}")
@@ -28,7 +32,10 @@ async def test_soft_delete_success(
assert data["message"] == "User account deactivated"
get_response = await auth_client.get(f"/api/v1/users/{username}")
- assert get_response.status_code == 404
+ assert get_response.status_code == 401
+
+ deleted = await db_session.scalar(select(User.is_deleted).where(User.id == test_user["id"]))
+ assert deleted is True
async def test_soft_delete_unauthorized(
@@ -148,13 +155,13 @@ async def test_permanent_delete_nonexistent_user(
assert data["detail"] == "User not found."
-async def test_delete_cascade_effects(
+async def test_an_account_deleted_by_its_owner_is_gone_for_another_user(
auth_client: AsyncClient,
superuser_auth_client: AsyncClient,
db_session: AsyncSession,
test_user: dict,
):
- """Test cascade effects of user deletion."""
+ """A self-deleted account's profile answers 404 to another signed-in user."""
username = test_user["username"]
profile = await auth_client.get(f"/api/v1/users/{username}")
diff --git a/backend/tests/integration/auth/test_fixture_users.py b/backend/tests/integration/auth/test_fixture_users.py
new file mode 100644
index 00000000..47782e3b
--- /dev/null
+++ b/backend/tests/integration/auth/test_fixture_users.py
@@ -0,0 +1,21 @@
+"""Fixture users never collide, however many one test makes."""
+
+import pytest
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.modules.user.models import User
+from tests.fixtures import accounts
+
+
+async def test_two_thousand_fixture_users_fit_in_one_session(db_session: AsyncSession, monkeypatch: pytest.MonkeyPatch):
+ """The password hash is stubbed: two thousand real ones take minutes, and the
+ columns that must not collide are the username and the email."""
+ monkeypatch.setattr(accounts, "get_password_hash", lambda password: "not-a-hash")
+ users = [accounts.new_user(profile_image_url="https://example.com/test.jpg") for _ in range(2000)]
+ db_session.add_all(users)
+ await db_session.commit()
+
+ stored = await db_session.scalar(select(func.count()).where(User.id.in_([user.id for user in users])))
+
+ assert stored == 2000
diff --git a/backend/tests/integration/auth/test_two_clients.py b/backend/tests/integration/auth/test_two_clients.py
new file mode 100644
index 00000000..7ae95cbd
--- /dev/null
+++ b/backend/tests/integration/auth/test_two_clients.py
@@ -0,0 +1,24 @@
+"""The two signed-in client fixtures are two users, at the same time, in one test."""
+
+from httpx import AsyncClient
+
+
+async def test_each_client_is_signed_in_as_its_own_user(
+ auth_client: AsyncClient, auth_client_2: AsyncClient, test_user: dict, test_user_2: dict
+):
+ first = await auth_client.get("/api/v1/users/me")
+ second = await auth_client_2.get("/api/v1/users/me")
+
+ assert first.status_code == second.status_code == 200
+ assert first.json()["id"] == test_user["id"]
+ assert second.json()["id"] == test_user_2["id"]
+
+
+async def test_signing_one_client_out_leaves_the_other_signed_in(
+ auth_client: AsyncClient, auth_client_2: AsyncClient, test_user: dict
+):
+ signed_out = await auth_client_2.post("/api/v1/auth/logout")
+
+ assert signed_out.status_code == 200
+ assert (await auth_client_2.get("/api/v1/users/me")).status_code == 401
+ assert (await auth_client.get("/api/v1/users/me")).json()["id"] == test_user["id"]
diff --git a/backend/tests/integration/tiers/test_signup_tier.py b/backend/tests/integration/tiers/test_signup_tier.py
new file mode 100644
index 00000000..a25cdd85
--- /dev/null
+++ b/backend/tests/integration/tiers/test_signup_tier.py
@@ -0,0 +1,65 @@
+"""A new account is given the default tier, whether it signed up with a password or a provider."""
+
+import pytest
+from crudauth import NewUserContext
+from crudauth.provisioning import resolve_new_user_fields
+from httpx import AsyncClient
+from sqlalchemy import select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.infrastructure.auth.setup import auth
+from src.infrastructure.config.settings import settings
+from src.modules.tier.models import Tier
+from src.modules.user.models import User
+
+
+def _signup(username: str) -> dict[str, str]:
+ return {"name": "New Person", "username": username, "email": f"{username}@example.com", "password": "Password123!"}
+
+
+async def _signed_up(client: AsyncClient, db: AsyncSession, username: str) -> User:
+ response = await client.post("/api/v1/users/", json=_signup(username))
+ assert response.status_code == 201, response.text
+ stored = await db.scalar(select(User).where(User.username == username))
+ assert stored is not None
+
+ return stored
+
+
+async def test_a_signup_is_given_the_tier_default_tier_name_names(
+ client: AsyncClient, db_session: AsyncSession, second_test_tier: dict, test_tier: dict
+):
+ """Another tier was made first, so the one given is the one named, not the first there is."""
+ assert test_tier["name"] == settings.DEFAULT_TIER_NAME
+ assert second_test_tier["id"] < test_tier["id"]
+
+ assert (await _signed_up(client, db_session, "newcomer")).tier_id == test_tier["id"]
+
+
+async def test_a_signup_is_given_whichever_tier_default_tier_name_is_set_to(
+ client: AsyncClient, db_session: AsyncSession, test_tier: dict, second_test_tier: dict, monkeypatch: pytest.MonkeyPatch
+):
+ monkeypatch.setattr(settings, "DEFAULT_TIER_NAME", second_test_tier["name"])
+
+ assert (await _signed_up(client, db_session, "upgraded")).tier_id == second_test_tier["id"]
+
+
+async def test_a_signup_with_no_default_tier_there_yet_is_accepted_without_one(client: AsyncClient, db_session: AsyncSession):
+ assert (await _signed_up(client, db_session, "early")).tier_id is None
+
+
+async def test_a_signup_is_not_given_a_default_tier_that_was_deleted(
+ client: AsyncClient, db_session: AsyncSession, test_tier: dict
+):
+ await db_session.execute(update(Tier).where(Tier.id == test_tier["id"]).values(is_deleted=True))
+ await db_session.commit()
+
+ assert (await _signed_up(client, db_session, "late")).tier_id is None
+
+
+async def test_an_account_a_provider_signs_up_is_given_the_default_tier(db_session: AsyncSession, test_tier: dict):
+ context = NewUserContext(email="someone@example.com", username="someone", source="oauth", db=db_session)
+
+ fields = await resolve_new_user_fields(auth.new_user_fields, context, auth.repo)
+
+ assert fields["tier_id"] == test_tier["id"]
diff --git a/backend/tests/settings_defaults.py b/backend/tests/settings_defaults.py
index 343963b4..962ede55 100644
--- a/backend/tests/settings_defaults.py
+++ b/backend/tests/settings_defaults.py
@@ -1,35 +1,18 @@
-"""Reading a setting's declared default, whatever the environment the suite runs in.
+"""Reading a setting's default, whatever the environment the suite runs in.
A default is only a default where nothing sets the variable, and the suite sets several of
-them before it imports the app. So each read happens in a fresh interpreter whose
-environment is this one minus the variable being asked about.
+them before it imports the app. Settings read the environment when they're built, so each
+read builds them in this environment minus the variable being asked about.
"""
import os
-import subprocess
-import sys
-from pathlib import Path
+from unittest.mock import patch
-BACKEND_ROOT = Path(__file__).resolve().parents[1]
-
-_DECLARED_DEFAULT = """
from src.infrastructure.config.settings import Settings
-print("DEFAULT:" + str(Settings.model_fields[{name!r}].default))
-"""
-
def declared_default(name: str, **environment: str) -> str:
- """``Settings``' declared default for ``name``, as a string."""
+ """The value ``Settings`` gives ``name`` when nothing sets it, as a string."""
inherited = {key: value for key, value in os.environ.items() if key != name}
- result = subprocess.run(
- [sys.executable, "-c", _DECLARED_DEFAULT.format(name=name)],
- cwd=BACKEND_ROOT,
- capture_output=True,
- text=True,
- check=True,
- env={**inherited, **environment},
- )
- line = next(line for line in result.stdout.splitlines() if line.startswith("DEFAULT:"))
-
- return line.removeprefix("DEFAULT:")
+ with patch.dict(os.environ, {**inherited, **environment}, clear=True):
+ return str(getattr(Settings(), name))
diff --git a/backend/tests/unit/infrastructure/auth/test_setup.py b/backend/tests/unit/infrastructure/auth/test_setup.py
index cf3a2917..0f09df0e 100644
--- a/backend/tests/unit/infrastructure/auth/test_setup.py
+++ b/backend/tests/unit/infrastructure/auth/test_setup.py
@@ -225,7 +225,8 @@ def test_one_configured_provider_mounts_the_oauth_router(self, configured: dict[
class TestNewUserFields:
"""crudauth creates the account; the boilerplate supplies the required display name."""
- def test_the_display_name_is_filled_and_bounded(self):
+ async def test_the_display_name_is_filled_and_bounded(self, monkeypatch):
+ monkeypatch.setattr(setup, "NEW_ACCOUNT_FIELDS", ())
context = NewUserContext(
email="a" * (NAME_MAX_LENGTH + 10) + "@example.com",
username="auser",
@@ -233,10 +234,24 @@ def test_the_display_name_is_filled_and_bounded(self):
db=None, # type: ignore[arg-type]
)
- fields = setup._new_user_fields(context)
+ fields = await setup._new_user_fields(context)
- assert fields["name"] == "a" * NAME_MAX_LENGTH
- assert len(fields["name"]) == NAME_MAX_LENGTH
+ assert fields == {"name": "a" * NAME_MAX_LENGTH}
+
+ async def test_what_each_feature_sets_on_a_new_account_is_added(self, monkeypatch):
+ session = object()
+
+ async def first(db):
+ assert db is session
+ return {"tier_id": 3, "first_column": 1}
+
+ async def second(db):
+ return {"tier_id": 4, "org": "x", "name": "Someone Else"}
+
+ monkeypatch.setattr(setup, "NEW_ACCOUNT_FIELDS", (first, second))
+ context = NewUserContext(email="ann@example.com", username="ann", source="oauth", db=session) # type: ignore[arg-type]
+
+ assert await setup._new_user_fields(context) == {"name": "ann", "tier_id": 4, "first_column": 1, "org": "x"}
class TestSessionTransportWiring:
diff --git a/backend/tests/unit/infrastructure/cache/backends/test_memcached.py b/backend/tests/unit/infrastructure/cache/backends/test_memcached.py
index 232b1399..30a465ea 100644
--- a/backend/tests/unit/infrastructure/cache/backends/test_memcached.py
+++ b/backend/tests/unit/infrastructure/cache/backends/test_memcached.py
@@ -1,9 +1,17 @@
+"""The memcached backend, which a project only installs aiomcache for when it chooses it.
+
+The dependency belongs to the `cache.backend=memcached` option, and an option owns no paths, so
+a project on the default redis choice receives this file without the package it needs.
+"""
+
import json
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-from src.infrastructure.cache.backends.memcached import (
+pytest.importorskip("aiomcache")
+
+from src.infrastructure.cache.backends.memcached import ( # noqa: E402
MemcachedBackend,
MemcachedSettings,
PatternMatchingNotSupportedError,
diff --git a/backend/tests/unit/infrastructure/cache/test_decorator.py b/backend/tests/unit/infrastructure/cache/test_decorator.py
index da82705a..df5c938a 100644
--- a/backend/tests/unit/infrastructure/cache/test_decorator.py
+++ b/backend/tests/unit/infrastructure/cache/test_decorator.py
@@ -10,7 +10,6 @@
from fastapi.routing import APIRoute
from pydantic import BaseModel, Field
-from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER
from src.infrastructure.cache.decorator import cache
from src.infrastructure.cache.exceptions import InvalidRequestError
from src.infrastructure.uncached import cached as uncached
@@ -123,23 +122,6 @@ async def endpoint(request: Request, page: int = 1, items_per_page: int = 10) ->
crafted, real = (call.args[0] for call in backend.get.call_args_list)
assert crafted != real
- async def test_a_scoped_credential_does_not_share_an_entry_with_its_owners_session(self, backend):
- """A key holds its owner's permissions narrowed, so a response made for the owner's
- session is not one it may be served.
- """
- session = Principal(user_id=1, transport="session")
- scoped = Principal(user_id=1, transport="apikey", scopes=("user.read",), metadata={SCOPE_OWNER_IS_SUPERUSER: False})
-
- @cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal")
- async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]:
- return {"ok": True}
-
- await endpoint(_request(), item_id=7, principal=session)
- await endpoint(_request(), item_id=7, principal=scoped)
-
- asked = [call.args[0] for call in backend.get.call_args_list]
- assert asked[0] != asked[1]
-
async def test_each_caller_gets_their_own_entry(self, backend):
@cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal")
async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]:
diff --git a/backend/tests/unit/infrastructure/cache/test_scoped_callers.py b/backend/tests/unit/infrastructure/cache/test_scoped_callers.py
new file mode 100644
index 00000000..1445aedf
--- /dev/null
+++ b/backend/tests/unit/infrastructure/cache/test_scoped_callers.py
@@ -0,0 +1,55 @@
+"""A credential that carries a scope is cached apart from its account's other credentials."""
+
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from crudauth import Principal
+from fastapi import Request
+
+from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER
+from src.infrastructure.cache.decorator import cache
+from src.infrastructure.cache.utils import caller_marks
+
+
+def _scoped(*scope: str) -> Principal:
+ """A principal shaped as the API-key transport builds one."""
+ return Principal(user_id=7, transport="apikey", scopes=scope, metadata={"api_key_id": 1, SCOPE_OWNER_IS_SUPERUSER: False})
+
+
+def test_a_credential_that_carries_a_scope_is_marked_apart_from_the_account():
+ """A key holds its owner's permissions narrowed, so what it is served is its own."""
+ marked = caller_marks(_scoped("user.read"))
+
+ assert marked != "7"
+ assert marked is not None and marked.startswith("7/")
+
+
+def test_two_scopes_of_one_account_are_marked_apart():
+ assert caller_marks(_scoped("user.read")) != caller_marks(_scoped("user.read", "user.update"))
+
+
+def test_one_scope_written_in_either_order_is_marked_the_same():
+ """The order the names were stored in is the client's, and holds the same permissions."""
+ assert caller_marks(_scoped("user.read", "user.update")) == caller_marks(_scoped("user.update", "user.read"))
+
+
+@pytest.mark.asyncio
+async def test_a_scoped_credential_does_not_share_an_entry_with_its_owners_session():
+ """A key holds its owner's permissions narrowed, so a response made for the owner's session
+ is not one it may be served."""
+ recorded = AsyncMock()
+ recorded.get = AsyncMock(return_value=None)
+ request = Request({"type": "http", "method": "GET", "path": "/items", "query_string": b"", "headers": []})
+
+ @cache(key_prefix="keys", resource_id_name="item_id", caller_from="principal")
+ async def endpoint(request: Request, item_id: int, principal: Principal) -> dict[str, Any]:
+ return {"ok": True}
+
+ with patch("src.infrastructure.cache.decorator.cache_provider") as provider:
+ provider.get_backend.return_value = recorded
+ await endpoint(request, item_id=7, principal=Principal(user_id=7, transport="session"))
+ await endpoint(request, item_id=7, principal=_scoped("user.read"))
+
+ session, scoped = (call.args[0] for call in recorded.get.call_args_list)
+ assert session != scoped
diff --git a/backend/tests/unit/infrastructure/cache/test_utils.py b/backend/tests/unit/infrastructure/cache/test_utils.py
index 199dd9ff..5313d9b6 100644
--- a/backend/tests/unit/infrastructure/cache/test_utils.py
+++ b/backend/tests/unit/infrastructure/cache/test_utils.py
@@ -1,7 +1,8 @@
+import pytest
from crudauth import Principal
from starlette.datastructures import QueryParams
-from src.infrastructure.auth.scope import SCOPE_OWNER_IS_SUPERUSER
+from src.infrastructure.cache import utils
from src.infrastructure.cache.utils import (
caller_marks,
format_extra_data,
@@ -12,11 +13,6 @@
DECLARED = {"page", "items_per_page"}
-def _scoped(*scope: str) -> Principal:
- """A principal shaped as the API-key transport builds one."""
- return Principal(user_id=7, transport="apikey", scopes=scope, metadata={"api_key_id": 1, SCOPE_OWNER_IS_SUPERUSER: False})
-
-
def test_the_query_is_the_declared_parameters_sorted():
assert format_query(QueryParams("page=2&items_per_page=20"), DECLARED) == "items_per_page=20&page=2"
@@ -38,21 +34,17 @@ def test_a_session_is_marked_by_the_account_it_signed_in_as():
assert caller_marks(Principal(user_id=7, transport="session")) == "7"
-def test_a_credential_that_carries_a_scope_is_marked_apart_from_the_account():
- """A key holds its owner's permissions narrowed, so what it is served is its own."""
- marked = caller_marks(_scoped("user.read"))
-
- assert marked != "7"
- assert marked is not None and marked.startswith("7/")
+def test_a_principal_is_marked_by_its_account_and_the_fingerprint_wired(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(utils, "SCOPE_FINGERPRINT", lambda principal: "narrowed")
+ assert caller_marks(Principal(user_id=7, transport="apikey", scopes=("user.read",))) == "7/narrowed"
-def test_two_scopes_of_one_account_are_marked_apart():
- assert caller_marks(_scoped("user.read")) != caller_marks(_scoped("user.read", "user.update"))
+def test_without_a_fingerprint_wired_a_principal_is_marked_by_its_account(monkeypatch: pytest.MonkeyPatch):
+ """A project without accounts wires none, and has no credential that carries a scope."""
+ monkeypatch.setattr(utils, "SCOPE_FINGERPRINT", None)
-def test_one_scope_written_in_either_order_is_marked_the_same():
- """The order the names were stored in is the client's, and holds the same permissions."""
- assert caller_marks(_scoped("user.read", "user.update")) == caller_marks(_scoped("user.update", "user.read"))
+ assert caller_marks(Principal(user_id=7, transport="apikey", scopes=("user.read",))) == "7"
def test_an_account_read_any_other_way_is_marked_with_nothing():
diff --git a/backend/tests/unit/infrastructure/config/conftest.py b/backend/tests/unit/infrastructure/config/conftest.py
new file mode 100644
index 00000000..a06161d1
--- /dev/null
+++ b/backend/tests/unit/infrastructure/config/conftest.py
@@ -0,0 +1,23 @@
+import importlib
+from pathlib import Path
+
+import pytest
+
+import src.infrastructure.config.base as base
+
+
+@pytest.fixture
+def reloaded():
+ """Re-import the settings module under the test's conditions, and put it back afterwards."""
+ yield lambda: importlib.reload(base)
+ importlib.reload(base)
+
+
+@pytest.fixture
+def found_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Path:
+ """``tmp_path/.env``, as the file the module finds where it would find ``backend/.env``."""
+ found = tmp_path / ".env"
+ found.write_text("")
+ monkeypatch.setattr(base.os.path, "realpath", lambda path: str(tmp_path / "src" / "infrastructure" / "config" / "base.py"))
+
+ return found
diff --git a/backend/tests/unit/infrastructure/config/defaults.json b/backend/tests/unit/infrastructure/config/defaults.json
new file mode 100644
index 00000000..b2a3bd04
--- /dev/null
+++ b/backend/tests/unit/infrastructure/config/defaults.json
@@ -0,0 +1,138 @@
+{
+ "ADMIN_BASE_URL": "'/admin'",
+ "ADMIN_EMAIL": "''",
+ "ADMIN_ENABLED": "False",
+ "ADMIN_NAME": "''",
+ "ADMIN_PASSWORD": "''",
+ "ADMIN_USERNAME": "''",
+ "API_CONTACT_EMAIL": "''",
+ "API_CONTACT_NAME": "''",
+ "API_CONTACT_URL": "''",
+ "API_DESCRIPTION": "''",
+ "API_LICENSE_IDENTIFIER": "''",
+ "API_LICENSE_NAME": "''",
+ "API_LICENSE_URL": "''",
+ "API_PREFIX": "'/api'",
+ "API_SUMMARY": "''",
+ "API_TAGS_METADATA": "'[]'",
+ "API_TERMS_OF_SERVICE": "''",
+ "API_TITLE": "''",
+ "API_VERSION": "''",
+ "APP_DESCRIPTION": "''",
+ "APP_NAME": "'FastAPI Boilerplate'",
+ "CACHE_BACKEND": "'redis'",
+ "CACHE_ENABLED": "True",
+ "CACHE_MEMCACHED_CONNECT_TIMEOUT": "5",
+ "CACHE_MEMCACHED_HOST": "'localhost'",
+ "CACHE_MEMCACHED_POOL_SIZE": "10",
+ "CACHE_MEMCACHED_PORT": "11211",
+ "CACHE_REDIS_CONNECT_TIMEOUT": "5",
+ "CACHE_REDIS_DB": "0",
+ "CACHE_REDIS_HOST": "'localhost'",
+ "CACHE_REDIS_PASSWORD": "None",
+ "CACHE_REDIS_POOL_SIZE": "10",
+ "CACHE_REDIS_PORT": "6379",
+ "CLIENT_CACHE_ENABLED": "True",
+ "CLIENT_CACHE_MAX_AGE": "60",
+ "CORS_ALLOW_CREDENTIALS": "True",
+ "CORS_ALLOW_HEADERS": "'*'",
+ "CORS_ALLOW_METHODS": "'*'",
+ "CORS_ENABLED": "True",
+ "CORS_ORIGINS": "'http://localhost:3000,http://localhost:5173'",
+ "CREATE_TABLES_ON_STARTUP": "True",
+ "CSRF_ENABLED": "True",
+ "DATABASE_URL_OVERRIDE": "None",
+ "DEBUG": "False",
+ "DEFAULT_RATE_LIMIT_LIMIT": "100",
+ "DEFAULT_RATE_LIMIT_PERIOD": "60",
+ "DEFAULT_TIER_NAME": "'free'",
+ "DOCS_URL": "'/docs'",
+ "EMAIL_BACKEND": "'console'",
+ "EMAIL_FROM": "'no-reply@localhost'",
+ "EMAIL_FROM_NAME": "''",
+ "EMAIL_SMTP_HOST": "''",
+ "EMAIL_SMTP_PASSWORD": "''",
+ "EMAIL_SMTP_PORT": "587",
+ "EMAIL_SMTP_STARTTLS": "True",
+ "EMAIL_SMTP_TIMEOUT_SECONDS": "10",
+ "EMAIL_SMTP_USER": "''",
+ "ENABLE_DOCS_IN_PRODUCTION": "False",
+ "ENVIRONMENT": "",
+ "FRESH_SIGN_IN_SECONDS": "None",
+ "FRONTEND_URL": "'http://localhost:3000'",
+ "GZIP_ENABLED": "True",
+ "GZIP_MINIMUM_SIZE": "1000",
+ "KEY_USAGE_RETENTION_DAYS": "90",
+ "LOGIN_ATTEMPT_WINDOW_SECONDS": "900",
+ "LOGIN_LOCKOUT_BASE_SECONDS": "300",
+ "LOGIN_LOCKOUT_MAX_SECONDS": "3600",
+ "LOGIN_MAX_ATTEMPTS": "5",
+ "LOG_CONSOLE_ENABLED": "True",
+ "LOG_DEVELOPMENT_VERBOSE": "True",
+ "LOG_FILE_BACKUP_COUNT": "5",
+ "LOG_FILE_ENABLED": "False",
+ "LOG_FILE_MAX_SIZE": "10485760",
+ "LOG_FILE_PATH": "'logs/app.log'",
+ "LOG_FORMAT": "''",
+ "LOG_LEVEL": "'INFO'",
+ "LOG_PRODUCTION_OPTIMIZE": "True",
+ "MAX_SESSIONS_PER_USER": "5",
+ "OAUTH_GITHUB_CLIENT_ID": "''",
+ "OAUTH_GITHUB_CLIENT_SECRET": "''",
+ "OAUTH_GOOGLE_CLIENT_ID": "''",
+ "OAUTH_GOOGLE_CLIENT_SECRET": "''",
+ "OAUTH_REDIRECT_BASE_URL": "'http://localhost:8000'",
+ "OPENAPI_PREFIX": "''",
+ "OPENAPI_URL": "'/openapi.json'",
+ "PASSWORD_MIN_LENGTH": "8",
+ "PASSWORD_REQUIRE_DIGIT": "True",
+ "PASSWORD_REQUIRE_LOWERCASE": "True",
+ "PASSWORD_REQUIRE_SPECIAL": "True",
+ "PASSWORD_REQUIRE_UPPERCASE": "True",
+ "POSTGRES_ASYNC_PREFIX": "'postgresql+asyncpg://'",
+ "POSTGRES_DB": "'postgres'",
+ "POSTGRES_MAX_OVERFLOW": "0",
+ "POSTGRES_PASSWORD": "'postgres'",
+ "POSTGRES_POOL_PRE_PING": "True",
+ "POSTGRES_POOL_RECYCLE": "-1",
+ "POSTGRES_POOL_SIZE": "20",
+ "POSTGRES_PORT": "5432",
+ "POSTGRES_SERVER": "'localhost'",
+ "POSTGRES_USER": "'postgres'",
+ "PRODUCTION_SECURITY_VALIDATION_ENABLED": "True",
+ "RATE_LIMITER_BACKEND": "'redis'",
+ "RATE_LIMITER_ENABLED": "True",
+ "RATE_LIMITER_REDIS_CONNECT_TIMEOUT": "5",
+ "RATE_LIMITER_REDIS_DB": "1",
+ "RATE_LIMITER_REDIS_HOST": "'localhost'",
+ "RATE_LIMITER_REDIS_PASSWORD": "None",
+ "RATE_LIMITER_REDIS_POOL_SIZE": "10",
+ "RATE_LIMITER_REDIS_PORT": "6379",
+ "REDOC_URL": "'/redoc'",
+ "SECRET_KEY": "'insecure-secret-key-change-this'",
+ "SECURITY_HEADERS_ENABLED": "True",
+ "SESSION_ABSOLUTE_TIMEOUT_HOURS": "None",
+ "SESSION_BACKEND": "'redis'",
+ "SESSION_CLEANUP_INTERVAL_MINUTES": "15",
+ "SESSION_REDIS_DB": "2",
+ "SESSION_REDIS_HOST": "'localhost'",
+ "SESSION_REDIS_PASSWORD": "None",
+ "SESSION_REDIS_PORT": "6379",
+ "SESSION_REDIS_URL_OVERRIDE": "None",
+ "SESSION_SECURE_COOKIES": "True",
+ "SESSION_TIMEOUT_MINUTES": "30",
+ "TASKIQ_BROKER_TYPE": "'redis'",
+ "TASKIQ_DEFAULT_RETRY_COUNT": "3",
+ "TASKIQ_RABBITMQ_HOST": "'localhost'",
+ "TASKIQ_RABBITMQ_PASSWORD": "'guest'",
+ "TASKIQ_RABBITMQ_PORT": "5672",
+ "TASKIQ_RABBITMQ_USER": "'guest'",
+ "TASKIQ_RABBITMQ_VHOST": "'/'",
+ "TASKIQ_REDIS_DB": "3",
+ "TASKIQ_REDIS_HOST": "'localhost'",
+ "TASKIQ_REDIS_PASSWORD": "None",
+ "TASKIQ_REDIS_PORT": "6379",
+ "TASKIQ_RETRY_DELAY_SECONDS": "0",
+ "TRUSTED_PROXY_HOPS": "0",
+ "VERSION": "'0.1.0'"
+}
\ No newline at end of file
diff --git a/backend/tests/unit/infrastructure/config/example_values.json b/backend/tests/unit/infrastructure/config/example_values.json
new file mode 100644
index 00000000..d720b61f
--- /dev/null
+++ b/backend/tests/unit/infrastructure/config/example_values.json
@@ -0,0 +1,138 @@
+{
+ "ADMIN_BASE_URL": "'/admin'",
+ "ADMIN_EMAIL": "'admin@example.com'",
+ "ADMIN_ENABLED": "False",
+ "ADMIN_NAME": "'Admin User'",
+ "ADMIN_PASSWORD": "'Change-Me-Now-1!'",
+ "ADMIN_USERNAME": "'admin'",
+ "API_CONTACT_EMAIL": "''",
+ "API_CONTACT_NAME": "''",
+ "API_CONTACT_URL": "''",
+ "API_DESCRIPTION": "''",
+ "API_LICENSE_IDENTIFIER": "''",
+ "API_LICENSE_NAME": "''",
+ "API_LICENSE_URL": "''",
+ "API_PREFIX": "'/api'",
+ "API_SUMMARY": "''",
+ "API_TAGS_METADATA": "'[]'",
+ "API_TERMS_OF_SERVICE": "''",
+ "API_TITLE": "''",
+ "API_VERSION": "''",
+ "APP_DESCRIPTION": "'Modular FastAPI starter'",
+ "APP_NAME": "'FastAPI Boilerplate'",
+ "CACHE_BACKEND": "'redis'",
+ "CACHE_ENABLED": "True",
+ "CACHE_MEMCACHED_CONNECT_TIMEOUT": "5",
+ "CACHE_MEMCACHED_HOST": "'localhost'",
+ "CACHE_MEMCACHED_POOL_SIZE": "10",
+ "CACHE_MEMCACHED_PORT": "11211",
+ "CACHE_REDIS_CONNECT_TIMEOUT": "5",
+ "CACHE_REDIS_DB": "0",
+ "CACHE_REDIS_HOST": "'redis'",
+ "CACHE_REDIS_PASSWORD": "''",
+ "CACHE_REDIS_POOL_SIZE": "10",
+ "CACHE_REDIS_PORT": "6379",
+ "CLIENT_CACHE_ENABLED": "True",
+ "CLIENT_CACHE_MAX_AGE": "60",
+ "CORS_ALLOW_CREDENTIALS": "True",
+ "CORS_ALLOW_HEADERS": "'*'",
+ "CORS_ALLOW_METHODS": "'*'",
+ "CORS_ENABLED": "True",
+ "CORS_ORIGINS": "'http://localhost:3000,http://localhost:5173'",
+ "CREATE_TABLES_ON_STARTUP": "True",
+ "CSRF_ENABLED": "True",
+ "DATABASE_URL_OVERRIDE": "None",
+ "DEBUG": "False",
+ "DEFAULT_RATE_LIMIT_LIMIT": "100",
+ "DEFAULT_RATE_LIMIT_PERIOD": "60",
+ "DEFAULT_TIER_NAME": "'free'",
+ "DOCS_URL": "'/docs'",
+ "EMAIL_BACKEND": "'console'",
+ "EMAIL_FROM": "'no-reply@localhost'",
+ "EMAIL_FROM_NAME": "''",
+ "EMAIL_SMTP_HOST": "''",
+ "EMAIL_SMTP_PASSWORD": "''",
+ "EMAIL_SMTP_PORT": "587",
+ "EMAIL_SMTP_STARTTLS": "True",
+ "EMAIL_SMTP_TIMEOUT_SECONDS": "10",
+ "EMAIL_SMTP_USER": "''",
+ "ENABLE_DOCS_IN_PRODUCTION": "False",
+ "ENVIRONMENT": "",
+ "FRESH_SIGN_IN_SECONDS": "None",
+ "FRONTEND_URL": "'http://localhost:3000'",
+ "GZIP_ENABLED": "True",
+ "GZIP_MINIMUM_SIZE": "1000",
+ "KEY_USAGE_RETENTION_DAYS": "90",
+ "LOGIN_ATTEMPT_WINDOW_SECONDS": "900",
+ "LOGIN_LOCKOUT_BASE_SECONDS": "300",
+ "LOGIN_LOCKOUT_MAX_SECONDS": "3600",
+ "LOGIN_MAX_ATTEMPTS": "5",
+ "LOG_CONSOLE_ENABLED": "True",
+ "LOG_DEVELOPMENT_VERBOSE": "True",
+ "LOG_FILE_BACKUP_COUNT": "5",
+ "LOG_FILE_ENABLED": "False",
+ "LOG_FILE_MAX_SIZE": "10485760",
+ "LOG_FILE_PATH": "'logs/app.log'",
+ "LOG_FORMAT": "''",
+ "LOG_LEVEL": "'INFO'",
+ "LOG_PRODUCTION_OPTIMIZE": "True",
+ "MAX_SESSIONS_PER_USER": "5",
+ "OAUTH_GITHUB_CLIENT_ID": "''",
+ "OAUTH_GITHUB_CLIENT_SECRET": "''",
+ "OAUTH_GOOGLE_CLIENT_ID": "''",
+ "OAUTH_GOOGLE_CLIENT_SECRET": "''",
+ "OAUTH_REDIRECT_BASE_URL": "'http://localhost:8000'",
+ "OPENAPI_PREFIX": "''",
+ "OPENAPI_URL": "'/openapi.json'",
+ "PASSWORD_MIN_LENGTH": "8",
+ "PASSWORD_REQUIRE_DIGIT": "True",
+ "PASSWORD_REQUIRE_LOWERCASE": "True",
+ "PASSWORD_REQUIRE_SPECIAL": "True",
+ "PASSWORD_REQUIRE_UPPERCASE": "True",
+ "POSTGRES_ASYNC_PREFIX": "'postgresql+asyncpg://'",
+ "POSTGRES_DB": "'postgres'",
+ "POSTGRES_MAX_OVERFLOW": "0",
+ "POSTGRES_PASSWORD": "'postgres'",
+ "POSTGRES_POOL_PRE_PING": "True",
+ "POSTGRES_POOL_RECYCLE": "-1",
+ "POSTGRES_POOL_SIZE": "20",
+ "POSTGRES_PORT": "5432",
+ "POSTGRES_SERVER": "'postgres'",
+ "POSTGRES_USER": "'postgres'",
+ "PRODUCTION_SECURITY_VALIDATION_ENABLED": "True",
+ "RATE_LIMITER_BACKEND": "'redis'",
+ "RATE_LIMITER_ENABLED": "True",
+ "RATE_LIMITER_REDIS_CONNECT_TIMEOUT": "5",
+ "RATE_LIMITER_REDIS_DB": "1",
+ "RATE_LIMITER_REDIS_HOST": "'redis'",
+ "RATE_LIMITER_REDIS_PASSWORD": "''",
+ "RATE_LIMITER_REDIS_POOL_SIZE": "10",
+ "RATE_LIMITER_REDIS_PORT": "6379",
+ "REDOC_URL": "'/redoc'",
+ "SECRET_KEY": "'insecure-secret-key-change-this-in-production'",
+ "SECURITY_HEADERS_ENABLED": "True",
+ "SESSION_ABSOLUTE_TIMEOUT_HOURS": "None",
+ "SESSION_BACKEND": "'redis'",
+ "SESSION_CLEANUP_INTERVAL_MINUTES": "15",
+ "SESSION_REDIS_DB": "2",
+ "SESSION_REDIS_HOST": "'redis'",
+ "SESSION_REDIS_PASSWORD": "''",
+ "SESSION_REDIS_PORT": "6379",
+ "SESSION_REDIS_URL_OVERRIDE": "None",
+ "SESSION_SECURE_COOKIES": "True",
+ "SESSION_TIMEOUT_MINUTES": "30",
+ "TASKIQ_BROKER_TYPE": "'redis'",
+ "TASKIQ_DEFAULT_RETRY_COUNT": "3",
+ "TASKIQ_RABBITMQ_HOST": "'localhost'",
+ "TASKIQ_RABBITMQ_PASSWORD": "'guest'",
+ "TASKIQ_RABBITMQ_PORT": "5672",
+ "TASKIQ_RABBITMQ_USER": "'guest'",
+ "TASKIQ_RABBITMQ_VHOST": "'/'",
+ "TASKIQ_REDIS_DB": "3",
+ "TASKIQ_REDIS_HOST": "'redis'",
+ "TASKIQ_REDIS_PASSWORD": "''",
+ "TASKIQ_REDIS_PORT": "6379",
+ "TASKIQ_RETRY_DELAY_SECONDS": "0",
+ "TRUSTED_PROXY_HOPS": "0",
+ "VERSION": "'0.1.0'"
+}
\ No newline at end of file
diff --git a/backend/tests/unit/infrastructure/config/test_env_file.py b/backend/tests/unit/infrastructure/config/test_env_file.py
index 019c5e7e..38931d2c 100644
--- a/backend/tests/unit/infrastructure/config/test_env_file.py
+++ b/backend/tests/unit/infrastructure/config/test_env_file.py
@@ -5,23 +5,13 @@
operator command the image runs.
"""
-import importlib
import logging
import os
import warnings
-import pytest
-
import src.infrastructure.config.base as base
-@pytest.fixture
-def reloaded():
- """Re-import the module under the test's conditions, and put it back afterwards."""
- yield lambda: importlib.reload(base)
- importlib.reload(base)
-
-
def test_with_no_environment_file_nothing_warns(reloaded, monkeypatch, caplog):
"""Starlette warns about a file it was handed and could not find, so it is handed none."""
monkeypatch.setattr(os.path, "isfile", lambda path: False)
@@ -37,10 +27,8 @@ def test_with_no_environment_file_nothing_warns(reloaded, monkeypatch, caplog):
assert "settings are read from the environment" in caplog.text
-def test_an_environment_file_that_exists_is_the_one_read(reloaded, monkeypatch, tmp_path, caplog):
- stored = tmp_path / ".env"
- stored.write_text("ENVIRONMENT=local\n")
- monkeypatch.setattr(base.os.path, "realpath", lambda path: str(tmp_path / "src" / "infrastructure" / "config" / "base.py"))
+def test_an_environment_file_that_exists_is_the_one_read(reloaded, found_file, monkeypatch, caplog):
+ stored = found_file
monkeypatch.delenv("PYTEST_VERSION", raising=False)
monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
diff --git a/backend/tests/unit/infrastructure/config/test_settings.py b/backend/tests/unit/infrastructure/config/test_settings.py
index d736458c..ad265146 100644
--- a/backend/tests/unit/infrastructure/config/test_settings.py
+++ b/backend/tests/unit/infrastructure/config/test_settings.py
@@ -127,14 +127,6 @@ def test_required_settings_exist(self):
assert hasattr(settings, attr), f"Missing required setting: {attr}"
assert getattr(settings, attr) is not None, f"Setting {attr} is None"
- @patch.dict(os.environ, {"SQLITE_URI": ":memory:"})
- def test_test_database_override(self):
- """Test that test database settings work."""
- settings = Settings()
- # In test mode, should use in-memory database
- if hasattr(settings, "SQLITE_URI"):
- assert ":memory:" in settings.SQLITE_URI
-
class TestCORSSettings:
"""Credentialed requests reject a wildcard origin, so the default must not be one."""
diff --git a/backend/tests/unit/infrastructure/config/test_settings_build.py b/backend/tests/unit/infrastructure/config/test_settings_build.py
new file mode 100644
index 00000000..476aacd7
--- /dev/null
+++ b/backend/tests/unit/infrastructure/config/test_settings_build.py
@@ -0,0 +1,212 @@
+"""Settings read the environment and the environment file when they're built, not when imported."""
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+from pydantic import ValidationError
+from pydantic_settings import BaseSettings
+
+import src.infrastructure.config.base as base
+import src.infrastructure.config.settings as facade
+from src.infrastructure.config.base import CoreSettings, EnvironmentOption, SecuritySettings
+from src.infrastructure.config.settings import Settings
+
+
+def test_a_variable_deleted_after_import_falls_back_to_the_default(reloaded, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.delenv("SECRET_KEY", raising=False)
+ default = base.SecuritySettings().SECRET_KEY
+ monkeypatch.setenv("SECRET_KEY", "set-before-the-import-" + "x" * 32)
+ reloaded()
+
+ monkeypatch.delenv("SECRET_KEY")
+
+ assert base.SecuritySettings().SECRET_KEY == default
+
+
+def test_the_file_found_is_read_when_the_settings_are_built(reloaded, found_file: Path, monkeypatch: pytest.MonkeyPatch):
+ found = found_file
+ monkeypatch.delenv("PYTEST_VERSION", raising=False)
+ monkeypatch.delenv("PYTEST_CURRENT_TEST", raising=False)
+ monkeypatch.delenv("APP_NAME", raising=False)
+ reloaded()
+
+ found.write_text("APP_NAME=Written After The Import\n")
+
+ assert base.AppSettings().APP_NAME == "Written After The Import"
+
+
+def test_no_file_is_read_under_pytest(reloaded, found_file: Path, monkeypatch: pytest.MonkeyPatch):
+ found = found_file
+ found.write_text("APP_NAME=Only The File Says So\n")
+ monkeypatch.setenv("PYTEST_VERSION", "set")
+ monkeypatch.delenv("APP_NAME", raising=False)
+ reloaded()
+
+ assert base.EnvSettings.model_config["env_file"] is None
+ assert base.AppSettings().APP_NAME != "Only The File Says So"
+
+
+def test_the_file_is_read_literally_as_it_always_was(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+ """A secret with `${...}` in it stays as written; a `#` is part of the value; `export` lines and
+ names in another case aren't the setting."""
+ for name in ("SECRET_KEY", "APP_NAME", "APP_DESCRIPTION"):
+ monkeypatch.delenv(name, raising=False)
+ stored = tmp_path / ".env"
+ stored.write_text(
+ "SECRET_KEY=ab${HOME}cd-long-enough-to-be-a-key-0123456789\n"
+ "APP_NAME=foo # not a comment\n"
+ "export APP_DESCRIPTION=exported\n"
+ "app_description=lower\n"
+ )
+ built = Settings(_env_file=stored)
+
+ assert built.SECRET_KEY == "ab${HOME}cd-long-enough-to-be-a-key-0123456789"
+ assert built.APP_NAME == "foo # not a comment"
+ assert built.APP_DESCRIPTION == Settings.model_fields["APP_DESCRIPTION"].default
+
+
+def test_the_environment_wins_over_the_file(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+ stored = tmp_path / ".env"
+ stored.write_text("APP_NAME=From The File\n")
+ monkeypatch.setenv("APP_NAME", "From The Environment")
+
+ assert Settings(_env_file=stored).APP_NAME == "From The Environment"
+
+
+def test_a_partial_class_ignores_the_names_other_classes_read(tmp_path: Path):
+ stored = tmp_path / ".env"
+ stored.write_text("POSTGRES_USER=elsewhere\n")
+
+ SecuritySettings(_env_file=stored)
+
+
+def test_a_misspelt_name_handed_to_the_constructor_is_refused():
+ misspelt: dict[str, Any] = {"SECRET_KEYY": "x"}
+
+ with pytest.raises(ValidationError):
+ Settings(**misspelt)
+
+
+def test_a_bad_environment_is_reported_without_the_other_settings(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("ENVIRONMENT", "prod")
+ monkeypatch.setenv("SECRET_KEY", "a-secret-nobody-should-see-0123456789abcdef")
+
+ with pytest.raises(ValidationError) as refused:
+ CoreSettings()
+
+ assert [error["loc"] for error in refused.value.errors()] == [("ENVIRONMENT",)]
+ assert "a-secret-nobody-should-see" not in str(refused.value)
+ assert "a-secret-nobody-should-see" not in str(refused.value.errors())
+
+
+@pytest.mark.parametrize(
+ ("environment", "creates"),
+ [(EnvironmentOption.LOCAL, True), (EnvironmentOption.DEVELOPMENT, True), (EnvironmentOption.PRODUCTION, False)],
+)
+def test_tables_are_created_on_startup_by_default_where_the_environment_builds_them(
+ environment: EnvironmentOption, creates: bool, monkeypatch: pytest.MonkeyPatch
+):
+ monkeypatch.delenv("CREATE_TABLES_ON_STARTUP", raising=False)
+ monkeypatch.setenv("ENVIRONMENT", environment.value)
+
+ assert Settings().CREATE_TABLES_ON_STARTUP is creates
+
+
+def test_tables_follow_the_environment_the_settings_are_built_with(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.delenv("CREATE_TABLES_ON_STARTUP", raising=False)
+ monkeypatch.setenv("ENVIRONMENT", "local")
+
+ assert Settings(ENVIRONMENT=EnvironmentOption.PRODUCTION).CREATE_TABLES_ON_STARTUP is False
+
+
+def test_settings_constructed_without_validation_still_follow_the_process_environment(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("ENVIRONMENT", "production")
+
+ assert Settings.model_construct().CREATE_TABLES_ON_STARTUP is False
+
+
+@pytest.mark.parametrize(("written", "read"), [("true", True), ("TRUE", True), ("1", True), ("false", False), ("0", False)])
+def test_a_flag_reads_the_spellings_it_always_did(written: str, read: bool, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("SECURITY_HEADERS_ENABLED", written)
+
+ assert SecuritySettings().SECURITY_HEADERS_ENABLED is read
+
+
+@pytest.mark.parametrize("written", ["yes", "on", "off", "t", ""])
+def test_a_flag_refuses_a_spelling_it_never_read(written: str, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("SECURITY_HEADERS_ENABLED", written)
+
+ with pytest.raises(ValidationError):
+ SecuritySettings()
+
+
+@pytest.mark.parametrize(("written", "read"), [("30", 30), (" 30", 30), ("1_000", 1000), ("+5", 5)])
+def test_a_number_reads_what_int_reads(written: str, read: int, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("POSTGRES_POOL_SIZE", written)
+
+ assert CoreSettings().POSTGRES_POOL_SIZE == read
+
+
+@pytest.mark.parametrize("written", ["1.0", "30.5", "thirty"])
+def test_a_number_refuses_what_int_refuses(written: str, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("POSTGRES_POOL_SIZE", written)
+
+ with pytest.raises(ValidationError):
+ CoreSettings()
+
+
+def test_a_flag_in_the_file_is_held_to_the_same_spellings(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+ monkeypatch.delenv("SECURITY_HEADERS_ENABLED", raising=False)
+ stored = tmp_path / ".env"
+ stored.write_text("SECURITY_HEADERS_ENABLED=yes\n")
+
+ with pytest.raises(ValidationError):
+ SecuritySettings(_env_file=stored)
+
+
+def test_a_class_written_the_old_way_still_composes_and_reads_its_variable(monkeypatch: pytest.MonkeyPatch):
+ """`config` stays exported, so a project's own class written with it keeps working."""
+
+ class OldStyle(BaseSettings):
+ OLD_STYLE_VALUE: str = facade.config("OLD_STYLE_VALUE", default="declared")
+
+ class Composed(OldStyle, CoreSettings):
+ pass
+
+ monkeypatch.setenv("OLD_STYLE_VALUE", "from the environment")
+
+ assert Composed().OLD_STYLE_VALUE == "from the environment"
+
+
+class _Probe(base.EnvSettings):
+ PROBE_LIMIT: int | None = None
+ PROBE_FLAG: bool | None = None
+ PROBE_IDS: list[int] = []
+
+
+@pytest.mark.parametrize("written", ["1.0", ""])
+def test_an_optional_number_refuses_what_int_refuses(written: str, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("PROBE_LIMIT", written)
+
+ with pytest.raises(ValidationError):
+ _Probe()
+
+
+def test_an_optional_flag_is_held_to_the_same_spellings(monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setenv("PROBE_FLAG", "yes")
+
+ with pytest.raises(ValidationError):
+ _Probe()
+
+
+def test_a_list_of_numbers_is_left_to_pydantic():
+ with pytest.raises(ValidationError) as refused:
+ _Probe(PROBE_IDS="[1, 2]")
+
+ assert [error["type"] for error in refused.value.errors()] == ["list_type"]
+
+
+def test_a_string_handed_to_the_constructor_is_held_to_the_same_rule():
+ with pytest.raises(ValidationError):
+ SecuritySettings(SECURITY_HEADERS_ENABLED="yes")
diff --git a/backend/tests/unit/infrastructure/config/test_settings_tables.py b/backend/tests/unit/infrastructure/config/test_settings_tables.py
new file mode 100644
index 00000000..ed29f05d
--- /dev/null
+++ b/backend/tests/unit/infrastructure/config/test_settings_tables.py
@@ -0,0 +1,38 @@
+"""Every setting has the value it had before settings read the environment at build time.
+
+The tables were written from the blueprint repo, where every feature is selected, so this file
+stays in the blueprint.
+"""
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from src.infrastructure.config.settings import Settings
+
+HERE = Path(__file__).resolve().parent
+ENV_EXAMPLE = HERE.parents[3] / ".env.example"
+DEFAULTS = json.loads((HERE / "defaults.json").read_text())
+"""Every field's value with nothing set."""
+EXAMPLE_VALUES = json.loads((HERE / "example_values.json").read_text())
+"""Every field's value with `backend/.env.example` as the environment file and nothing else set."""
+
+
+def test_the_tables_are_every_field():
+ assert sorted(DEFAULTS) == sorted(Settings.model_fields)
+ assert sorted(EXAMPLE_VALUES) == sorted(Settings.model_fields)
+
+
+@pytest.mark.parametrize("name", sorted(DEFAULTS))
+def test_every_default_is_the_one_it_was(name: str):
+ with patch.dict(os.environ, {}, clear=True):
+ assert repr(getattr(Settings(), name)) == DEFAULTS[name]
+
+
+@pytest.mark.parametrize("name", sorted(EXAMPLE_VALUES))
+def test_every_value_the_example_gives_is_the_one_it_gave(name: str):
+ with patch.dict(os.environ, {}, clear=True):
+ assert repr(getattr(Settings(_env_file=ENV_EXAMPLE), name)) == EXAMPLE_VALUES[name]
diff --git a/backend/tests/unit/infrastructure/email/test_senders.py b/backend/tests/unit/infrastructure/email/test_senders.py
index 4795369f..76706abe 100644
--- a/backend/tests/unit/infrastructure/email/test_senders.py
+++ b/backend/tests/unit/infrastructure/email/test_senders.py
@@ -2,8 +2,13 @@
import asyncio
import logging
+import smtplib
+import socket
import ssl
+import threading
+import time
import warnings
+from collections.abc import Callable
from typing import Any
import httpx
@@ -21,6 +26,12 @@
LINK = "https://app.example.com/reset-password?token=the-signed-token"
BODY = f"Someone asked to reset your password. Use this link: {LINK}"
+WAIT = 120
+"""Seconds Mailpit gets to come up and to answer each call, on a machine busy with other suites."""
+
+ATTEMPT = 5
+"""Seconds one attempt to reach Mailpit gets before the wait tries again."""
+
async def _send_the_reset_email(sender: EmailSender) -> None:
"""One message, as crudauth hands it over."""
@@ -33,6 +44,26 @@ async def _send_the_reset_email(sender: EmailSender) -> None:
)
+def _greets(host: str, port: int, timeout: float = ATTEMPT) -> None:
+ """Return once an SMTP server at `host:port` has greeted and answered a NOOP."""
+ with smtplib.SMTP(host, port, timeout=timeout) as server:
+ server.noop()
+
+
+def _until(check: Callable[[], object], within: float) -> None:
+ """Call `check` until it returns, retrying a refused or failed connection, and raise its
+ last error once `within` seconds have passed."""
+ deadline = time.monotonic() + within
+ while True:
+ try:
+ check()
+ return
+ except (OSError, smtplib.SMTPException, httpx.HTTPError):
+ if time.monotonic() >= deadline:
+ raise
+ time.sleep(0.2)
+
+
@pytest.fixture(scope="module")
def mailpit():
"""A real SMTP server of this module's own, with an API to read what arrived."""
@@ -44,6 +75,9 @@ def mailpit():
container = MailpitContainer().start()
try:
+ api = container.get_base_api_url()
+ _until(lambda: _greets(container.get_container_host_ip(), container.get_exposed_smtp_port()), WAIT)
+ _until(lambda: httpx.get(f"{api}/api/v1/info", timeout=ATTEMPT).raise_for_status(), WAIT)
yield container
finally:
container.stop()
@@ -58,16 +92,16 @@ def _smtp_sender(mailpit: MailpitContainer, starttls: bool) -> SmtpSender:
user="mailer",
password="secret",
starttls=starttls,
- timeout=10,
+ timeout=WAIT,
)
def _delivered(mailpit: MailpitContainer) -> dict[str, Any]:
"""The one message Mailpit is holding, with its body."""
api = mailpit.get_base_api_url()
- listed = httpx.get(f"{api}/api/v1/messages", timeout=10).json()["messages"]
+ listed = httpx.get(f"{api}/api/v1/messages", timeout=WAIT).json()["messages"]
assert len(listed) == 1, listed
- message: dict[str, Any] = httpx.get(f"{api}/api/v1/message/{listed[0]['ID']}", timeout=10).json()
+ message: dict[str, Any] = httpx.get(f"{api}/api/v1/message/{listed[0]['ID']}", timeout=WAIT).json()
return message
@@ -100,6 +134,55 @@ async def test_starttls_will_not_talk_to_a_server_it_cannot_verify(mailpit: Mail
await _send_the_reset_email(_smtp_sender(mailpit, starttls=True))
+def _serve_smtp_after(delay: float) -> tuple[int, list[bytes], threading.Thread]:
+ """A port where a minimal SMTP server starts listening only after `delay` seconds, the
+ commands it receives, and its thread, which ends after one session or 2 idle seconds."""
+ with socket.socket() as probe:
+ probe.bind(("127.0.0.1", 0))
+ port: int = probe.getsockname()[1]
+ received: list[bytes] = []
+
+ def serve() -> None:
+ time.sleep(delay)
+ with socket.create_server(("127.0.0.1", port)) as server:
+ server.settimeout(2)
+ try:
+ connection, _ = server.accept()
+ except TimeoutError:
+ return
+ with connection, connection.makefile("rwb") as stream:
+ stream.write(b"220 ready\r\n")
+ stream.flush()
+ for line in stream:
+ received.append(line.strip().upper())
+ stream.write(b"221 bye\r\n" if line.upper().startswith(b"QUIT") else b"250 ok\r\n")
+ stream.flush()
+
+ thread = threading.Thread(target=serve, daemon=True)
+ thread.start()
+
+ return port, received, thread
+
+
+def test_the_wait_returns_once_a_server_that_starts_late_answers_a_noop():
+ port, received, thread = _serve_smtp_after(0.5)
+
+ _until(lambda: _greets("127.0.0.1", port), within=10)
+ thread.join(10)
+
+ assert b"NOOP" in received
+
+
+def test_the_wait_gives_up_with_the_last_error():
+ port, _, thread = _serve_smtp_after(2)
+
+ with pytest.raises(ConnectionRefusedError):
+ _until(lambda: _greets("127.0.0.1", port), within=0.3)
+ thread.join(10)
+
+ assert not thread.is_alive()
+
+
class _GatedSender(EmailSender):
"""Delivers only once it is let go, and records what it delivered."""
diff --git a/backend/tests/unit/infrastructure/security/test_production_validator.py b/backend/tests/unit/infrastructure/security/test_production_validator.py
index c429be50..435d2f65 100644
--- a/backend/tests/unit/infrastructure/security/test_production_validator.py
+++ b/backend/tests/unit/infrastructure/security/test_production_validator.py
@@ -610,7 +610,8 @@ def test_the_email_settings_are_left_alone_without_the_accounts_feature(self):
def test_the_core_checks_still_run(self):
"""Dropping features must not drop the checks that hold for every project."""
- validator = ProductionSecurityValidator(cast(Settings, CoreSettings(ENVIRONMENT=EnvironmentOption.PRODUCTION)))
+ settings = CoreSettings(ENVIRONMENT=EnvironmentOption.PRODUCTION, SECRET_KEY="change-me")
+ validator = ProductionSecurityValidator(cast(Settings, settings))
errors = validator._validate_critical_security()
@@ -638,7 +639,7 @@ def test_every_generated_key_is_accepted(self, shape):
The rules do refuse a few generated keys: one hex key in 12.6 million runs
through eight consecutive digits, and a ``token_urlsafe`` key walks
neighbouring keys over 0.6 of its length at around one in ten million (one
- such key in a 10,000,000 sample, none in a second). ``bp env gen-secret``
+ such key in a 10,000,000 sample, none in a second). ``fastro env secret``
draws again rather than printing those, and the seed here is fixed so that
this sweep states what the rules do instead of drawing a lottery.
"""
diff --git a/backend/tests/unit/modules/user/test_service.py b/backend/tests/unit/modules/user/test_service.py
index 086a81e9..267a3c88 100644
--- a/backend/tests/unit/modules/user/test_service.py
+++ b/backend/tests/unit/modules/user/test_service.py
@@ -146,6 +146,46 @@ async def test_signup_cannot_write_the_verification_or_oauth_columns(user_servic
assert created["oauth_provider"] is None
+async def test_what_each_feature_sets_on_a_new_account_is_written_the_later_over_the_earlier(
+ user_service: UserService, db_session: AsyncSession, monkeypatch
+):
+ """The account's own fields win over any of them, and none sets a column crudauth owns,
+ as on a provider's first sign-in."""
+ given: list[AsyncSession] = []
+ written: list[dict[str, Any]] = []
+
+ async def first(db: AsyncSession) -> dict[str, Any]:
+ given.append(db)
+ return {
+ "first_column": 1,
+ "shared_column": "first",
+ "name": "Someone Else",
+ "is_superuser": True,
+ "email_verified": True,
+ "oauth_provider": "google",
+ }
+
+ async def second(db: AsyncSession) -> dict[str, Any]:
+ return {"second_column": 2, "shared_column": "second"}
+
+ async def recording(*, db: AsyncSession, object: Any, schema_to_select: Any) -> dict[str, Any]:
+ written.append(object.model_dump())
+ return {"id": 1}
+
+ monkeypatch.setattr(service_module, "NEW_ACCOUNT_FIELDS", (first, second))
+ monkeypatch.setattr(crud_users, "create", recording)
+
+ await user_service.create(
+ UserCreate(name="Owner", username="contributed", email="contributed@example.com", password="Str1ngst!"), db_session
+ )
+
+ (row,) = written
+ assert given == [db_session]
+ assert (row["first_column"], row["second_column"], row["shared_column"]) == (1, 2, "second")
+ assert (row["name"], row["username"], row["email"]) == ("Owner", "contributed", "contributed@example.com")
+ assert (row.get("is_superuser"), row["email_verified"], row["oauth_provider"]) == (None, False, None)
+
+
# =============================================================================
# Which credential was taken decides how a signup answers
# =============================================================================
diff --git a/backend/tests/unit/modules/user/test_signup_route.py b/backend/tests/unit/modules/user/test_signup_route.py
new file mode 100644
index 00000000..61c679b2
--- /dev/null
+++ b/backend/tests/unit/modules/user/test_signup_route.py
@@ -0,0 +1,12 @@
+"""The signup route says where other features set what they add to a new account."""
+
+from src.interfaces.main import app
+from src.wiring import signup
+
+
+def test_the_signup_route_names_the_wiring_a_new_account_takes_other_features_columns_from():
+ description = app.openapi()["paths"]["/api/v1/users/"]["post"]["description"]
+
+ assert signup.__file__.endswith("src/wiring/signup.py")
+ assert "`src/wiring/signup.py`" in description
+ assert "tier" not in description.lower()
diff --git a/backend/tests/unit/scripts/test_baseline.py b/backend/tests/unit/scripts/test_baseline.py
new file mode 100644
index 00000000..0a5d362e
--- /dev/null
+++ b/backend/tests/unit/scripts/test_baseline.py
@@ -0,0 +1,273 @@
+"""What the baseline writes, what it refuses, and what it leaves behind.
+
+The container and alembic are mocked, so the suite needs no Docker: what is checked here is
+the script's own reasoning. The revision it writes has to be the baseline rather than any
+revision, and ``--check`` has to leave ``migrations/versions/`` exactly as it found it, since
+that is the mode `fastro verify` runs in a project it has just generated.
+"""
+
+import os
+import subprocess
+import sys
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from scripts import baseline
+from src.infrastructure.database.session import Base
+
+HOST = "127.0.0.1"
+PORT = 54321
+
+BACKEND = Path(baseline.__file__).resolve().parents[1]
+
+
+class _Container:
+ """The pieces of a ``PostgresContainer`` the script reads."""
+
+ username = "baseline-user"
+ password = "baseline-password"
+ dbname = "baseline-db"
+
+ def __init__(self, image: str):
+ self.image = image
+
+ def __enter__(self) -> "_Container":
+ return self
+
+ def __exit__(self, *exception: Any) -> None:
+ return None
+
+ def get_container_host_ip(self) -> str:
+ return HOST
+
+ def get_exposed_port(self, port: int) -> int:
+ return PORT
+
+
+class _Alembic:
+ """Alembic as the script calls it: a recorder that writes the revision autogenerate would."""
+
+ def __init__(self, versions: Path, *, revision: str = "0a1b2c3d4e5f", slug: str | None = None, failing: str | None = None):
+ self.versions = versions
+ self.revision = revision
+ self.slug = slug
+ self.failing = failing
+ self.calls: list[tuple[str, ...]] = []
+ self.environments: list[dict[str, str]] = []
+
+ def __call__(self, *arguments: str) -> subprocess.CompletedProcess[str]:
+ self.calls.append(arguments)
+ self.environments.append(dict(os.environ))
+ if self.failing == arguments[0]:
+ return subprocess.CompletedProcess(list(arguments), 1, "", f"{arguments[0]} went wrong")
+
+ if arguments[0] == "revision":
+ slug = self.slug or arguments[arguments.index("-m") + 1]
+ (self.versions / f"{self.revision}_{slug}.py").write_text(f'revision = "{self.revision}"\n')
+
+ return subprocess.CompletedProcess(list(arguments), 0, "", "")
+
+
+@pytest.fixture
+def versions(tmp_path: Path, monkeypatch) -> Path:
+ directory = tmp_path / "versions"
+ directory.mkdir()
+ monkeypatch.setattr(baseline, "VERSIONS", directory)
+
+ return directory
+
+
+@pytest.fixture(autouse=True)
+def _restored_environment() -> Iterator[None]:
+ """The script writes the container's details into the environment, as alembic reads them."""
+ before = dict(os.environ)
+
+ yield
+
+ os.environ.clear()
+ os.environ.update(before)
+
+
+@pytest.fixture
+def container(monkeypatch) -> None:
+ monkeypatch.setattr(baseline, "PostgresContainer", _Container)
+
+
+@pytest.fixture
+def alembic(versions, monkeypatch) -> _Alembic:
+ """Alembic itself is never run: what it would do to the tree is what the script reasons about."""
+ recorder = _Alembic(versions)
+ monkeypatch.setattr(baseline, "alembic", recorder)
+
+ return recorder
+
+
+def _schema_of(declared: dict[str, list[str]]):
+ async def read(url: str) -> dict[str, list[str]]:
+ return declared
+
+ return read
+
+
+@pytest.fixture
+def matching(monkeypatch) -> None:
+ """A database the baseline left holding exactly what the models declare."""
+ monkeypatch.setattr(baseline, "created_schema", _schema_of(baseline.declared_schema()))
+
+
+def _written(versions: Path) -> dict[str, str]:
+ return {path.name: path.read_text() for path in versions.glob("*.py")}
+
+
+def test_it_writes_one_revision_named_after_the_baseline(versions, container, matching, alembic, capsys):
+ code = baseline.main([])
+
+ assert code == 0, capsys.readouterr()
+ assert list(_written(versions)) == ["0a1b2c3d4e5f_baseline.py"]
+ assert "tables" in capsys.readouterr().out
+
+
+def test_it_autogenerates_the_baseline_and_applies_it(versions, container, matching, alembic):
+ baseline.main([])
+
+ assert alembic.calls == [("revision", "--autogenerate", "-m", "baseline"), ("upgrade", "head")]
+
+
+def test_check_leaves_the_versions_directory_as_it_found_it(versions, container, matching, alembic):
+ before = _written(versions)
+
+ code = baseline.main(["--check"])
+
+ assert code == 0
+ assert _written(versions) == before
+ assert ("revision", "--autogenerate", "-m", "baseline") in alembic.calls
+
+
+def test_the_commands_run_against_the_container(versions, container, matching, alembic):
+ baseline.main([])
+
+ environment = alembic.environments[0]
+ assert environment["POSTGRES_SERVER"] == HOST
+ assert environment["POSTGRES_PORT"] == str(PORT)
+ assert environment["POSTGRES_USER"] == _Container.username
+ assert environment["POSTGRES_PASSWORD"] == _Container.password
+ assert environment["POSTGRES_DB"] == _Container.dbname
+ assert environment["DATABASE_URL"] == "", "a configured URL wins over these, and names the real database"
+
+
+def test_a_database_the_models_do_not_declare_is_refused(versions, container, alembic, monkeypatch, capsys):
+ """The table named here is one no project declares, so it is a mismatch whatever is selected."""
+ monkeypatch.setattr(baseline, "created_schema", _schema_of({"alembic_version": [], "nothing_declares_this": []}))
+
+ code = baseline.main(["--check"])
+
+ printed = capsys.readouterr()
+ assert code == 1
+ assert "while the models declare" in printed.err
+ assert _written(versions) == {}
+
+
+def test_a_failed_autogenerate_is_reported_with_what_alembic_printed(versions, container, matching, monkeypatch, capsys):
+ monkeypatch.setattr(baseline, "alembic", _Alembic(versions, failing="revision"))
+
+ code = baseline.main([])
+
+ printed = capsys.readouterr()
+ assert code == 1
+ assert "revision went wrong" in printed.err
+ assert _written(versions) == {}
+
+
+def test_a_failed_upgrade_is_withdrawn_under_check(versions, container, matching, monkeypatch, capsys):
+ monkeypatch.setattr(baseline, "alembic", _Alembic(versions, failing="upgrade"))
+
+ code = baseline.main(["--check"])
+
+ printed = capsys.readouterr()
+ assert code == 1
+ assert "upgrade went wrong" in printed.err
+ assert _written(versions) == {}
+
+
+def test_a_revision_that_is_not_the_baseline_is_refused(versions, container, matching, monkeypatch, capsys):
+ """Alembic names the file after its own slug, and a project's first revision is the baseline."""
+ monkeypatch.setattr(baseline, "alembic", _Alembic(versions, slug="add_a_column"))
+
+ code = baseline.main(["--check"])
+
+ assert code == 1
+ assert "is not the baseline" in capsys.readouterr().err
+
+
+def test_a_project_that_already_has_a_history_is_refused(versions, container, matching, alembic, capsys):
+ (versions / "f5e4d3c2b1a0_add_a_column.py").write_text('revision = "f5e4d3c2b1a0"\n')
+ before = _written(versions)
+
+ code = baseline.main([])
+
+ printed = capsys.readouterr()
+ assert code == 1
+ assert "f5e4d3c2b1a0_add_a_column.py" in printed.err
+ assert _written(versions) == before
+
+
+def test_the_declared_schema_is_the_one_the_models_build(versions):
+ """The tables are the ones this project's features declare, read rather than listed.
+
+ A project without accounts has no `user`, and one with no features has only alembic's own,
+ which the script adds because a baseline creates the table alembic records itself in.
+ """
+ declared = baseline.declared_schema()
+
+ assert declared["alembic_version"] == []
+ assert set(declared) == set(Base.metadata.tables) | {"alembic_version"}
+ assert all(indexes == sorted(indexes) for indexes in declared.values())
+
+
+_COLD_SCHEMA = """
+from scripts.baseline import declared_schema
+
+print(sorted(name for name in declared_schema() if name != "alembic_version"))
+"""
+
+
+def test_the_script_imports_the_models_itself():
+ """Only a cold interpreter can tell: in the suite, `tests/conftest.py` has imported the app,
+ which imports every model, so the metadata is already full whatever the script does.
+
+ A project that declares no models of its own cannot tell an import that did nothing from one
+ that worked, so it skips rather than passing for the wrong reason.
+ """
+ declared = sorted(Base.metadata.tables)
+ if not declared:
+ pytest.skip("this project declares no models, so a missing import looks like a working one")
+
+ result = subprocess.run(
+ [sys.executable, "-c", _COLD_SCHEMA],
+ cwd=BACKEND,
+ env={**os.environ, "PYTHONPATH": str(BACKEND)},
+ capture_output=True,
+ text=True,
+ timeout=120,
+ )
+
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert result.stdout.strip().splitlines()[-1] == str(declared), "the settings log to stdout before it prints"
+
+
+def test_running_it_as_a_module_takes_the_check_flag():
+ """``--check`` is what verify runs, so an argument parser that refuses it is a broken verify."""
+ result = subprocess.run(
+ [sys.executable, "-m", "scripts.baseline", "--help"],
+ cwd=BACKEND,
+ capture_output=True,
+ text=True,
+ env={**os.environ, "PYTHONPATH": str(BACKEND)},
+ timeout=120,
+ )
+
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert "--check" in result.stdout
diff --git a/backend/tests/unit/scripts/test_gen_secret.py b/backend/tests/unit/scripts/test_gen_secret.py
new file mode 100644
index 00000000..baa4dd44
--- /dev/null
+++ b/backend/tests/unit/scripts/test_gen_secret.py
@@ -0,0 +1,101 @@
+"""The key the script prints, and why it sometimes draws more than once.
+
+``SECRET_KEY`` is refused at startup in production when the project's own rules read it as
+something a person typed. A generator that printed such a key would send you into that
+refusal, so it draws again while the rules refuse what it drew.
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from scripts.gen_secret import generate
+from src.infrastructure.config.settings import EnvironmentOption, Settings
+from src.infrastructure.security.production_validator import ProductionSecurityValidator
+from src.infrastructure.security.secret_key import is_weak_secret_key
+
+BACKEND = Path(__file__).resolve().parents[3]
+
+REFUSED = "e48102bfe6ac2eac3aa8623456789a6030e4fa7dee3cd173bfb7941f2f819678"
+"""A hex key the rules refuse: it runs through eight consecutive digits."""
+
+
+def _run(*arguments: str) -> subprocess.CompletedProcess[str]:
+ """Run the script from ``backend/``, with nothing configured but the interpreter."""
+ environment = {
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ "HOME": os.environ.get("HOME", "/tmp"),
+ "PYTHONPATH": str(BACKEND),
+ }
+
+ return subprocess.run(
+ [sys.executable, *arguments],
+ cwd=BACKEND,
+ env=environment,
+ capture_output=True,
+ text=True,
+ timeout=60,
+ )
+
+
+def test_the_key_it_prints_is_one_the_validator_accepts():
+ """The script is what an operator runs to satisfy the validator, so ask the validator."""
+ key = generate()
+
+ validator = ProductionSecurityValidator(Settings(SECRET_KEY=key, ENVIRONMENT=EnvironmentOption.PRODUCTION))
+
+ assert len(key) == 64
+ assert not validator._is_insecure_secret_key()
+
+
+def test_a_key_the_rules_refuse_is_drawn_again(monkeypatch):
+ """One hex key in twelve million runs through eight digits, which production refuses."""
+ accepted = "7b1c9d4e2a6f8305b4c7e1d9f2a6b8c30d5e7f91a2b3c4d5e6f708192a3b4c5d"
+ draws = iter([REFUSED, accepted])
+ monkeypatch.setattr("scripts.gen_secret.secrets.token_hex", lambda size: next(draws))
+
+ assert is_weak_secret_key(REFUSED)
+ assert generate() == accepted
+
+
+def test_it_gives_up_after_the_draws_it_allows(monkeypatch):
+ """Drawing for ever would hang; the last draw is printed whatever the rules say."""
+ monkeypatch.setattr("scripts.gen_secret.secrets.token_hex", lambda size: REFUSED)
+
+ assert generate() == REFUSED
+
+
+def test_the_byte_count_decides_the_length():
+ assert len(generate(16)) == 32
+
+
+@pytest.mark.parametrize("invocation", [("scripts/gen_secret.py",), ("-m", "scripts.gen_secret")])
+def test_it_runs_the_way_the_documentation_runs_it(invocation: tuple[str, ...]):
+ """As a file from ``backend/``, and as a module, which is what the blueprint declares."""
+ result = _run(*invocation)
+
+ assert result.returncode == 0, result.stderr
+ assert len(result.stdout.strip()) == 64
+
+
+@pytest.mark.parametrize("count", ["8", "256", "many"])
+def test_a_byte_count_the_script_will_not_take_is_refused(count: str):
+ """A short key is one the rules would refuse anyway, and a usage error exits 2."""
+ result = _run("scripts/gen_secret.py", "--bytes", count)
+
+ assert result.returncode == 2
+ assert result.stdout.strip() == ""
+
+
+def test_it_prints_the_key_and_nothing_else():
+ """The documented use pipes it (``| gh secret set SECRET_KEY``), so a log line would go too.
+
+ Importing ``src.infrastructure.security`` configures logging, which writes to stdout.
+ """
+ result = _run("-m", "scripts.gen_secret")
+
+ assert result.stdout.count("\n") == 1
+ assert len(result.stdout.strip()) == 64
diff --git a/backend/tests/unit/scripts/test_setup_initial_data.py b/backend/tests/unit/scripts/test_setup_initial_data.py
index 5499a6da..4e1c5a62 100644
--- a/backend/tests/unit/scripts/test_setup_initial_data.py
+++ b/backend/tests/unit/scripts/test_setup_initial_data.py
@@ -42,8 +42,8 @@ async def an_empty_database(test_db_url: str):
def _seed(url: str, **extra: str):
"""Run the script as an operator does, with the superuser settings a seeder needs.
- The drill's copy of the project carries no ``.env``, so anything the script reads has
- to be in the environment it is handed.
+ ``.env`` is git-ignored, so a checkout carries none, and anything the script reads has to
+ be in the environment it is handed.
"""
return run_script("setup_initial_data", script_environment(url, **ADMIN, **extra))
diff --git a/backend/tests/unit/scripts/test_validate_env.py b/backend/tests/unit/scripts/test_validate_env.py
new file mode 100644
index 00000000..af6c8fae
--- /dev/null
+++ b/backend/tests/unit/scripts/test_validate_env.py
@@ -0,0 +1,216 @@
+"""What the environment audit reports, and what it exits with.
+
+The audit answers one question: what would production refuse about this configuration?
+It therefore reads the settings as production whatever ``ENVIRONMENT`` says, so that a
+development or staging configuration is held to the same gate, and so that a finding that
+names an environment names the one it was checked for.
+"""
+
+import os
+import secrets
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+from pydantic import AliasChoices
+
+from scripts.validate_env import audit, main
+from src.infrastructure.config.settings import EnvironmentOption, Settings
+
+BACKEND = Path(__file__).resolve().parents[3]
+
+PRODUCTION_SHAPED: dict[str, Any] = {
+ "ENVIRONMENT": EnvironmentOption.PRODUCTION,
+ "CREATE_TABLES_ON_STARTUP": False,
+ "EMAIL_BACKEND": "smtp",
+ "EMAIL_SMTP_HOST": "smtp.example.com",
+ "FRONTEND_URL": "https://app.example.com",
+}
+"""The settings whose defaults describe development rather than the production these stand for."""
+
+
+def _settings(**overrides: Any) -> Settings:
+ return Settings(**(PRODUCTION_SHAPED | overrides))
+
+
+def _audited(monkeypatch, settings: Settings) -> None:
+ """Answer the script with these settings instead of the ones the environment holds."""
+ monkeypatch.setattr("scripts.validate_env.get_settings", lambda: settings)
+
+
+def _accepted_names() -> set[str]:
+ """Every name this project's settings take, a field's alias choices included.
+
+ `SESSION_REDIS_PASSWORD` accepts `CACHE_REDIS_PASSWORD` as well, so a project with accounts
+ and no cache still takes that name and reads the session password from it.
+ """
+ accepted = set()
+ for name, field in Settings.model_fields.items():
+ accepted.add(name)
+ alias = field.validation_alias
+ if isinstance(alias, str):
+ accepted.add(alias)
+ elif isinstance(alias, AliasChoices):
+ accepted.update(choice for choice in alias.choices if isinstance(choice, str))
+
+ return accepted
+
+
+def _strong() -> dict[str, Any]:
+ """A configuration production would accept, less whatever this project has no feature for.
+
+ `Settings` forbids an input no field of its own takes, so a project without the cache, the
+ limiter or the admin panel refuses their settings rather than ignoring them.
+ """
+ strong = {
+ "SECRET_KEY": secrets.token_hex(32),
+ "POSTGRES_PASSWORD": "a-strong-database-password",
+ "CORS_ORIGINS": "https://app.example.com",
+ "ADMIN_ENABLED": False,
+ "DEBUG": False,
+ "OPENAPI_URL": "",
+ "CACHE_REDIS_PASSWORD": "redis-password",
+ "RATE_LIMITER_REDIS_PASSWORD": "redis-password",
+ "SESSION_SECURE_COOKIES": True,
+ "SESSION_BACKEND": "redis",
+ "RATE_LIMITER_BACKEND": "redis",
+ }
+
+ return {name: value for name, value in strong.items() if name in _accepted_names()}
+
+
+def test_a_clean_configuration_says_so(monkeypatch, capsys):
+ _audited(monkeypatch, _settings(**_strong()))
+
+ code = main()
+
+ assert code == 0
+ assert "No issues found" in capsys.readouterr().out
+
+
+def test_a_weak_configuration_is_refused_and_named(monkeypatch, capsys):
+ """Settings the validator really refuses come out as critical findings that name them."""
+ _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this", POSTGRES_PASSWORD="postgres"))
+
+ code = main()
+
+ printed = capsys.readouterr().out
+ assert code == 1
+ assert "SECRET_KEY" in printed
+ assert "Database is using default credentials" in printed
+
+
+def test_warnings_are_reported_even_when_something_is_critical(monkeypatch, capsys):
+ """The warnings used to be computed only when nothing critical was found.
+
+ Both findings are core: the placeholder key is critical and debug mode is a warning, so a
+ project with no features selected still produces one of each.
+ """
+ _audited(monkeypatch, _settings(SECRET_KEY="insecure-secret-key-change-this", DEBUG=True))
+
+ code = main()
+
+ printed = capsys.readouterr().out
+ assert code == 1
+ assert "Critical (" in printed
+ assert "Warnings (" in printed
+
+
+def test_warnings_alone_do_not_fail_the_audit(monkeypatch, capsys):
+ """A warning is something to look at, not something that would stop a boot.
+
+ Debug mode rather than an unprotected cache: the cache is a feature, and this test runs in
+ projects that didn't select it.
+ """
+ _audited(monkeypatch, _settings(**(_strong() | {"DEBUG": True})))
+
+ code = main()
+
+ printed = capsys.readouterr().out
+ assert code == 0
+ assert "Warnings (" in printed
+ assert "Critical (" not in printed
+
+
+def test_every_finding_names_the_environment_it_is_checked_for(monkeypatch, capsys):
+ """Audited as production, a finding that names a development environment is a lie.
+
+ The table-creation finding is the one asked for, because it is core: the email backend names
+ the environment too, but only a project with accounts has anything to email.
+ """
+ _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT, CREATE_TABLES_ON_STARTUP=True))
+
+ main()
+
+ printed = capsys.readouterr().out
+ assert "in production" in printed
+ assert "in development" not in printed
+
+
+def test_the_audited_settings_carry_the_environment_as_the_app_reads_it(monkeypatch):
+ """The app factory and the logger read ``ENVIRONMENT.value``, which a plain string has not."""
+ handed: list[Settings] = []
+ _audited(monkeypatch, _settings(ENVIRONMENT=EnvironmentOption.DEVELOPMENT))
+
+ class _Validator:
+ def __init__(self, settings: Settings):
+ handed.append(settings)
+
+ def audit(self) -> tuple[list[str], list[str]]:
+ return [], []
+
+ monkeypatch.setattr("scripts.validate_env.ProductionSecurityValidator", _Validator)
+ audit()
+
+ assert handed[0].ENVIRONMENT.value == "production"
+
+
+def _run(environment: dict[str, str]) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [sys.executable, "-m", "scripts.validate_env"],
+ cwd=BACKEND,
+ env={
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ "HOME": os.environ.get("HOME", "/tmp"),
+ "PYTEST_VERSION": os.environ.get("PYTEST_VERSION", "1"),
+ **environment,
+ },
+ capture_output=True,
+ text=True,
+ timeout=120,
+ )
+
+
+@pytest.mark.parametrize(("key", "code"), [("placeholder", 1), ("drawn", 0)])
+def test_it_runs_as_a_module_and_exits_on_what_it_found(key: str, code: int):
+ """``python -m scripts.validate_env`` is what the blueprint declares as a command.
+
+ The key is drawn here rather than in the parameter list, where it would land in the
+ test's id: ``pytest -n auto`` refuses a run whose workers collected different ids.
+ """
+ secret = secrets.token_hex(32) if key == "drawn" else "insecure-secret-key-change-this"
+ environment = {
+ "PYTHONPATH": str(BACKEND),
+ "ENVIRONMENT": "development",
+ "SECRET_KEY": secret,
+ "POSTGRES_PASSWORD": "a-strong-database-password",
+ "CORS_ORIGINS": "https://app.example.com",
+ "ADMIN_ENABLED": "false",
+ "DEBUG": "false",
+ "OPENAPI_URL": "",
+ "CACHE_REDIS_PASSWORD": "redis-password",
+ "RATE_LIMITER_REDIS_PASSWORD": "redis-password",
+ "SESSION_SECURE_COOKIES": "true",
+ "CREATE_TABLES_ON_STARTUP": "false",
+ "EMAIL_BACKEND": "smtp",
+ "EMAIL_SMTP_HOST": "smtp.example.com",
+ "FRONTEND_URL": "https://app.example.com",
+ "SESSION_BACKEND": "redis",
+ "RATE_LIMITER_BACKEND": "redis",
+ }
+
+ result = _run(environment)
+
+ assert result.returncode == code, result.stdout + result.stderr
diff --git a/backend/tests/unit/test_blueprint_catalog.py b/backend/tests/unit/test_blueprint_catalog.py
new file mode 100644
index 00000000..98aecbe7
--- /dev/null
+++ b/backend/tests/unit/test_blueprint_catalog.py
@@ -0,0 +1,2799 @@
+"""The catalog describes this repository.
+
+`blueprint.toml` is read by fastro, which the repository root installs and the backend doesn't,
+so nothing in this file imports it: the rules it checks are transcribed from the catalog spec,
+and the facts it checks against are the repository's own files.
+"""
+
+import ast
+import functools
+import importlib
+import ipaddress
+import itertools
+import keyword
+import re
+import subprocess
+import sys
+import time
+import tomllib
+from collections.abc import Iterable
+from importlib.metadata import packages_distributions, requires
+from pathlib import Path
+from typing import Any
+
+import pytest
+import yaml
+from packaging.requirements import Requirement
+
+from tests.conftest import is_docker_running
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+CATALOG = REPO_ROOT / "blueprint.toml"
+BACKEND_PYPROJECT = REPO_ROOT / "backend" / "pyproject.toml"
+
+FEATURE_NAME = re.compile(r"^[a-z][a-z0-9_]*$")
+"""Spec 1.2. Written out rather than imported, because the backend's tests don't import fastro."""
+
+BLUEPRINT_NAME = re.compile(r"^[a-z][a-z0-9-]*$")
+
+SET_NAME = re.compile(r"^[a-z][a-z0-9_-]*$")
+"""Spec 1.2. A preset or a verify set may carry a hyphen, which a feature name may not."""
+
+
+@functools.cache
+def _catalog() -> dict[str, Any]:
+ with CATALOG.open("rb") as handle:
+ return tomllib.load(handle)
+
+
+def test_the_catalog_parses():
+ assert _catalog()["blueprint"]["name"] == "fastapi-boilerplate"
+
+
+def test_it_names_itself_the_way_the_spec_allows():
+ blueprint = _catalog()["blueprint"]
+
+ assert BLUEPRINT_NAME.match(blueprint["name"])
+ assert blueprint["schema"] == 1
+ assert blueprint["python_root"] == "backend"
+ assert blueprint["import_root"] == "src"
+
+
+def test_the_version_is_the_one_the_backend_ships():
+ """FR002: a release tag is a blueprint release, so the two versions move together."""
+ with BACKEND_PYPROJECT.open("rb") as handle:
+ backend = tomllib.load(handle)
+
+ assert _catalog()["blueprint"]["version"] == backend["project"]["version"]
+
+
+def test_development_builds_of_the_tool_can_read_it():
+ """Spec 1.6: `0.1.0.dev0` sorts below `0.1`, so the lower bound has to name it."""
+ assert _catalog()["blueprint"]["requires_fastro"] == ">=0.1.0.dev0,<0.2"
+
+
+def _declared_specifiers(listing: str = "runtime") -> set[str]:
+ """Every specifier a project could install from this listing: the core's, each feature's, each
+ `when` block's, and, for the runtime one, each option's."""
+ key = "dependencies" if listing == "runtime" else "dev_dependencies"
+ specifiers = set(_catalog()["blueprint"]["dependencies"][listing])
+ for feature in _catalog()["features"].values():
+ specifiers.update(feature.get(key, ()))
+ for block in feature.get("when", ()):
+ specifiers.update(block.get(key, ()))
+ for option in feature.get("options", {}).values() if listing == "runtime" else ():
+ for chosen in option.get("dependencies", {}).values():
+ specifiers.update(chosen)
+
+ return specifiers
+
+
+def test_the_dependencies_a_project_could_install_are_the_ones_the_backend_declares():
+ """This repo selects every feature, so the union of the declarations is the backend's own list.
+
+ The specifiers are compared, not the distribution names, so a floor that moves in one file
+ and not the other is caught rather than averaged away.
+ """
+ with BACKEND_PYPROJECT.open("rb") as handle:
+ backend = tomllib.load(handle)
+
+ assert _declared_specifiers() == set(backend["project"]["dependencies"])
+ assert _declared_specifiers("dev") == set(backend["project"]["optional-dependencies"]["dev"])
+
+
+FASTAPI_THE_APP_NEEDS = {
+ "get_flat_dependant": ("src/infrastructure/cache/utils.py", "0.140.7"),
+ "openapi_prefix": ("src/infrastructure/app_factory.py", "0.145.0"),
+}
+"""Each FastAPI name the app relies on, the file that uses it, and the first release without it."""
+
+
+def test_every_fastapi_a_project_could_install_is_one_the_app_can_import():
+ """A project resolves its dependencies fresh, so the declared range, not the lock, decides which FastAPI it gets."""
+ with (REPO_ROOT / "uv.lock").open("rb") as handle:
+ locked = next(package["version"] for package in tomllib.load(handle)["package"] if package["name"] == "fastapi")
+ ranges = [Requirement(specifier).specifier for specifier in _declared_specifiers() if _distribution(specifier) == "fastapi"]
+
+ assert ranges
+ for name, (path, first_without) in FASTAPI_THE_APP_NEEDS.items():
+ assert name in (REPO_ROOT / "backend" / path).read_text(), (name, path)
+ for allowed in ranges:
+ assert first_without not in allowed, (allowed, name)
+ for allowed in ranges:
+ assert "999.0" not in allowed, allowed
+ assert locked in allowed, (allowed, locked)
+
+
+def _distribution(specifier: str) -> str:
+ """The distribution a PEP 508 specifier names, without its extras or its version."""
+ return re.split(r"[\[<>=!~;]", specifier)[0].strip().lower().replace("_", "-")
+
+
+@functools.cache
+def _provided() -> dict[str, frozenset[str]]:
+ """The modules each installed distribution provides, which is what an import names: `faker`
+ is imported as `faker`, and `user-agents` as `user_agents`."""
+ provided: dict[str, set[str]] = {}
+ for module, distributions in packages_distributions().items():
+ for distribution in distributions:
+ provided.setdefault(_distribution(distribution), set()).add(module)
+
+ return {name: frozenset(modules) for name, modules in provided.items()}
+
+
+@functools.cache
+def _module_imports(path: Path) -> frozenset[str]:
+ """Every module an absolute import in this file names, dotted as it is written."""
+ found: set[str] = set()
+ for node in ast.walk(ast.parse(path.read_text())):
+ if isinstance(node, ast.Import):
+ found.update(alias.name for alias in node.names)
+ elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+ found.add(node.module)
+
+ return frozenset(found)
+
+
+@functools.cache
+def _imported(*directories: str, skipping: tuple[str, ...] = ()) -> frozenset[str]:
+ """Every top-level module imported under these directories of the python root, less the files
+ named in `skipping`, which are given relative to that root."""
+ root = REPO_ROOT / _catalog()["blueprint"]["python_root"]
+ skipped = {root / name for name in skipping}
+
+ return frozenset(
+ module.split(".")[0]
+ for directory in directories
+ for path in sorted((root / directory).rglob("*.py"))
+ if path not in skipped
+ for module in _module_imports(path)
+ )
+
+
+@functools.cache
+def _imports_outright(path: Path) -> frozenset[str]:
+ """The top-level modules this file imports with no guard, counted statement by statement.
+
+ One import of a module inside a `try` doesn't excuse another outside it: the unguarded one is
+ what runs first and what fails, so a module imported both ways is imported outright.
+ """
+ tree = ast.parse(path.read_text())
+ guarded = {
+ id(inner)
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Try)
+ for inner in ast.walk(node)
+ if isinstance(inner, ast.Import | ast.ImportFrom)
+ }
+
+ found: set[str] = set()
+ for node in ast.walk(tree):
+ if id(node) in guarded:
+ continue
+
+ if isinstance(node, ast.Import):
+ found.update(alias.name.split(".")[0] for alias in node.names)
+ elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+ found.add(node.module.split(".")[0])
+
+ return frozenset(found)
+
+
+@functools.cache
+def _importers() -> dict[str, frozenset[str]]:
+ """Which files under the python root import each top-level module, as repo-relative paths."""
+ root = REPO_ROOT / _catalog()["blueprint"]["python_root"]
+ found: dict[str, set[str]] = {}
+ for path in sorted(root.rglob("*.py")):
+ for module in _module_imports(path):
+ found.setdefault(module.split(".")[0], set()).add(path.relative_to(REPO_ROOT).as_posix())
+
+ return {module: frozenset(files) for module, files in found.items()}
+
+
+def _declared_distributions(listing: str) -> set[str]:
+ """The distributions a listing names, the core's and every feature's together."""
+ return {_distribution(specifier) for specifier in _declared_specifiers(listing)}
+
+
+INDIRECT_NEEDS = {
+ "itsdangerous": ("starlette.middleware.sessions", "backend/src/interfaces/admin/auth.py"),
+ "user-agents": ("crudauth.transports.session.transport", "backend/src/infrastructure/auth/evictions.py"),
+}
+"""Distributions nothing imports by name, each with the import that needs it and the file that
+makes that import. `starlette` doesn't declare `itsdangerous`, and importing
+`crudauth.transports.session.transport` runs that package's `__init__`, which imports its
+`manager`, which imports `user_agents` inside a `try`. A project without either would refuse
+to start the admin panel, or record every session's device as unknown, with nothing naming
+what is missing."""
+
+
+NEEDED_WITHOUT_AN_IMPORT = {
+ "asyncpg": "the driver `POSTGRES_ASYNC_PREFIX` names, which sqlalchemy loads from the URL",
+ "greenlet": "what sqlalchemy runs a DBAPI call in, for its asyncio support",
+}
+"""Core distributions no file imports and no import pulls in: another distribution asks for them,
+or a setting names them as a driver. Written down so a project's image carries nothing nobody can
+account for."""
+
+
+def test_every_runtime_dependency_nothing_imports_is_accounted_for():
+ """Both ways: a distribution installed and never imported is either needed through something
+ else, which is worth writing down, or weight in every project's image for no reason."""
+ runtime = _declared_distributions("runtime")
+ imported = {name for name in runtime if _provided().get(name, frozenset()) & set(_importers())}
+
+ assert runtime - imported == set(INDIRECT_NEEDS) | set(NEEDED_WITHOUT_AN_IMPORT)
+
+
+def test_the_two_the_database_needs_are_the_blueprint_s_to_declare():
+ """Why neither can be left to sqlalchemy, read from the installed metadata and the settings.
+
+ `asyncpg` is the driver the URL names and sqlalchemy loads; `greenlet` is what sqlalchemy's
+ asyncio support runs a driver's calls in. Sqlalchemy asks for them only through extras the
+ backend doesn't declare, and the greenlet one outright on some platforms only, so a project
+ that installed plain `sqlalchemy` would have neither.
+ """
+ asked = requires("sqlalchemy") or ()
+ base = (REPO_ROOT / "backend/src/infrastructure/config/base.py").read_text()
+
+ assert 'POSTGRES_ASYNC_PREFIX: str = "postgresql+asyncpg://"' in base
+ assert any(entry.startswith("asyncpg") and entry.endswith('extra == "postgresql-asyncpg"') for entry in asked)
+ assert any(entry.startswith("greenlet") and entry.endswith('extra == "asyncio"') for entry in asked)
+ assert "sqlalchemy>=2.0.37" in _catalog()["blueprint"]["dependencies"]["runtime"], "plain, with no extras"
+
+
+@pytest.mark.parametrize(
+ ("feature", "specifier"),
+ sorted(
+ (name, specifier) for name, feature in _catalog()["features"].items() for specifier in feature.get("dependencies", ())
+ ),
+)
+def test_every_feature_dependency_is_one_that_feature_needs(feature: str, specifier: str):
+ """A dependency parked on the wrong feature is a project that installs it and never uses it,
+ or selects the feature and finds it missing."""
+ name = _distribution(specifier)
+ owned = [path for path, _ in _declared(_catalog()["features"][feature])]
+
+ if name in INDIRECT_NEEDS:
+ module, importer = INDIRECT_NEEDS[name]
+
+ assert _under(importer, owned), importer
+ assert module in _module_imports(REPO_ROOT / importer), module
+ assert not _provided()[name] & set(_importers()), f"{name} is imported by name now"
+
+ return
+
+ importers = {file for module in _provided()[name] for file in _importers().get(module, ())}
+ outright = {file for file in importers if _provided()[name] & _imports_outright(REPO_ROOT / file)}
+
+ assert importers, name
+ assert any(_under(file, owned) for file in outright), sorted(importers)
+
+
+def _needed_by(features: dict[str, Any]) -> dict[str, set[str]]:
+ """Each declared distribution, with the features that bring it. An option's brings an empty
+ set: a project selects the feature and still chooses another value, so nothing guarantees it."""
+ needed: dict[str, set[str]] = {}
+ for name, feature in features.items():
+ for specifier in feature.get("dependencies", ()):
+ needed.setdefault(_distribution(specifier), set()).add(name)
+ for option in feature.get("options", {}).values():
+ for specifiers in option.get("dependencies", {}).values():
+ for specifier in specifiers:
+ needed.setdefault(_distribution(specifier), set())
+
+ return needed
+
+
+def _removed_for(features: dict[str, Any], chosen: set[str]) -> list[str]:
+ """The owned paths this selection doesn't keep, which is what `_kept_by_the_catalog` leaves out."""
+ return [
+ path
+ for name, feature in features.items()
+ for path, condition in _declared(feature)
+ if name not in chosen or (condition is not None and not _true(condition, chosen))
+ ]
+
+
+def test_no_file_a_project_keeps_imports_a_dependency_it_did_not_select():
+ """The other half of moving a dependency off the core, over all 164 selections.
+
+ `fastro new` writes a project's `pyproject.toml` from the declarations (spec 6.3), so a file
+ kept without the feature that brings a distribution, importing it outright, is a project that
+ fails at import. Only the files that go with the feature may need it.
+ """
+ features = _catalog()["features"]
+ needed = _needed_by(features)
+
+ assert needed["sqladmin"] == {"admin"}
+ assert needed["aiomcache"] == set(), "an option's dependency is never guaranteed"
+
+ for chosen in _selections():
+ removed = _removed_for(features, chosen)
+ for name, owners in needed.items():
+ if owners & chosen:
+ continue
+
+ for module in _provided()[name]:
+ for file in _importers().get(module, ()):
+ if not _provided()[name] & _imports_outright(REPO_ROOT / file):
+ continue
+
+ assert _under(file, removed) or _withheld(file), (sorted(chosen), name, file)
+
+
+@functools.cache
+def _project_modules_imported(file: str) -> frozenset[str]:
+ """The project's own modules this file imports, as repo-relative paths with no suffix.
+
+ A relative import is resolved against the file's package, and each name a `from` import takes
+ counts as a submodule too, since it may be one.
+ """
+ root = _catalog()["blueprint"]["python_root"]
+ tops = {path.name for path in (REPO_ROOT / root).iterdir() if path.is_dir()}
+ package = Path(file).relative_to(root).parts[:-1]
+ found: set[tuple[str, ...]] = set()
+ for node in ast.walk(ast.parse((REPO_ROOT / file).read_text())):
+ if isinstance(node, ast.Import):
+ found.update(tuple(alias.name.split(".")) for alias in node.names)
+ elif isinstance(node, ast.ImportFrom):
+ anchor = package[: len(package) - node.level + 1] if node.level else ()
+ base = anchor + (tuple(node.module.split(".")) if node.module else ())
+ found.add(base)
+ found.update((*base, alias.name) for alias in node.names)
+
+ return frozenset(f"{root}/{'/'.join(parts)}" for parts in found if parts and parts[0] in tops)
+
+
+def test_no_file_a_project_keeps_imports_a_module_the_selection_removed():
+ """Over all 164 selections, a kept file never imports the project's own code from a path a
+ feature left out took with it: that project fails at import, or ships a test that can't.
+
+ The generated wiring is left out here, since fastro writes it for each selection.
+ """
+ features = _catalog()["features"]
+ generated = {entry["path"] for entry in _entries()}
+ root = REPO_ROOT / _catalog()["blueprint"]["python_root"]
+ files = sorted(path.relative_to(REPO_ROOT).as_posix() for path in root.rglob("*.py"))
+ broken: dict[str, set[str]] = {}
+
+ for chosen in _selections():
+ removed = _removed_for(features, chosen)
+ for file in files:
+ if file in generated or _withheld(file) or _under(file, removed):
+ continue
+ for module in _project_modules_imported(file):
+ if _under(module, removed) or _under(f"{module}.py", removed):
+ broken.setdefault(file, set()).add(",".join(sorted(chosen)))
+
+ assert {file: len(selections) for file, selections in broken.items()} == {}
+
+
+@pytest.mark.parametrize(
+ ("feature", "specifier"),
+ sorted(
+ (name, specifier)
+ for name, feature in _catalog()["features"].items()
+ for specifier in feature.get("dev_dependencies", ())
+ ),
+)
+def test_every_feature_development_dependency_belongs_to_that_feature(feature: str, specifier: str):
+ """An extra is never imported by name, so what makes it the feature's is the distribution it
+ extends: `taskiq[reload]` is the taskiq worker's own `--reload`, and a project with no worker
+ has nothing to reload. A file of the feature's importing it counts too, for a test-only
+ dependency that is imported.
+ """
+ name = _distribution(specifier)
+ runtime = {_distribution(entry) for entry in _catalog()["features"][feature].get("dependencies", ())}
+ owned = [path for path, _ in _declared(_catalog()["features"][feature])]
+ importers = {file for module in _provided().get(name, ()) for file in _importers().get(module, ())}
+
+ assert name in runtime or any(_under(file, owned) for file in importers), name
+
+
+@pytest.mark.parametrize(
+ ("feature", "option", "value", "specifier"),
+ sorted(
+ (name, option, value, specifier)
+ for name, feature in _catalog()["features"].items()
+ for option, declared in feature.get("options", {}).items()
+ for value, specifiers in declared.get("dependencies", {}).items()
+ for specifier in specifiers
+ ),
+)
+def test_every_option_dependency_is_one_its_value_needs(feature: str, option: str, value: str, specifier: str):
+ """Spec 2.5: the value has to be one of the option's choices, and the file that imports the
+ distribution has to belong to the feature that offers it."""
+ declared = _catalog()["features"][feature]["options"][option]
+ owned = [path for path, _ in _declared(_catalog()["features"][feature])]
+ importers = {file for module in _provided()[_distribution(specifier)] for file in _importers().get(module, ())}
+
+ assert value in declared["choices"]
+ assert importers, specifier
+ assert all(_under(file, owned) for file in importers), sorted(importers)
+ for file in importers:
+ assert not _provided()[_distribution(specifier)] & _imports_outright(REPO_ROOT / file), (
+ f"{file} imports {specifier} without a guard, and a project that chose another value has it absent"
+ )
+
+
+def test_no_runtime_dependency_is_one_only_the_tests_import():
+ """A distribution only the tests import is installed in production for nothing.
+
+ `backend/Dockerfile` installs the runtime list with `--no-dev`, so that is the list that
+ decides the image. A distribution nothing imports at all is left alone here: several are
+ needed indirectly, through something that doesn't declare them.
+ """
+ runtime = _declared_distributions("runtime")
+ application = _imported("src", "scripts", "migrations")
+ tests = _imported("tests")
+
+ only_tested = {
+ name for name in runtime if _provided().get(name, frozenset()) & tests and not _provided()[name] & application
+ }
+
+ assert only_tested == set()
+
+
+DEVELOPMENT_SCRIPT = "scripts/baseline.py"
+"""The one script a project runs from its development environment rather than from the image."""
+
+
+def test_no_dependency_the_application_imports_is_declared_for_development_only():
+ """The other way round, where `uv export --no-dev` would leave an import with nothing behind it.
+
+ The scripts are read too, because an operator runs them in the image: the first-run guide
+ seeds a deployment with `docker compose exec api python -m scripts.setup_initial_data`, and
+ the repairs, the usage prune and the account unlock are all run the same way. `baseline.py`
+ is the exception, and the only one: it writes a project's first migration against a container
+ it starts itself, which is a thing to do once, from a checkout.
+ """
+ development = _declared_distributions("dev") - _declared_distributions("runtime")
+ application = _imported("src", "scripts", "migrations", skipping=(DEVELOPMENT_SCRIPT,))
+
+ assert {name for name in development if _provided().get(name, frozenset()) & application} == set()
+
+
+def test_the_dependency_readings_find_what_they_claim_to():
+ """Both rules report what they found, so a reading that stopped working would pass quietly."""
+ assert "fastapi" in _imported("src", "migrations")
+ assert "pytest" in _imported("tests")
+ assert _provided()["sqlalchemy"] == frozenset({"sqlalchemy"})
+ assert "testcontainers" in _imported("scripts")
+ assert "testcontainers" not in _imported("scripts", skipping=(DEVELOPMENT_SCRIPT,))
+ assert "asyncio" in _imported("scripts", skipping=(DEVELOPMENT_SCRIPT,)), "the other scripts are still read"
+
+
+@pytest.mark.parametrize("entry", sorted(_catalog()["blueprint"]["blueprint_only"]))
+def test_every_blueprint_only_path_is_written_the_way_the_spec_reads_them(entry: str):
+ """Spec 1.1: a trailing slash means the subtree, and without one it is a single file.
+
+ `docs` rather than `docs/` would name one file nobody has, and the whole tree would
+ reach projects.
+ """
+ assert not entry.startswith("/")
+ assert ".." not in Path(entry).parts
+ assert entry.endswith("/") == (REPO_ROOT / entry).is_dir()
+
+
+@pytest.mark.parametrize("entry", sorted(_catalog()["blueprint"]["blueprint_only"]))
+def test_every_blueprint_only_path_is_one_this_repo_has(entry: str):
+ """A path that no longer exists keeps a file out of projects that nobody meant to keep out."""
+ assert (REPO_ROOT / entry).exists()
+
+
+def _withheld(path: str) -> bool:
+ """Whether `blueprint_only` keeps a project from receiving this path (spec 1.1 subtrees)."""
+ return any(
+ path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry))
+ for entry in _catalog()["blueprint"]["blueprint_only"]
+ )
+
+
+def _workspace_members() -> list[str]:
+ with (REPO_ROOT / "pyproject.toml").open("rb") as handle:
+ return list(tomllib.load(handle)["tool"]["uv"]["workspace"]["members"])
+
+
+def _root_project_paths() -> list[str]:
+ """The workspace members and the test paths the root `pyproject.toml` names."""
+ root = _root_project()
+
+ return [*root["tool"]["uv"]["workspace"]["members"], *root["tool"]["pytest"]["ini_options"]["testpaths"]]
+
+
+def _unwrapped(pattern: str) -> str:
+ """A pattern without the one group that wraps all of it, if there is one."""
+ depth = 0
+ for index, character in enumerate(pattern):
+ depth += {"(": 1, ")": -1}.get(character, 0)
+ if depth == 0:
+ return pattern[1:-1] if pattern.startswith("(") and index == len(pattern) - 1 else pattern
+
+ return pattern
+
+
+def _alternatives(pattern: str) -> list[str]:
+ """The top-level alternatives of an anchored pattern, outside a group that wraps it whole."""
+ body = _unwrapped(pattern.removeprefix("^").removesuffix("$"))
+
+ parts, depth, start = [], 0, 0
+ for index, character in enumerate(body):
+ depth += {"(": 1, "[": 1, ")": -1, "]": -1}.get(character, 0)
+ if character == "|" and depth == 0:
+ parts.append(body[start:index])
+ start = index + 1
+
+ return [*parts, body[start:]]
+
+
+def _literal_head(pattern: str) -> str:
+ """The characters a pattern matches literally before its first special one, unescaped."""
+ head = re.match(r"(?:[^\\()\[\]{}|?*+.^$]|\\[./-])*", pattern)
+ assert head is not None
+
+ return re.sub(r"\\(.)", r"\1", head.group())
+
+
+def _pattern_heads(pattern: str) -> list[str]:
+ """The path each alternative of a pre-commit `files:` pattern starts with, through nested ones."""
+ alternatives = _alternatives(pattern)
+ if len(alternatives) > 1:
+ return [head for alternative in alternatives for head in _pattern_heads(alternative)]
+
+ return [_literal_head(alternatives[0]).rstrip("/")]
+
+
+def _named_paths(patterns: list[str]) -> list[str]:
+ """The paths the patterns name, refusing one whose head is empty: it would name nothing to check."""
+ heads = [head for pattern in patterns for head in _pattern_heads(pattern)]
+ assert all(heads), patterns
+
+ return heads
+
+
+def _hook_paths() -> list[str]:
+ """The paths the pre-commit `files:` patterns name, one per alternative."""
+ return _named_paths(re.findall(r"^\s*files: (\S+)$", (REPO_ROOT / ".pre-commit-config.yaml").read_text(), re.M))
+
+
+@pytest.mark.parametrize(
+ ("pattern", "heads"),
+ [
+ ("^docs/", ["docs"]),
+ ("^backend/(src|scripts|migrations|tests)/", ["backend"]),
+ (r"^(blueprint\.toml|fastro\.toml|backend/src/wiring/)", ["blueprint.toml", "fastro.toml", "backend/src/wiring"]),
+ (r"^(a\.py)|(b/)$", ["a.py", "b"]),
+ (r"^(a|(b\.py|c/))$", ["a", "b.py", "c"]),
+ (r"^(a|b)/x", [""]),
+ ],
+)
+def test_the_hook_reader_sees_every_path_a_pattern_names(pattern: str, heads: list[str]):
+ """An alternation names one path per branch, and an escaped dot is part of the name."""
+ assert _pattern_heads(pattern) == heads
+
+
+def test_the_hook_reader_refuses_a_pattern_that_names_no_path():
+ """A head of `""` is never withheld, so the rules that read it would pass over nothing."""
+ with pytest.raises(AssertionError):
+ _named_paths([r"^(a|b)/x"])
+
+
+def _readme_references() -> list[str]:
+ """The files the README's own markup points at, leaving out what it fetches over the network."""
+ found = re.findall(r'src(?:set)?="([^"]+)"', (REPO_ROOT / "README.md").read_text())
+
+ return [reference for reference in found if not reference.startswith("http")]
+
+
+POINTS_AT = {
+ "pyproject.toml": _root_project_paths,
+ ".pre-commit-config.yaml": _hook_paths,
+ "README.md": _readme_references,
+}
+"""Each root file that names paths, read the way that file spells them."""
+
+
+@pytest.mark.parametrize("path", sorted(POINTS_AT))
+def test_no_file_a_project_receives_points_at_one_it_does_not(path: str):
+ """Either the pointer goes or the file does.
+
+ A workspace member a project never receives is a project `uv sync` refuses; a test path is
+ a pytest run that collects nothing; a lint pattern is a hook over nothing; an image is a
+ hole where the cover was. The three root files are the blueprint's own, so they are the
+ ones that go.
+ """
+ withheld = sorted(target for target in POINTS_AT[path]() if _withheld(target))
+
+ assert not withheld or _withheld(path), (path, withheld)
+
+
+WITHHELD_POINTERS = {
+ "pyproject.toml": "blueprint/tests",
+ ".pre-commit-config.yaml": "blueprint.toml",
+ "README.md": "docs/assets",
+}
+"""What keeps each of the three out of a project, pinned so a reader of it can't go quiet."""
+
+
+@pytest.mark.parametrize("path", sorted(POINTS_AT))
+def test_each_file_still_names_the_path_that_keeps_it_out(path: str):
+ """The reason each file is blueprint-only, rather than the fact of it.
+
+ A format that moved on -- a renamed pre-commit key, an image moved out of `docs/` -- would
+ leave the rule above with nothing to object to, and the file would ship. The root
+ `pyproject.toml` is kept out by the blueprint's own tests, which its pytest config runs.
+ """
+ pointed = POINTS_AT[path]()
+
+ assert any(target.startswith(WITHHELD_POINTERS[path]) for target in pointed), pointed
+
+
+ROOT_PYPROJECT = REPO_ROOT / "pyproject.toml"
+FASTRO_REPOSITORY = "https://github.com/benavlabs/fastro"
+COMMIT = re.compile(r"^[0-9a-f]{40}$")
+
+
+def _root_project() -> dict[str, Any]:
+ with ROOT_PYPROJECT.open("rb") as handle:
+ return tomllib.load(handle)
+
+
+def test_the_backend_is_the_workspaces_one_member():
+ """The old developer tool's package is gone."""
+ assert _workspace_members() == ["backend"]
+
+
+def test_the_repository_root_installs_fastro_for_its_own_checks():
+ """fastro checks the blueprint, so the root project, which no project receives, carries it."""
+ assert _withheld("pyproject.toml")
+ assert "fastro" in {_distribution(specifier) for specifier in _root_project()["dependency-groups"]["dev"]}
+
+
+def test_fastro_is_pinned_to_one_commit_of_its_repository():
+ """Unreleased, so a commit is the only version a lock can hold steady."""
+ source = _root_project()["tool"]["uv"]["sources"]["fastro"]
+
+ assert source.keys() == {"git", "rev"}
+ assert source["git"] == FASTRO_REPOSITORY
+ assert COMMIT.match(source["rev"]), source["rev"]
+
+
+def test_no_project_receives_the_fastro_pin():
+ """A project gets `backend/pyproject.toml`, and its own checks run fastro through `uvx`."""
+ with BACKEND_PYPROJECT.open("rb") as handle:
+ backend = tomllib.load(handle)
+
+ groups = [
+ backend["project"].get("dependencies", []),
+ *backend["project"].get("optional-dependencies", {}).values(),
+ *backend.get("dependency-groups", {}).values(),
+ ]
+
+ assert "fastro" not in {_distribution(specifier) for group in groups for specifier in group}
+ assert "fastro" not in backend.get("tool", {}).get("uv", {}).get("sources", {})
+
+
+def _pre_commit_repositories(config: str | None = None) -> list[dict[str, Any]]:
+ """Each `- repo:` entry of `.pre-commit-config.yaml`, parsed."""
+ parsed = yaml.safe_load((REPO_ROOT / ".pre-commit-config.yaml").read_text() if config is None else config)
+ repositories: list[dict[str, Any]] = parsed["repos"]
+
+ return repositories
+
+
+def _pre_commit_hooks(config: str | None = None) -> list[dict[str, Any]]:
+ return [hook for repository in _pre_commit_repositories(config) for hook in repository["hooks"]]
+
+
+def test_the_pre_commit_reader_reads_what_yaml_means_not_how_it_is_written():
+ hooks = _pre_commit_hooks(
+ "repos:\n"
+ " - repo: local\n"
+ " hooks:\n"
+ ' - id: "commented" # why\n'
+ " # a note\n"
+ " entry: run it # how\n"
+ "\n"
+ " stages: [ 'manual' ]\n"
+ " - id: listed\n"
+ " stages:\n"
+ " - manual # first\n"
+ " - pre-push\n"
+ " pass_filenames: false\n"
+ )
+
+ assert hooks == [
+ {"id": "commented", "entry": "run it", "stages": ["manual"]},
+ {"id": "listed", "stages": ["manual", "pre-push"], "pass_filenames": False},
+ ]
+
+
+def _the_sync_check_hook() -> dict[str, Any]:
+ hooks = [hook for hook in _pre_commit_hooks() if "fastro sync --check" in hook.get("entry", "")]
+ assert len(hooks) == 1, hooks
+
+ return hooks[0]
+
+
+SYNC_CHECK_TRIGGERS_BY_NAME = {"blueprint.toml", "fastro.toml", "pyproject.toml", "uv.lock"}
+"""The files the guides name as running the sync check; the wiring they name by what it is."""
+
+
+def _path_spans(text: str) -> set[str]:
+ """Each code span that reads as a path: no spaces, and a directory or an extension."""
+ return {span for span in re.findall(r"`([^`]+)`", text) if re.fullmatch(r"[\w./-]+", span) and re.search(r"[/.]", span)}
+
+
+def _assert_names_the_sync_check_triggers(text: str) -> None:
+ assert _path_spans(text) == SYNC_CHECK_TRIGGERS_BY_NAME, _path_spans(text)
+ for path in _path_spans(text):
+ assert re.search(_the_sync_check_hook()["files"], path), path
+
+
+def test_a_commit_runs_sync_check_on_the_whole_tree():
+ """`sync --check` compares every wiring file, so the hook hands it no file names."""
+ hook = _the_sync_check_hook()
+
+ assert hook["entry"] == "uv run --no-sync fastro sync --check"
+ assert hook["language"] == "system"
+ assert hook["pass_filenames"] is False
+
+
+def test_the_sync_check_hook_runs_at_every_commit():
+ """Any key beyond these narrows when it runs: a stage, an exclusion, a file type."""
+ assert _the_sync_check_hook().keys() == {"id", "name", "language", "entry", "pass_filenames", "files"}
+
+
+@pytest.mark.parametrize("path", ["blueprint.toml", "fastro.toml", *(entry["path"] for entry in _catalog()["wiring"])])
+def test_a_commit_that_touches_what_sync_compares_runs_sync_check(path: str):
+ """The catalog, the selection and every file it generates, so a new wiring file can't slip by."""
+ assert re.search(_the_sync_check_hook()["files"], path), path
+
+
+@pytest.mark.parametrize("path", ["pyproject.toml", "uv.lock"])
+def test_a_commit_that_moves_the_fastro_pin_runs_sync_check(path: str):
+ """Another fastro can render the same catalog differently, so the files that pin it count too."""
+ assert re.search(_the_sync_check_hook()["files"], path), path
+
+
+def test_a_commit_that_touches_nothing_sync_compares_skips_sync_check():
+ for path in (
+ "backend/src/modules/user/models.py",
+ "docs/backend/src/wiring/app.md",
+ "backend/fastro.toml",
+ "blueprint.toml.orig",
+ "backend/pyproject.toml",
+ "backend/uv.lock",
+ "uv_lock",
+ "pyproject_toml",
+ "fastro_toml",
+ "blueprint_toml",
+ ):
+ assert not re.search(_the_sync_check_hook()["files"], path), path
+
+
+def _hook_repositories() -> dict[str, str]:
+ """Each hook id in `.pre-commit-config.yaml`, with the repository it comes from."""
+ return {hook["id"]: repository["repo"] for repository in _pre_commit_repositories() for hook in repository["hooks"]}
+
+
+def _development_guide_pre_commit_section() -> str:
+ guide = (REPO_ROOT / "docs" / "user-guide" / "development.md").read_text()
+
+ return guide.split("## Pre-Commit", 1)[1].split("\n\n## ", 1)[0]
+
+
+def _development_guide_hook_rows() -> dict[str, str]:
+ """The guide's pre-commit table, each row keyed by each hook its first cell names, or by the cell if it names none."""
+ rows = re.findall(r"^\| (?!Hook\b|-)(.+?) \| (.+) \|$", _development_guide_pre_commit_section(), re.M)
+
+ named = [
+ (name, cells)
+ for names, cells in rows
+ for name in [code.split()[0] for code in re.findall(r"`([^`]+)`", names)] or [names]
+ ]
+ assert len({name for name, _ in named}) == len(named), named
+
+ return dict(named)
+
+
+def test_the_development_guide_names_every_hook_a_commit_runs():
+ assert _hook_repositories()
+ assert set(_hook_repositories()) <= set(_development_guide_hook_rows())
+
+
+def test_the_development_guide_names_no_hook_the_config_lacks():
+ assert set(_development_guide_hook_rows()) <= set(_hook_repositories())
+
+
+def test_the_development_guide_says_which_hooks_are_local():
+ rows = _development_guide_hook_rows()
+ local = {hook for hook, repository in _hook_repositories().items() if repository == "local"}
+
+ assert local
+ assert {hook for hook, cells in rows.items() if cells.startswith("local")} == local
+
+
+def test_the_development_guide_says_which_hooks_run_only_when_asked_for():
+ manual = {hook["id"] for hook in _pre_commit_hooks() if hook.get("stages") == ["manual"]}
+
+ assert manual
+ assert {hook for hook, cells in _development_guide_hook_rows().items() if "manual stage" in cells} == manual
+
+
+def test_the_development_guide_gives_the_command_the_sync_check_hook_runs():
+ row = _development_guide_hook_rows()[_the_sync_check_hook()["id"]]
+ entry = f"`{_the_sync_check_hook()['entry']}`"
+
+ assert entry in row
+ _assert_names_the_sync_check_triggers(row)
+ assert "wiring" in row.replace(entry, "")
+
+
+def _hook_shell_line(hook: dict[str, str]) -> str:
+ """What a hook runs, without the `bash -c` that lets a local hook change directory first."""
+ found = re.fullmatch(r"bash -c '(.+)'", hook["entry"])
+
+ return found[1] if found else hook["entry"]
+
+
+def _ci_runs_command(command: str) -> bool:
+ """Whether a CI step runs this command, alone or on paths after it."""
+ return any(re.fullmatch(rf"(?:uv run --no-sync )?{re.escape(command)}(?: [^-\s]\S*)*", run) for run in _workflow_runs())
+
+
+def _names_ci(row: str) -> bool:
+ """Whether a row of the development guide's hook table says what CI runs."""
+ return re.search(r"\bCI\b", row) is not None
+
+
+def _ci_runs_hook(hook: dict[str, str]) -> bool:
+ """Whether a CI step runs a local hook's command, as it is or on every path instead of the ones it names."""
+ line = _hook_shell_line(hook)
+
+ return line in _workflow_runs() or _without_trailing_paths(line) in _workflow_runs()
+
+
+def _names_a_path(word: str) -> bool:
+ return any(mark in word for mark in "/.") and all(char.isalnum() or char in "_./-" for char in word)
+
+
+def _without_trailing_paths(line: str) -> str:
+ """The line with the space-separated paths it ends in dropped: a word of letters, digits,
+ ``_``, ``.``, ``/`` and ``-`` that holds a ``/`` or a ``.``. The first word always stays, and so
+ does a newline the line ends in."""
+ body, newline = (line[:-1], "\n") if line.endswith("\n") else (line, "")
+ words = body.split(" ")
+ while len(words) > 1 and _names_a_path(words[-1]):
+ words.pop()
+
+ return " ".join(words) + newline
+
+
+@pytest.mark.parametrize(
+ ("line", "kept"),
+ [
+ ("uv run --no-sync ruff check src/app.py tests/x.py", "uv run --no-sync ruff check"),
+ ("cd backend && mypy src/a.py", "cd backend && mypy"),
+ ("ruff format --check .", "ruff format --check"),
+ ("mypy src tests", "mypy src tests"),
+ ("pytest -q", "pytest -q"),
+ ("x.py", "x.py"),
+ ("ruff --config=a.toml", "ruff --config=a.toml"),
+ ("run a/b c/d", "run a/b "),
+ ("mypy src/ ", "mypy src/ "),
+ ("run src/a.py tests", "run src/a.py tests"),
+ ("run ../up", "run"),
+ ("run tests/unit_2/my-file.py", "run"),
+ ("x a/b\n", "x\n"),
+ ],
+)
+def test_a_hook_line_drops_the_paths_it_ends_in(line: str, kept: str):
+ assert _without_trailing_paths(line) == kept
+
+
+def test_a_long_line_of_dots_is_read_at_once():
+ line = "run" + " .." * 100_000 + " !"
+ started = time.perf_counter()
+
+ assert _without_trailing_paths(line) == line
+ assert _without_trailing_paths(line[:-2]) == "run"
+ assert time.perf_counter() - started < 1
+
+
+def test_the_hooks_the_development_guide_says_ci_runs_run_what_ci_runs():
+ rows = _development_guide_hook_rows()
+ claimed = [hook for hook in _pre_commit_hooks() if _names_ci(rows[hook["id"]])]
+
+ assert claimed
+ for hook in claimed:
+ if "entry" in hook:
+ assert _ci_runs_hook(hook), hook["id"]
+ else:
+ commands = [span for span in re.findall(r"`([^`]+)`", rows[hook["id"]]) if " " in span]
+ assert any(command.startswith(hook["id"].replace("-", " ")) for command in commands), hook["id"]
+ for command in commands:
+ assert _ci_runs_command(command), command
+
+
+def test_the_hooks_the_development_guide_leaves_ci_out_of_are_no_ci_step():
+ rows = _development_guide_hook_rows()
+ unclaimed = [hook for hook in _pre_commit_hooks() if not _names_ci(rows[hook["id"]])]
+
+ assert unclaimed
+ for hook in unclaimed:
+ if "entry" in hook:
+ assert not _ci_runs_hook(hook), hook["id"]
+ else:
+ for name in {hook["id"], hook["id"].replace("-", " ")}:
+ assert not any(re.search(rf"\b{re.escape(name)}\b", run) for run in _workflow_runs()), name
+
+
+def test_the_development_guide_gives_the_command_each_manual_hook_runs_and_where():
+ manual = [hook for hook in _pre_commit_hooks() if hook.get("stages") == ["manual"]]
+
+ assert manual
+ for hook in manual:
+ found = re.fullmatch(r"cd (\S+) && (.+)", _hook_shell_line(hook))
+ assert found, hook["id"]
+ directory, command = found.groups()
+ row = _development_guide_hook_rows()[hook["id"]]
+ assert f"`{command}`" in row, row
+ assert f"`{directory}/`" in row, row
+
+
+def _development_guide_pre_commit_prose() -> str:
+ """The development guide's Pre-Commit section, past its hook table."""
+ return _development_guide_pre_commit_section().rsplit("\n|", 1)[1].split("\n", 1)[1]
+
+
+def test_some_unit_tests_start_containers_through_testcontainers():
+ """The development guide's claim; `blueprint/tests/test_pre_commit.py` runs the hook without Docker to show they skip."""
+ unit = REPO_ROOT / "backend" / "tests" / "unit"
+
+ assert "`testcontainers`" in _development_guide_pre_commit_prose()
+ assert any(
+ isinstance(node, ast.ImportFrom) and re.fullmatch(r"testcontainers(?:\..+)?", node.module or "")
+ for path in unit.rglob("*.py")
+ if path != Path(__file__).resolve()
+ for node in ast.walk(ast.parse(path.read_text()))
+ )
+
+
+def test_docker_counts_as_not_running_when_its_client_cannot_connect(monkeypatch):
+ monkeypatch.setenv("DOCKER_HOST", "tcp://127.0.0.1:1")
+ monkeypatch.setattr("testcontainers.core.config.testcontainers_config.tc_properties", {})
+
+ assert is_docker_running() is False
+
+
+def test_the_project_puts_an_attribute_docstring_under_a_module_level_name():
+ """Why the development guide leaves `check-docstring-first` out."""
+ documented = [
+ path
+ for path in sorted((REPO_ROOT / "backend").glob("[st]*/**/*.py"))
+ if any(
+ isinstance(name, ast.Assign | ast.AnnAssign)
+ and isinstance(docstring, ast.Expr)
+ and isinstance(docstring.value, ast.Constant)
+ and isinstance(docstring.value.value, str)
+ for name, docstring in itertools.pairwise(ast.parse(path.read_text()).body)
+ )
+ ]
+
+ assert any(path.is_relative_to(REPO_ROOT / "backend" / "src") for path in documented), documented
+ assert "`check-docstring-first`" in _development_guide_pre_commit_prose()
+
+
+def test_the_hooks_the_development_guide_leaves_out_are_not_in_the_config():
+ left_out = {"mdformat", "blacken-docs", "check-docstring-first"}
+ named = set(re.findall(r"`([\w-]+)`", _development_guide_pre_commit_prose()))
+
+ assert left_out <= named
+ assert not left_out & set(_hook_repositories())
+ assert "ruff-format" in named & set(_hook_repositories())
+
+
+def test_the_extra_the_development_guide_names_installs_pre_commit():
+ prose = _development_guide_pre_commit_prose()
+ extra = re.search(r"`pre-commit` ships in the `([\w-]+)` extra, so `(uv sync[^`]*)`", prose)
+ assert extra, prose
+
+ assert {"--all-packages", "--all-extras"} <= set(extra[2].split())
+ assert any(
+ re.match(r"pre-commit(?![\w.-])", requirement)
+ for member in tomllib.loads((REPO_ROOT / "pyproject.toml").read_text())["tool"]["uv"]["workspace"]["members"]
+ for requirement in tomllib.loads((REPO_ROOT / member / "pyproject.toml").read_text())["project"]
+ .get("optional-dependencies", {})
+ .get(extra[1], [])
+ )
+
+
+def test_each_hook_the_development_guide_runs_by_name_is_in_the_config_at_the_stage_it_gives():
+ runs = re.findall(r"pre-commit run (\w[\w-]*)(.*)$", _development_guide_pre_commit_prose(), re.M)
+ hooks = {hook["id"]: hook for hook in _pre_commit_hooks()}
+
+ assert runs
+ for hook, flags in runs:
+ assert hook in hooks, hook
+ stage = re.search(r"--hook-stage (\w+)", flags)
+ assert hooks[hook].get("stages", ["pre-commit"]) == [stage[1] if stage else "pre-commit"], hook
+
+
+def test_each_pre_commit_command_the_development_guide_gives_takes_the_flags_it_passes():
+ prose = _development_guide_pre_commit_prose()
+ commands = re.findall(r"^uv run --no-sync pre-commit (\w+)(.*)$", prose, re.M)
+
+ assert commands
+ for fence in re.findall(r"^```bash\n(.*?)^```$", prose, re.M | re.S):
+ for line in fence.splitlines():
+ assert "pre-commit" not in line or line.startswith("uv run --no-sync pre-commit "), line
+ for subcommand, arguments in commands:
+ usage = subprocess.run(
+ [sys.executable, "-m", "pre_commit", subcommand, "--help"], capture_output=True, text=True, check=False
+ )
+ assert usage.returncode == 0, subcommand
+ for flag in re.findall(r"(? list[str]:
+ """Each line every `run:` in the repository's own CI runs, a block's line by line."""
+ if workflows is None:
+ workflows = [workflow.read_text() for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml"))]
+
+ return [
+ line.strip()
+ for workflow in workflows
+ for job in yaml.safe_load(workflow)["jobs"].values()
+ for step in job.get("steps", [])
+ for line in str(step.get("run", "")).splitlines()
+ if line.strip()
+ ]
+
+
+def test_the_workflow_reader_reads_every_run_and_a_block_line_by_line():
+ workflow = (
+ "jobs:\n"
+ " a:\n"
+ " steps:\n"
+ " - run: uv sync # first\n"
+ " - name: named\n"
+ " run: 'uv run --no-sync pytest'\n"
+ " - name: block\n"
+ " run: |\n"
+ " echo one\n"
+ "\n"
+ " if true; then\n"
+ " echo two\n"
+ " fi\n"
+ " b:\n"
+ " uses: ./.github/workflows/other.yml\n"
+ )
+
+ assert _workflow_runs([workflow]) == ["uv sync", "uv run --no-sync pytest", "echo one", "if true; then", "echo two", "fi"]
+
+
+def test_ci_type_checks_the_blueprint_tests_it_runs():
+ """A test file nobody type-checks can drift from the code it reads, and only fail when it runs."""
+ runs = _workflow_runs()
+ tested = {
+ argument.rstrip("/")
+ for run in runs
+ if run.startswith("uv run --no-sync pytest ")
+ for argument in run.split()[4:]
+ if argument.startswith("blueprint/")
+ }
+ checked = [run.split()[4:] for run in runs if run.startswith("uv run --no-sync mypy ")]
+
+ assert tested
+ for directory in tested:
+ assert any(
+ directory == path.rstrip("/") or directory.startswith(path.rstrip("/") + "/") for paths in checked for path in paths
+ ), directory
+
+
+def _defaults_blocks(workflow: str) -> list[str]:
+ """Each `defaults:` block of a workflow, at any level, with its value written on the same line or below it."""
+ lines = workflow.splitlines()
+ blocks = []
+ for index, line in enumerate(lines):
+ found = re.match(r"^( *)defaults:(.*)$", line)
+ if found is None:
+ continue
+
+ block = [found.group(2)]
+ for following in lines[index + 1 :]:
+ if following.strip() and len(following) - len(following.lstrip()) <= len(found.group(1)):
+ break
+ block.append(following)
+ blocks.append("\n".join(block))
+
+ return blocks
+
+
+@pytest.mark.parametrize(
+ "workflow",
+ [
+ "defaults:\n run:\n working-directory: backend\njobs:\n",
+ "jobs:\n lint:\n defaults:\n run:\n shell: bash\n working-directory: backend\n steps:\n",
+ "jobs:\n lint:\n defaults: {run: {working-directory: backend}}\n",
+ ],
+)
+def test_the_defaults_reader_sees_a_working_directory_however_it_is_written(workflow: str):
+ assert any("working-directory" in block for block in _defaults_blocks(workflow))
+
+
+def test_the_defaults_reader_stops_at_the_end_of_its_block():
+ workflow = "defaults:\n run:\n shell: bash\njobs:\n lint:\n steps:\n - working-directory: backend\n"
+
+ assert not any("working-directory" in block for block in _defaults_blocks(workflow))
+
+
+SYNC_THAT_KEEPS_THE_DEV_GROUP = {"uv", "sync", "--all-packages", "--all-extras", "--locked", "--python", "3.11"}
+"""The words a sync may use and still install the root dev group, where fastro is."""
+
+
+@pytest.mark.parametrize("command", ["fastro sync --check", "fastro blueprint lint"])
+def test_ci_runs_fastros_checks_where_fastro_is_installed(command: str):
+ """From the repository root, the project that declares fastro, never after a `cd`, and always gating the job."""
+ assert [run for run in _workflow_runs() if command in run] == [f"uv run --no-sync {command}"]
+
+ for workflow in sorted((REPO_ROOT / ".github" / "workflows").glob("*.yml")):
+ text = workflow.read_text()
+ steps = [step for step in re.split(r"\n(?= +- )", text) if command in step]
+ if steps:
+ assert not any("working-directory" in block for block in _defaults_blocks(text)), workflow.name
+ for step in steps:
+ assert set(re.findall(r"^\s*(?:- )?([\w-]+):", step, re.M)) == {"name", "run"}, step
+
+ syncs = re.findall(r"^\s+run: (uv sync\b.*)$", text, re.M)
+ assert syncs, workflow.name
+ for sync in syncs:
+ assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync
+
+
+CONTRIBUTING = REPO_ROOT / "CONTRIBUTING.md"
+
+UV_THAT_WROTE_THE_LOCK = {5: "0.13.8"}
+"""The uv release this repository's lock was first written with at each revision, not the first release that writes it."""
+
+
+def _contributing_syncs() -> list[str]:
+ """Each sync the guide gives as a command on its own line, not a sync it names inline in prose."""
+ return re.findall(r"^\s*(?:\$\s+)?(uv sync\b.*)$", CONTRIBUTING.read_text(), re.M)
+
+
+def _imported_modules(module: str, source: str) -> set[str]:
+ """Each module a file imports, and each name it imports from one, with relative imports resolved."""
+ package = module.split(".")[:-1]
+ imported: set[str] = set()
+ for node in ast.walk(ast.parse(source)):
+ if isinstance(node, ast.Import):
+ imported.update(alias.name for alias in node.names)
+ elif isinstance(node, ast.ImportFrom):
+ anchor = package[: len(package) - node.level + 1] if node.level else []
+ base = ".".join([*anchor, *filter(None, [node.module])])
+ imported.add(base)
+ imported.update(f"{base}.{alias.name}" for alias in node.names)
+
+ return imported
+
+
+def test_every_test_that_reads_the_docs_or_imports_a_withheld_test_stays_in_the_blueprint():
+ backend = REPO_ROOT / "backend"
+ files = {".".join(path.relative_to(backend).with_suffix("").parts): path for path in (backend / "tests").rglob("*.py")}
+ withheld = {module for module, path in files.items() if _withheld(str(path.relative_to(REPO_ROOT)))}
+ reading = []
+ for module, path in sorted(files.items()):
+ source = path.read_text()
+ if re.search(r"""(?:["']|\}/|\.\./)docs["'/]""", source) or withheld & _imported_modules(module, source):
+ reading.append(path)
+
+ assert {f"test_docs_{name}.py" for name in ("imports", "recipes", "scripts", "wiring")} <= {path.name for path in reading}
+ for path in reading:
+ assert _withheld(str(path.relative_to(REPO_ROOT))), (
+ f"{path.relative_to(REPO_ROOT)} reads the docs, which describe every feature, or imports a blueprint-only test, "
+ "so it assumes the full repo: list it under [blueprint].blueprint_only in blueprint.toml"
+ )
+
+
+def test_the_contributing_guide_is_the_blueprint_s_own():
+ assert _withheld("CONTRIBUTING.md")
+
+
+def test_the_sync_the_contributing_guide_gives_installs_fastro():
+ """Every sync it gives keeps the root dev group, where fastro is."""
+ assert _contributing_syncs()
+ for sync in _contributing_syncs():
+ assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync
+
+
+def test_the_readme_s_quickstart_sync_installs_fastro():
+ """Every sync the README gives keeps the root dev group, and says it brings fastro in."""
+ syncs = re.findall(r"^\s*(?:\$\s+)?(uv sync\b[^#\n]*)(#.*)?$", (REPO_ROOT / "README.md").read_text(), re.M)
+
+ assert syncs
+ for sync, note in syncs:
+ assert set(sync.split()) <= SYNC_THAT_KEEPS_THE_DEV_GROUP, sync
+ assert re.search(r"\bfastro\b", note), note
+
+
+def test_the_contributing_guide_names_the_group_that_pins_fastro():
+ groups = [
+ group
+ for group, specifiers in _root_project()["dependency-groups"].items()
+ if "fastro" in {_distribution(specifier) for specifier in specifiers}
+ ]
+
+ assert len(groups) == 1, groups
+ assert f"`{groups[0]}`" in CONTRIBUTING.read_text()
+
+
+def test_the_contributing_guide_names_the_uv_that_wrote_the_lock():
+ """A uv older than the one that wrote the lock can write it back at an older revision, so the guide names that release."""
+ with (REPO_ROOT / "uv.lock").open("rb") as handle:
+ revision = tomllib.load(handle)["revision"]
+ assert revision in UV_THAT_WROTE_THE_LOCK, f"add the uv that wrote lock revision {revision}, and name it in CONTRIBUTING.md"
+
+ text = CONTRIBUTING.read_text()
+ assert re.search(rf"\brevision\s+{revision}\b", text)
+ assert set(re.findall(r"\buv\s+(\d+\.\d+\.\d+)", text)) == {UV_THAT_WROTE_THE_LOCK[revision]}
+ assert re.search(rf"uv\s+{re.escape(UV_THAT_WROTE_THE_LOCK[revision])}\s+or\s+(?:newer|later)\b", text)
+
+
+def _the_guide_s_sync_check_sentence() -> str:
+ hook = f"`{_the_sync_check_hook()['entry']}`"
+ sentences = [sentence for sentence in re.split(r"(?<=\.)\s+", CONTRIBUTING.read_text()) if hook in sentence]
+ assert len(sentences) == 1, sentences
+
+ return sentences[0]
+
+
+def test_the_contributing_guide_names_the_check_a_commit_runs():
+ """`blueprint/tests/test_fastro.py::test_plain_sync_regenerates_what_the_check_compares` proves what it does."""
+ assert _the_guide_s_sync_check_sentence()
+
+
+def test_the_contributing_guide_names_every_file_that_runs_the_check():
+ """The catalog, the selection and the pin by name, and the wiring, each one the hook runs on."""
+ sentence = _the_guide_s_sync_check_sentence()
+
+ _assert_names_the_sync_check_triggers(sentence)
+ assert "wiring" in sentence.split(f"`{_the_sync_check_hook()['entry']}`")[0]
+
+
+def test_the_check_runs_on_no_file_the_contributing_guide_leaves_out():
+ """Each trigger is a file the guide names or a wiring file, so a new one fails until the guide names it."""
+ named = _path_spans(_the_guide_s_sync_check_sentence())
+ wiring = [entry["path"] for entry in _catalog()["wiring"]]
+
+ for alternative in _alternatives(_the_sync_check_hook()["files"]):
+ assert re.sub(r"\\(.)", r"\1", alternative) in named or any(re.fullmatch(alternative, path) for path in wiring), (
+ alternative
+ )
+
+
+def test_the_contributing_guide_names_the_command_that_fixes_a_failed_check():
+ """`blueprint/tests/test_fastro.py::test_plain_sync_regenerates_what_the_check_compares` proves what it does."""
+ assert "`uv run --no-sync fastro sync`" in CONTRIBUTING.read_text()
+
+
+def _literals(module: Path) -> set[str]:
+ """Every string literal in a module, less the docstrings, which talk about files rather than
+ reach for them."""
+ tree = ast.parse(module.read_text())
+ docstrings = {
+ id(node.body[0].value)
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Module | ast.ClassDef | ast.FunctionDef | ast.AsyncFunctionDef)
+ and node.body
+ and isinstance(node.body[0], ast.Expr)
+ and isinstance(node.body[0].value, ast.Constant)
+ }
+
+ return {
+ node.value
+ for node in ast.walk(tree)
+ if isinstance(node, ast.Constant) and isinstance(node.value, str) and id(node) not in docstrings
+ }
+
+
+def test_no_test_a_project_receives_names_a_tree_it_does_not_get():
+ """A test that reaches for `docs/` or `blueprint/` is a test no project can run.
+
+ `test_baseline.py` read the migrations guide, a file a project never receives. Only the
+ subtree entries are compared, because a root file's name is ambiguous: a shipped test naming
+ `pyproject.toml` means the one under `backend/`.
+ """
+ trees = [entry for entry in _catalog()["blueprint"]["blueprint_only"] if entry.endswith("/")]
+ reaching = {}
+ for module in sorted((REPO_ROOT / "backend" / "tests").rglob("*.py")):
+ relative = module.relative_to(REPO_ROOT).as_posix()
+ if _withheld(relative):
+ continue
+
+ named = sorted(
+ text for text in _literals(module) for tree in trees if text == tree.rstrip("/") or text.startswith(tree)
+ )
+ if named:
+ reaching[relative] = named
+
+ assert reaching == {}
+
+
+def test_the_things_projects_must_not_receive_are_listed():
+ """The catalog and the docs belong to the blueprint only."""
+ listed = set(_catalog()["blueprint"]["blueprint_only"])
+
+ assert {"blueprint/", "blueprint.toml", "fastro.toml", "docs/"} <= listed
+ assert "backend/tests/unit/test_blueprint_catalog.py" in listed
+
+
+def test_the_docs_reading_tests_stay_in_the_blueprint():
+ """They read `docs/`, which projects don't get, so they would fail in one."""
+ listed = set(_catalog()["blueprint"]["blueprint_only"])
+
+ for name in ("test_docs_imports", "test_docs_recipes", "test_docs_scripts", "test_docs_wiring", "test_image_contents"):
+ assert f"backend/tests/unit/{name}.py" in listed
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["presets"]) + sorted(_catalog()["verify"]["sets"]))
+def test_every_preset_and_verify_set_is_named_the_way_the_spec_allows(name: str):
+ """Spec 1.2: a name here is lower case and may carry a hyphen, so `accounts-only` reads as one."""
+ assert SET_NAME.match(name)
+
+
+def test_every_preset_is_closed_under_what_its_features_require():
+ """A preset that names tier_limits without tiers would generate a project that can't import."""
+ for name, features in _catalog()["presets"].items():
+ assert _closed(features) == set(features), f"{name} is missing what its features require"
+
+
+def test_the_presets_name_features_this_repository_has():
+ known = set(_catalog()["features"])
+
+ for name, features in _catalog()["presets"].items():
+ assert set(features) <= known, name
+ for feature in features:
+ assert FEATURE_NAME.match(feature)
+
+
+def test_full_is_every_feature():
+ assert sorted(_catalog()["presets"]["full"]) == sorted(_catalog()["features"])
+
+
+ONE_OF_EACH = {"root_routers", "docs_guard", "email_sender", "cache_decorator", "scope_fingerprint"}
+"""The points a project may fill once: each renders as a single value with a fallback."""
+
+
+def _ref(text: str) -> tuple[str, str, str]:
+ """A spec 1.4 ref, as (module, attribute, local name)."""
+ body, _, alias = text.partition(" as ")
+ module, _, attribute = body.partition(":")
+
+ return module, attribute, alias or attribute
+
+
+def _binding(entry: str) -> tuple[str, str, str]:
+ """What a wiring file under ``src/wiring/`` binds for this ref: (module, attribute, name).
+
+ Spec 2.8: a file under the import root imports relatively, so ``src.a.b:name`` is read
+ from ``..a.b``. Anything outside it, such as ``scripts.seed``, is imported as written.
+ """
+ module, attribute, alias = _ref(entry)
+ if module.startswith("src."):
+ module = ".." + module.removeprefix("src.")
+
+ return module, attribute, alias
+
+
+def _bindings(source: str) -> set[tuple[str, str, str]]:
+ """Every (module, attribute, local name) the imports in ``source`` bind.
+
+ Read with ``ast`` rather than by matching text: names from one module share a statement,
+ and a long one wraps over several lines, and neither shape contains the single-name line a
+ substring check would look for.
+ """
+ bindings: set[tuple[str, str, str]] = set()
+ for node in ast.parse(source).body:
+ if isinstance(node, ast.ImportFrom):
+ module = "." * node.level + (node.module or "")
+ bindings.update((module, alias.name, alias.asname or alias.name) for alias in node.names)
+
+ return bindings
+
+
+def _defines(module: str, attribute: str) -> bool:
+ """Whether ``module`` defines ``attribute`` at its top level, read without importing."""
+ path = REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py")
+ if not path.exists():
+ return False
+
+ tree = ast.parse(path.read_text())
+ for node in tree.body:
+ if isinstance(node, ast.Assign) and any(
+ isinstance(target, ast.Name) and target.id == attribute for target in node.targets
+ ):
+ return True
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == attribute:
+ return True
+ if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef | ast.ClassDef) and node.name == attribute:
+ return True
+ if isinstance(node, ast.ImportFrom | ast.Import) and any(
+ (alias.asname or alias.name) == attribute for alias in node.names
+ ):
+ return True
+
+ return False
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["points"]))
+def test_every_point_is_declared_the_way_the_spec_asks(name: str):
+ """Spec 2.3: a cardinality, and one line saying what the point collects."""
+ point = _catalog()["points"][name]
+
+ assert FEATURE_NAME.match(name)
+ assert point["cardinality"] in {"many", "one"}
+ assert point["doc"].strip() == point["doc"]
+ assert "\n" not in point["doc"]
+
+
+def test_the_points_a_project_may_fill_once_are_the_ones_rendered_as_a_value():
+ """A second contribution to one of these is an error, so the set has to be exact."""
+ points = _catalog()["points"]
+ single = {name for name, point in points.items() if point["cardinality"] == "one"}
+
+ assert single == ONE_OF_EACH
+
+
+@pytest.mark.parametrize("entry", _catalog()["core"]["contributes"]["critical_readiness"])
+def test_every_core_contribution_names_something_that_exists(entry: str):
+ """Spec 1.4: the attribute has to be defined at the module's top level."""
+ module, attribute, _ = _ref(entry)
+
+ assert _defines(module, attribute), entry
+
+
+def test_the_import_reader_sees_a_name_that_shares_a_statement():
+ """Two names from one module in one statement, whose second name no line contains alone."""
+ bindings = _bindings("from ..infrastructure.auth.health import limiter_readiness, sessions_readiness\n")
+
+ assert ("..infrastructure.auth.health", "limiter_readiness", "limiter_readiness") in bindings
+ assert ("..infrastructure.auth.health", "sessions_readiness", "sessions_readiness") in bindings
+
+
+def test_the_import_reader_sees_a_name_in_a_wrapped_import():
+ """An import written over several lines, so no single line holds it."""
+ bindings = _bindings("from ..infrastructure.composition import (\n PermissionSource,\n ReadinessCheck,\n)\n")
+
+ assert ("..infrastructure.composition", "ReadinessCheck", "ReadinessCheck") in bindings
+
+
+GENERATED_BY_WIRING = "backend/src/wiring/admin.py"
+"""Written by a `[[wiring]]` entry for the admin feature, so no feature's paths declare it."""
+
+
+def _declared(feature: dict[str, Any]) -> list[tuple[str, str | None]]:
+ """A feature's declared paths, each with the condition it is kept under, if any."""
+ paths: list[tuple[str, str | None]] = [(path.rstrip("/"), None) for path in feature.get("paths", ())]
+ for block in feature.get("when", ()):
+ paths.extend((path.rstrip("/"), block["if"]) for path in block.get("paths", ()))
+
+ return paths
+
+
+def _kept_by_the_catalog(features: dict[str, Any], chosen: set[str]) -> set[str]:
+ return {
+ path
+ for name, feature in features.items()
+ if name in chosen
+ for path, condition in _declared(feature)
+ if condition is None or _true(condition, chosen)
+ }
+
+
+@pytest.mark.parametrize(
+ ("path", "kept_with"),
+ [
+ ("backend/src/modules/user/admin.py", {"accounts", "admin"}),
+ ("backend/src/modules/api_keys/tasks.py", {"accounts", "api_keys", "taskiq"}),
+ ("backend/src/modules/api_keys/service.py", {"accounts", "api_keys"}),
+ ("backend/src/infrastructure/taskiq/worker.py", {"taskiq"}),
+ ("backend/src/infrastructure/taskiq/email.py", {"accounts", "taskiq"}),
+ ("backend/tests/unit/infrastructure/taskiq/test_email.py", {"accounts", "taskiq"}),
+ ("backend/src/modules/tier/admin.py", {"tiers", "admin"}),
+ ("backend/tests/unit/modules/tier/test_admin.py", {"tiers", "admin"}),
+ ("backend/src/modules/role/admin.py", {"rbac", "admin"}),
+ ("backend/tests/unit/modules/role/test_admin.py", {"rbac", "admin"}),
+ ("backend/tests/unit/modules/user/test_admin.py", {"accounts", "admin"}),
+ ("backend/tests/unit/modules/api_keys/test_tasks.py", {"api_keys", "taskiq"}),
+ ("backend/tests/integration/api_keys_rbac/test_effective_permissions.py", {"api_keys", "rbac"}),
+ ("backend/tests/integration/api_keys_ratelimit/test_invalid_keys.py", {"api_keys", "ratelimit"}),
+ ("backend/tests/integration/api_keys_tiers/test_reading_another_account.py", {"api_keys", "tier_limits"}),
+ ("backend/tests/unit/infrastructure/cache/test_scoped_callers.py", {"cache", "accounts"}),
+ ("backend/tests/integration/tier_limits/test_cached_listing.py", {"tier_limits", "cache"}),
+ ],
+)
+def test_a_file_is_kept_exactly_where_its_features_are(path: str, kept_with: set[str]):
+ """A file one feature brings into another's package is kept only when every feature it
+ needs is selected, and leaves when any one of them is missing."""
+ features = _catalog()["features"]
+ declared = {declared for feature in features.values() for declared, _ in _declared(feature)}
+
+ for chosen in _selections():
+ kept_paths = _kept_by_the_catalog(features, chosen)
+ kept = _under(path, kept_paths) and not _under(path, _removed_for(features, chosen))
+ assert kept is (kept_with <= chosen), sorted(chosen)
+ if path in declared:
+ assert (path in kept_paths) is (kept_with <= chosen), sorted(chosen)
+
+
+def _local_names(point: str, chosen: set[str]) -> list[str]:
+ return [_ref(entry["ref"])[2] for entry in _contributed(_catalog(), point, chosen)]
+
+
+def test_a_project_with_a_worker_queues_its_mail_and_one_without_hands_it_over():
+ """No selection waits for a mail server: the fallback hands the delivery over."""
+ fallback = next(slot for entry in _entries() for slot in entry["slots"] if slot.get("point") == "email_sender")
+
+ assert fallback["fallback"] == "HandingOverSender(build_sender())"
+ for chosen in _selections():
+ expected = ["queued_sender"] if {"accounts", "taskiq"} <= chosen else []
+ assert _local_names("email_sender", chosen) == expected, sorted(chosen)
+
+
+def test_a_project_with_accounts_wires_the_scope_fingerprint_and_one_without_wires_none():
+ """Accounts contributes it, and the cache imports nothing of accounts to read it."""
+ fallback = next(slot for entry in _entries() for slot in entry["slots"] if slot.get("point") == "scope_fingerprint")
+
+ assert fallback["fallback"] == "None"
+ for chosen in _selections():
+ expected = ["scope_fingerprint"] if "accounts" in chosen else []
+ assert _local_names("scope_fingerprint", chosen) == expected, sorted(chosen)
+
+
+def test_a_project_with_tiers_gives_a_new_account_the_default_tier_and_one_without_sets_nothing():
+ for chosen in _selections():
+ expected = ["default_tier"] if "tiers" in chosen else []
+ assert _local_names("new_account_fields", chosen) == expected, sorted(chosen)
+
+
+def test_a_project_drains_what_it_handed_over_with_the_worker_or_on_its_own():
+ """Accounts hands its mail over, and drains it once: in the worker's lifecycle where there is
+ one, and in the handover's own where there isn't."""
+ for chosen in _selections():
+ names = _local_names("lifecycles", chosen)
+
+ assert ("taskiq_lifecycle" in names) is ("taskiq" in chosen), sorted(chosen)
+ assert ("handover_lifecycle" in names) is ("accounts" in chosen and "taskiq" not in chosen), sorted(chosen)
+
+
+def _closed(chosen: Iterable[str]) -> set[str]:
+ """A selection with everything its features require, and what that requires in turn."""
+ features = _catalog()["features"]
+ selection = set(chosen)
+ while missing := {required for name in selection for required in features[name].get("requires", ())} - selection:
+ selection |= missing
+
+ return selection
+
+
+def _selections() -> list[set[str]]:
+ """Every selection a project could carry: each subset of the features, closed under requires."""
+ closed: list[set[str]] = []
+ for size in range(len(_catalog()["features"]) + 1):
+ for combination in itertools.combinations(_catalog()["features"], size):
+ selection = _closed(combination)
+ if selection not in closed:
+ closed.append(selection)
+
+ return closed
+
+
+def test_a_project_can_carry_164_selections():
+ """The rules below that run over every selection have that many to run over."""
+ assert len(_selections()) == 164
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["features"]))
+def test_every_feature_is_declared_the_way_the_spec_asks(name: str):
+ """Spec 2.4: a one-line summary, and the heading the checklist groups it under."""
+ feature = _catalog()["features"][name]
+
+ assert FEATURE_NAME.match(name)
+ assert feature["summary"].strip() == feature["summary"]
+ assert "\n" not in feature["summary"]
+ assert feature["group"] in {"Accounts", "Operations"}
+
+
+@pytest.mark.parametrize(
+ ("name", "condition"),
+ sorted((name, block["if"]) for name, feature in _catalog()["features"].items() for block in feature.get("when", ())),
+)
+def test_every_condition_names_a_feature_this_repository_has(name: str, condition: str):
+ """Spec 1.3: an unknown name is an error rather than something that reads as false."""
+ assert condition in _catalog()["features"]
+ assert condition != name
+
+
+@pytest.mark.parametrize(
+ "entry",
+ sorted(
+ {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)},
+ ),
+)
+def test_every_feature_path_is_one_this_repo_has(entry: str):
+ """A path that no longer exists leaves a file in projects that nobody meant to keep."""
+ assert not entry.startswith("/")
+ assert ".." not in Path(entry).parts
+ assert (REPO_ROOT / entry).exists()
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["features"]))
+def test_a_directory_is_spelled_as_a_subtree_and_a_file_is_not(name: str):
+ """Spec 1.1: `src/modules/user` without the slash would name one file nobody has."""
+ for path in _catalog()["features"][name].get("paths", ()):
+ assert path.endswith("/") == (REPO_ROOT / path).is_dir(), path
+
+ for block in _catalog()["features"][name].get("when", ()):
+ for path in block.get("paths", ()):
+ assert path.endswith("/") == (REPO_ROOT / path).is_dir(), path
+
+
+def test_no_path_is_declared_twice():
+ """Spec 1.1: two declarations of the identical path are 'owned twice'."""
+ declared = [path for feature in _catalog()["features"].values() for path, _ in _declared(feature)]
+
+ assert sorted(declared) == sorted(set(declared))
+
+
+def test_the_generated_wiring_file_belongs_to_no_feature():
+ """It is written by `[[wiring]]`, which leaves it out of a project rather than deleting it."""
+ declared = {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)}
+
+ assert GENERATED_BY_WIRING in [entry["path"] for entry in _entries()]
+ assert GENERATED_BY_WIRING not in declared
+
+
+def test_the_app_the_verification_imports_is_this_project_s_own():
+ """Spec 2.2: a dotted module whose first part is `import_root`, and whose file this repository
+ has. Without it `blueprint verify` skips the app-import check, which is the one that catches a
+ feature removal that left something importing what went."""
+ blueprint = _catalog()["blueprint"]
+ module = _catalog()["verify"]["app"]
+ path = REPO_ROOT / blueprint["python_root"] / Path(*module.split(".")).with_suffix(".py")
+
+ assert module.split(".")[0] == blueprint["import_root"]
+ assert path.is_file(), module
+ assert _defines(module, "app"), "the check imports the module for its app"
+
+
+def test_the_toolchain_environment_is_what_the_app_needs_to_import():
+ """Spec 2.12: names and string values only. They are test values for checking a project
+ rather than secrets: a memory session store, a memory limiter, the local environment, and a
+ key that exists only so the settings validate.
+ """
+ declared = _catalog()["checks"]["toolchain"]["env"]
+
+ assert set(declared) == {"ENVIRONMENT", "SECRET_KEY", "SESSION_BACKEND", "RATE_LIMITER_BACKEND"}
+ for name, value in declared.items():
+ assert ENV_VAR.match(name), name
+ assert isinstance(value, str), name
+
+ assert len(declared["SECRET_KEY"]) >= 32, "the settings refuse a shorter one"
+ assert declared["SECRET_KEY"] not in ENV_EXAMPLE.read_text(), "not the example's placeholder"
+
+
+def _true(condition: str, chosen: set[str]) -> bool:
+ """Whether a spec 1.3 condition holds for this selection."""
+ tokens = re.findall(r"\(|\)|[^\s()]+", condition)
+ position = 0
+
+ def expression() -> bool:
+ value = conjunction()
+ nonlocal position
+ while position < len(tokens) and tokens[position] == "or":
+ position += 1
+ value = conjunction() or value
+
+ return value
+
+ def conjunction() -> bool:
+ value = negation()
+ nonlocal position
+ while position < len(tokens) and tokens[position] == "and":
+ position += 1
+ value = negation() and value
+
+ return value
+
+ def negation() -> bool:
+ nonlocal position
+ if tokens[position] == "not":
+ position += 1
+
+ return not negation()
+
+ return atom()
+
+ def atom() -> bool:
+ nonlocal position
+ token = tokens[position]
+ position += 1
+ if token == "(":
+ value = expression()
+ assert tokens[position] == ")", condition
+ position += 1
+
+ return value
+
+ if "=" in token:
+ raise NotImplementedError(f"{token!r} names an option; this test only selects features.")
+
+ return token in chosen
+
+ held = expression()
+ assert position == len(tokens), condition
+
+ return held
+
+
+def _tables(entries: Any) -> list[dict[str, Any]]:
+ """Spec 1.5: a contribution is a bare ref or a table, and reads the same either way."""
+ return [{"ref": entry} if isinstance(entry, str) else dict(entry) for entry in entries]
+
+
+def _contributed(catalog: dict[str, Any], point: str, chosen: set[str]) -> list[dict[str, Any]]:
+ """What reaches a point for this selection, in the order spec 2.7 sorts it."""
+ collected = [(index, -1, 0, table) for index, table in enumerate(_tables(catalog["core"]["contributes"].get(point, ())))]
+
+ for index, (name, feature) in enumerate(catalog["features"].items()):
+ if name not in chosen:
+ continue
+
+ entries = list(feature.get("contributes", {}).get(point, ()))
+ for block in feature.get("when", ()):
+ if _true(block["if"], chosen):
+ entries.extend(block.get("contributes", {}).get(point, ()))
+
+ for position, table in enumerate(_tables(entries)):
+ if "if" in table and not _true(table["if"], chosen):
+ continue
+
+ collected.append((table.get("order", (index + 1) * 100 + position), index, position, table))
+
+ return [table for *_, table in sorted(collected, key=lambda entry: entry[:3])]
+
+
+def _defined(source: str, name: str) -> ast.AST | None:
+ """The value assigned to ``name``, or the class defined under it."""
+ for node in ast.parse(source).body:
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == name:
+ return node.value
+ if isinstance(node, ast.Assign) and any(isinstance(t, ast.Name) and t.id == name for t in node.targets):
+ return node.value
+ if isinstance(node, ast.ClassDef) and node.name == name:
+ return node
+
+ return None
+
+
+def test_every_declared_point_is_contributed_to_or_filled_by_core():
+ """A point no feature and no core contribution reaches would render empty for every project."""
+ catalog = _catalog()
+ reached = set(catalog["core"]["contributes"])
+ for feature in catalog["features"].values():
+ reached.update(feature.get("contributes", {}))
+ for block in feature.get("when", ()):
+ reached.update(block.get("contributes", {}))
+
+ assert set(catalog["points"]) == reached
+
+
+def test_every_contribution_names_something_that_exists():
+ """Spec 1.4: a ref's attribute has to be defined at the top level of its module."""
+ catalog = _catalog()
+ everything = set(catalog["features"])
+
+ for point in catalog["points"]:
+ for entry in _contributed(catalog, point, everything):
+ if "value" in entry:
+ continue
+
+ module, attribute, _ = _ref(entry["ref"])
+ assert _defines(module, attribute), entry
+
+
+def test_a_point_a_project_fills_once_never_receives_two_contributions():
+ """Spec 2.6: a second contribution to a `value` slot is an error rather than a last-wins."""
+ catalog = _catalog()
+ single = {name for name, point in catalog["points"].items() if point["cardinality"] == "one"}
+
+ for chosen in _selections():
+ for point in single:
+ assert len(_contributed(catalog, point, chosen)) <= 1, (point, sorted(chosen))
+
+
+def test_a_transport_that_is_constructed_says_so():
+ """Spec 1.5: `call` is what renders `APIKeyTransport()` rather than the class itself."""
+ catalog = _catalog()
+ everything = set(catalog["features"])
+ entry = _contributed(catalog, "extra_transports", everything)[0]
+ rendered = _defined(_committed("backend/src/wiring/transports.py"), "EXTRA_TRANSPORTS")
+
+ assert entry["call"] is True
+ assert isinstance(rendered, ast.Tuple) and isinstance(rendered.elts[0], ast.Call)
+
+
+@pytest.mark.parametrize(
+ "condition",
+ sorted(
+ {block["if"] for feature in _catalog()["features"].values() for block in feature.get("when", ())}
+ | {
+ entry["if"]
+ for feature in _catalog()["features"].values()
+ for entries in feature.get("contributes", {}).values()
+ for entry in _tables(entries)
+ if "if" in entry
+ }
+ ),
+)
+def test_every_condition_is_one_this_test_can_evaluate(condition: str):
+ """An option atom would need a selection to carry option values, which this test doesn't."""
+ assert _true(condition, set(_catalog()["features"])) in {True, False}
+
+
+@pytest.mark.parametrize(
+ ("feature", "option"),
+ sorted((name, option) for name, feature in _catalog()["features"].items() for option in feature.get("options", {})),
+)
+def test_every_option_is_declared_the_way_the_spec_asks(feature: str, option: str):
+ """Spec 2.5: named choices, listed once, with the default among them."""
+ declared = _catalog()["features"][feature]["options"][option]
+
+ assert FEATURE_NAME.match(option)
+ assert declared["choices"] == sorted(set(declared["choices"]), key=declared["choices"].index)
+ assert all(choice and not re.search(r"[\s()=]", choice) for choice in declared["choices"])
+ assert declared["default"] in declared["choices"]
+ assert all(re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name) for name in declared.get("env", {}))
+
+
+EXTRA_SERVICES = {
+ ("cache", "backend"): {"memcached": ["memcached"]},
+ ("taskiq", "broker"): {"rabbitmq": ["rabbitmq"]},
+}
+"""The service each choice needs on top of what a project already runs, which is redis."""
+
+
+@pytest.mark.parametrize(("feature", "option"), sorted(EXTRA_SERVICES))
+def test_every_extra_service_an_option_asks_for_belongs_to_one_of_its_choices(feature: str, option: str):
+ """Spec 2.5: the key is the value that needs the service, so a typo would ask for nothing."""
+ declared = _catalog()["features"][feature]["options"][option]
+ services = declared.get("services", {})
+
+ assert set(services) <= set(declared["choices"])
+ assert services == EXTRA_SERVICES[(feature, option)]
+ assert declared["default"] not in services
+
+
+OPTION_SOURCES = {
+ ("cache", "backend"): ("src/infrastructure/cache/initialize.py", "CacheBackend"),
+ ("taskiq", "broker"): ("src/infrastructure/taskiq/settings.py", "TaskiqBrokerType"),
+}
+"""Where each option's choices are acted on, and the enum whose members name them."""
+
+
+@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES))
+def test_every_option_offers_the_values_its_feature_acts_on(feature: str, option: str):
+ """`CacheBackend` also names an in-memory backend that nothing starts, so it isn't offered."""
+ module, enum = OPTION_SOURCES[(feature, option)]
+ acted_on = re.findall(rf"{enum}\.([A-Z_]+)\.value", (REPO_ROOT / "backend" / module).read_text())
+
+ assert sorted(set(acted_on)) == sorted(
+ choice.upper() for choice in _catalog()["features"][feature]["options"][option]["choices"]
+ )
+
+
+ENV_EXAMPLE = REPO_ROOT / "backend" / ".env.example"
+
+NOT_A_SETTING = {
+ "FORWARDED_ALLOW_IPS": "core",
+}
+"""Variables the example sets that no settings field takes: `FORWARDED_ALLOW_IPS` is read by
+uvicorn and written by the deploy templates, never by the app."""
+
+
+def _alias_names(node: ast.AnnAssign) -> set[str]:
+ """The names a field accepts besides its own, which is how one feature's setting reads
+ another's: `SESSION_REDIS_HOST` takes `CACHE_REDIS_HOST` when nothing sets it."""
+ names: set[str] = set()
+ for given in getattr(node.value, "keywords", ()):
+ if given.arg != "validation_alias":
+ continue
+
+ if isinstance(given.value, ast.Constant) and isinstance(given.value.value, str):
+ names.add(given.value.value)
+ else:
+ names.update(
+ argument.value
+ for argument in getattr(given.value, "args", ())
+ if isinstance(argument, ast.Constant) and isinstance(argument.value, str)
+ )
+
+ return names
+
+
+@functools.cache
+def _settings_fields() -> dict[str, frozenset[str]]:
+ """Which parts of the project take each setting: `core`, or the features whose contributed
+ settings classes declare it, counting the names a field accepts as aliases as well."""
+ modules: dict[str, list[Path]] = {"core": [REPO_ROOT / "backend/src/infrastructure/config/base.py"]}
+ for name, feature in _catalog()["features"].items():
+ for entry in feature.get("contributes", {}).get("settings", ()):
+ module, _, _ = _ref(entry if isinstance(entry, str) else entry["ref"])
+ modules.setdefault(name, []).append(REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py"))
+
+ declared: dict[str, set[str]] = {}
+ for owner, paths in modules.items():
+ for path in paths:
+ for node in ast.walk(ast.parse(path.read_text())):
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id.isupper():
+ for name in {node.target.id} | _alias_names(node):
+ declared.setdefault(name, set()).add(owner)
+
+ return {name: frozenset(owners) for name, owners in declared.items()}
+
+
+@functools.cache
+def _env_comments() -> dict[str, tuple[str, ...]]:
+ """Each section's comment lines, less its markers, which name variables as data."""
+ lines = ENV_EXAMPLE.read_text().splitlines()
+ rule = re.compile(r"^# ={10,}$")
+ headers = [
+ index
+ for index, line in enumerate(lines)
+ if rule.match(line) and index + 2 < len(lines) and rule.match(lines[index + 2])
+ ]
+
+ comments = {}
+ for position, start in enumerate(headers):
+ end = headers[position + 1] if position + 1 < len(headers) else len(lines)
+ comments[lines[start + 1].lstrip("# ").strip()] = tuple(
+ line for line in lines[start + 3 : end] if line.lstrip().startswith("#") and "@fastro" not in line
+ )
+
+ return comments
+
+
+@functools.cache
+def _env_sections() -> tuple[tuple[str, str | None, tuple[str, ...]], ...]:
+ """Each section of the example: its title, the marker directly below its header if it carries
+ one, and the variables it sets, including the ones it ships commented out, since a reader
+ uncomments them where they sit."""
+ lines = ENV_EXAMPLE.read_text().splitlines()
+ rule = re.compile(r"^# ={10,}$")
+ headers = [
+ index
+ for index, line in enumerate(lines)
+ if rule.match(line) and index + 2 < len(lines) and rule.match(lines[index + 2])
+ ]
+
+ sections = []
+ for position, start in enumerate(headers):
+ end = headers[position + 1] if position + 1 < len(headers) else len(lines)
+ variables = tuple(
+ found.group(1) for line in lines[start + 3 : end] if (found := re.match(r"^#?\s*([A-Z][A-Z0-9_]*)=", line))
+ )
+ marker = lines[start + 3] if start + 3 < end and lines[start + 3].startswith("# @fastro ") else None
+ sections.append((lines[start + 1].lstrip("# ").strip(), marker, variables))
+
+ return tuple(sections)
+
+
+def _owner_of(variable: str) -> frozenset[str]:
+ fields = _settings_fields()
+ if variable in fields:
+ return fields[variable]
+
+ assert variable in NOT_A_SETTING, f"{variable} is in the example and nothing declares it"
+
+ return frozenset({NOT_A_SETTING[variable]})
+
+
+def _owners_of(title: str) -> set[str]:
+ """Every part of the project that takes any of this section's variables."""
+ variables = next(found for name, _, found in _env_sections() if name == title)
+
+ return {owner for variable in variables for owner in _owner_of(variable)}
+
+
+def _common_owners_of(title: str) -> set[str]:
+ """The parts that take *every* variable in the section, which is what a marker can name."""
+ variables = next(found for name, _, found in _env_sections() if name == title)
+
+ return set.intersection(*(set(_owner_of(variable)) for variable in variables)) if variables else {"core"}
+
+
+def _marked_feature(title: str) -> str:
+ marker = next(found for name, found, _ in _env_sections() if name == title)
+
+ return marker.removeprefix("# @fastro if=") if marker else "core"
+
+
+@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()])
+def test_every_section_of_the_example_belongs_to_one_feature_or_to_the_core(title: str):
+ """Spec 6.1 keeps or drops a section whole, so a section can hold one feature's variables or
+ the core's, never both: dropping a mixed one would take `SECRET_KEY` from every project
+ without accounts.
+ """
+ assert _common_owners_of(title), sorted(_owners_of(title))
+
+
+@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()])
+def test_every_section_a_feature_owns_says_which_feature_keeps_it(title: str):
+ """Spec 6.1: the marker is a line of its own directly below the header's closing rule, and
+ the section goes when its condition is false. A core section carries none, because a project
+ keeps it whatever it selected.
+ """
+ common = _common_owners_of(title)
+ marker = next(found for name, found, _ in _env_sections() if name == title)
+
+ if common == {"core"}:
+ assert marker is None, title
+
+ return
+
+ assert marker is not None, sorted(common)
+ assert marker.removeprefix("# @fastro if=") in common - {"core"}
+
+
+@pytest.mark.parametrize("title", [title for title, _, _ in _env_sections()])
+def test_no_section_sends_a_reader_to_a_variable_another_feature_owns(title: str):
+ """A kept section has to read on its own: a project that selected one feature and not another
+ would otherwise be told to set something it hasn't got, with nowhere to set it.
+
+ Only variables this section's own feature declares, or the core's, may be named. The
+ production checklist is the reason this exists: it used to name eight of them.
+ """
+ mine = {_marked_feature(title)}
+ named = {
+ word
+ for line in _env_comments()[title]
+ for word in re.findall(r"\b[A-Z][A-Z0-9_]{2,}\b", line)
+ if word in _settings_fields() or word in NOT_A_SETTING
+ }
+
+ assert {word: sorted(_owner_of(word)) for word in named if not _owner_of(word) & (mine | {"core"})} == {}
+
+
+@functools.cache
+def _fields_falling_back_to_another_feature() -> dict[str, frozenset[str]]:
+ """Fields that read another feature's variable when nothing sets their own, with the features
+ whose names they borrow. `SESSION_REDIS_HOST` takes `CACHE_REDIS_HOST`, so a project with
+ accounts and no cache has nothing in its example pointing sessions at Redis."""
+ fields: dict[str, set[str]] = {}
+ for name, feature in _catalog()["features"].items():
+ for entry in feature.get("contributes", {}).get("settings", ()):
+ module, _, _ = _ref(entry if isinstance(entry, str) else entry["ref"])
+ path = REPO_ROOT / "backend" / Path(*module.split(".")).with_suffix(".py")
+ for node in ast.walk(ast.parse(path.read_text())):
+ if not isinstance(node, ast.AnnAssign) or not isinstance(node.target, ast.Name):
+ continue
+
+ borrowed = {
+ owner for alias in _alias_names(node) - {node.target.id} for owner in _owner_of(alias) if owner != name
+ }
+ if borrowed:
+ fields.setdefault(node.target.id, set()).update(borrowed)
+
+ return {name: frozenset(owners) for name, owners in fields.items()}
+
+
+@pytest.mark.parametrize("field", sorted(_fields_falling_back_to_another_feature()))
+def test_every_setting_that_borrows_another_features_variable_is_named_in_its_own_section(field: str):
+ """Otherwise the only line that sets it is the other feature's, and a project without that
+ feature is left with the default: for the session Redis, `localhost`, which is not the
+ service name the compose stack publishes.
+
+ The line may be commented out. It is there to be found and uncommented, and a live one would
+ beat the borrowed value rather than fall back to it.
+ """
+ owners = _owner_of(field) - _fields_falling_back_to_another_feature()[field]
+ sections = {title: variables for title, _, variables in _env_sections()}
+ theirs = [title for title in sections if _marked_feature(title) in owners]
+
+ assert theirs, sorted(owners)
+ assert any(field in sections[title] for title in theirs), (
+ f"{field} is set only by {sorted(_fields_falling_back_to_another_feature()[field])}"
+ )
+
+
+def test_the_comments_are_read_the_way_they_are_written():
+ """The reading above: comments that stopped being found would leave it nothing to object to."""
+ comments = _env_comments()
+
+ assert any("SECRET_KEY" in line for line in comments["Production Security Checklist"])
+ assert any("CACHE_REDIS_DB" in line for line in comments["Cache Configuration"])
+ assert not any("@fastro" in line for section in comments.values() for line in section)
+
+
+def test_no_marker_sits_anywhere_but_under_a_header():
+ """A marker further down would speak for the lines after it, which spec 6.1 doesn't read:
+ the section is what the condition keeps or drops."""
+ lines = ENV_EXAMPLE.read_text().splitlines()
+ marked = [line for line in lines if line.startswith("# @fastro if=")]
+ under_headers = [marker for _, marker, _ in _env_sections() if marker is not None]
+
+ assert marked == under_headers
+ assert all(_true(marker.removeprefix("# @fastro if="), set(_catalog()["features"])) for marker in marked)
+
+
+ADMIN_GUIDE = REPO_ROOT / "docs" / "user-guide" / "admin-panel" / "configuration.md"
+
+QUOTED_EXAMPLE = "The default `.env.example`"
+"""Where that guide quotes the example, which is the one place the docs reproduce its values."""
+
+
+def test_the_guide_quotes_the_example_as_it_ships():
+ """A quoted value that drifts from the file is a reader setting up a panel that stays dark, or
+ serving one they thought was off: the example keeps the admin panel off, as the setting's own
+ default has since 0.20.0."""
+ guide = ADMIN_GUIDE.read_text()
+ quoted = guide[guide.index(QUOTED_EXAMPLE) :].split("```")[1].removeprefix("env\n")
+ shipped = dict(line.split("=", 1) for line in ENV_EXAMPLE.read_text().splitlines() if re.match(r"^[A-Z][A-Z0-9_]*=", line))
+
+ assert "ADMIN_ENABLED=false" in quoted, "the example ships the panel off"
+ for line in quoted.splitlines():
+ name, _, value = line.partition("=")
+ assert shipped[name] == value, name
+
+
+FIRST_RUN = REPO_ROOT / "docs" / "getting-started"
+
+NEARBY_LINES = 2
+"""How far from a mention of the panel the flag may be and still be read as part of the same claim."""
+
+
+@pytest.mark.parametrize("page", sorted(path.name for path in FIRST_RUN.glob("*.md")))
+def test_no_first_run_page_offers_the_admin_panel_without_saying_what_turns_it_on(page: str):
+ """A new reader follows these pages in order, and `/admin` answers 404 until the flag is set
+ and both credentials are there. A page that lists it among the things that now work sends
+ that reader to look for a bug of their own."""
+ lines = (FIRST_RUN / page).read_text().splitlines()
+ unexplained = [
+ line
+ for index, line in enumerate(lines)
+ if "/admin" in line and "ADMIN_ENABLED" not in "\n".join(lines[max(0, index - NEARBY_LINES) : index + NEARBY_LINES + 1])
+ ]
+
+ assert unexplained == []
+
+
+def test_the_example_is_read_the_way_it_is_written():
+ """The reading itself: a parse that found no sections, or missed the commented-out lines,
+ would leave the rule above with nothing to object to."""
+ sections = {title: variables for title, _, variables in _env_sections()}
+
+ assert len(sections) >= 15
+ assert "CREATE_TABLES_ON_STARTUP" in sections["Database Configuration"], "a line shipped commented out"
+ assert _owner_of("SECRET_KEY") == frozenset({"core"})
+ assert _owner_of("CACHE_BACKEND") == frozenset({"cache"})
+ assert _owner_of("SESSION_REDIS_URL") == frozenset({"accounts"})
+ assert _owner_of("CACHE_REDIS_HOST") == frozenset({"accounts", "cache"}), "the session host takes it too"
+
+
+@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES))
+def test_every_option_defaults_to_what_the_project_already_ships(feature: str, option: str):
+ """The question `fastro new` asks pre-picks the value a clone of this repo runs with."""
+ declared = _catalog()["features"][feature]["options"][option]
+ example = (REPO_ROOT / "backend" / ".env.example").read_text()
+
+ for variable in declared["env"]:
+ assert f"\n{variable}={declared['default']}\n" in example
+
+
+@pytest.mark.parametrize(("feature", "option"), sorted(OPTION_SOURCES))
+def test_every_option_marks_the_line_it_rewrites(feature: str, option: str):
+ """Spec 6.1: the marker sits on its own line directly above the VAR line it speaks for."""
+ declared = _catalog()["features"][feature]["options"][option]
+ lines = (REPO_ROOT / "backend" / ".env.example").read_text().splitlines()
+
+ for variable in declared["env"]:
+ marked = [index for index, line in enumerate(lines) if line == f"# @fastro option={feature}.{option}"]
+ assert len(marked) == 1
+ assert lines[marked[0] + 1].startswith(f"{variable}=")
+
+
+SLOT_KINDS = {"tuple", "list", "class", "value", "reexport", "raw", "data"}
+"""Spec 2.6. A kind the engine doesn't know would be a slot nothing renders."""
+
+
+def _entries() -> list[dict[str, Any]]:
+ return list(_catalog()["wiring"])
+
+
+def _committed(path: str) -> str:
+ return (REPO_ROOT / path).read_text()
+
+
+def _annotated(source: str, name: str) -> str | None:
+ """How the committed file spells this name's annotation."""
+ for node in ast.parse(source).body:
+ if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name) and node.target.id == name:
+ return ast.unparse(node.annotation)
+
+ return None
+
+
+@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()])
+def test_every_wiring_file_is_under_the_python_root_and_is_a_file(path: str):
+ """Spec 2.6: a generated Python file lives under `python_root`, and names one file."""
+ blueprint = _catalog()["blueprint"]
+
+ assert path.startswith(blueprint["python_root"] + "/")
+ assert not path.endswith("/")
+ assert (REPO_ROOT / path).is_file()
+
+
+@pytest.mark.parametrize(
+ ("path", "name"),
+ [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if "annotation" in slot],
+)
+def test_every_annotated_slot_is_annotated_the_way_the_file_annotates_it(path: str, name: str):
+ """`NAME: ANNOTATION` is what mypy and an IDE read, so the catalog has to spell it the same."""
+ slot = next(slot for slot in next(e for e in _entries() if e["path"] == path)["slots"] if slot.get("name") == name)
+
+ assert _annotated(_committed(path), name) == slot["annotation"]
+
+
+@pytest.mark.parametrize(
+ ("path", "name"),
+ [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if "name" in slot],
+)
+def test_every_slot_fills_a_name_the_file_defines(path: str, name: str):
+ assert _defined(_committed(path), name) is not None or name in {alias for _, _, alias in _bindings(_committed(path))}
+
+
+def test_every_declared_point_is_filled_by_exactly_one_slot():
+ """One direction: a point no slot collects is a point whose contributions reach nothing."""
+ filled = [slot["point"] for entry in _entries() for slot in entry["slots"] if "point" in slot]
+
+ assert sorted(filled) == sorted(_catalog()["points"])
+
+
+def test_every_slot_collects_a_point_the_catalog_declares():
+ """The other direction: a slot naming an undeclared point would collect nothing for ever."""
+ declared = set(_catalog()["points"])
+
+ for entry in _entries():
+ for slot in entry["slots"]:
+ if slot["kind"] == "raw":
+ assert "point" not in slot and "name" not in slot
+ continue
+
+ assert slot["point"] in declared, slot
+
+
+@pytest.mark.parametrize(
+ ("path", "kind"),
+ [(entry["path"], slot["kind"]) for entry in _entries() for slot in entry["slots"]],
+)
+def test_every_slot_is_a_kind_the_spec_has(path: str, kind: str):
+ assert kind in SLOT_KINDS
+
+
+def test_every_point_a_project_fills_once_is_rendered_as_one_value():
+ """Spec 2.6: `value`, `class` and `reexport` render one, and each needs its fallback."""
+ cardinality = {name: point["cardinality"] for name, point in _catalog()["points"].items()}
+
+ for entry in _entries():
+ for slot in entry["slots"]:
+ if slot["kind"] in {"value", "reexport"}:
+ assert cardinality[slot["point"]] == "one", slot
+ assert "fallback" in slot, slot
+ if slot["kind"] in {"tuple", "list"}:
+ assert cardinality[slot["point"]] == "many", slot
+
+
+def test_the_file_a_feature_brings_with_it_is_generated_only_for_that_feature():
+ """FR003: without admin the file is absent from the project, not emptied."""
+ admin = next(entry for entry in _entries() if entry["path"].endswith("wiring/admin.py"))
+
+ assert admin["if"] == "admin"
+ assert [entry.get("if") for entry in _entries()].count(None) == 13
+
+
+def test_the_statement_a_raw_slot_carries_is_in_the_file():
+ """`settings = Settings()` is what the rest of the project imports, and no point fills it."""
+ raw = [slot for entry in _entries() for slot in entry["slots"] if slot["kind"] == "raw"]
+ committed = _committed("backend/src/wiring/settings.py")
+
+ assert [slot["code"] for slot in raw] == ["settings = Settings()"]
+ assert "settings = Settings()" in committed
+
+
+def _declared_bindings(catalog: dict[str, Any], entry: dict[str, Any], chosen: set[str]) -> set[tuple[str, str, str]]:
+ """Every name the catalog says this file binds: its own imports, and what reaches its slots."""
+ bindings: set[tuple[str, str, str]] = set()
+ for line in entry.get("imports", ()):
+ module, _, names = line.removeprefix("from ").partition(" import ")
+ bindings.update((module, name, name) for name in names.split(", "))
+
+ for slot in entry["slots"]:
+ if slot["kind"] == "raw":
+ continue
+
+ contributed = _contributed(catalog, slot["point"], chosen)
+ if contributed and not slot.get("literal"):
+ bindings.update(_binding(contribution["ref"]) for contribution in contributed if "ref" in contribution)
+ for line in slot.get("item_imports", ()):
+ module, _, names = line.removeprefix("from ").partition(" import ")
+ bindings.update((module, name, name) for name in names.split(", "))
+
+ if not contributed:
+ for line in slot.get("fallback_imports", ()):
+ module, _, names = line.removeprefix("from ").partition(" import ")
+ bindings.update((module, name, name) for name in names.split(", "))
+ if ":" in slot.get("fallback", ""):
+ bindings.add(_binding(slot["fallback"]))
+
+ bindings.update(_binding(ref) for ref in slot.get("append", ()))
+
+ return bindings
+
+
+@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()])
+def test_the_catalog_accounts_for_every_name_the_file_imports(path: str):
+ """An import the entry forgets is a NameError in a project nobody has built yet.
+
+ The committed files carry every feature, so with everything selected the names the
+ catalog brings and the names the file binds are the same set, both ways.
+ """
+ catalog = _catalog()
+ entry = next(entry for entry in _entries() if entry["path"] == path)
+
+ assert _declared_bindings(catalog, entry, set(catalog["features"])) == _bindings(_committed(path))
+
+
+def _refs_of(slot: dict[str, Any]) -> list[str]:
+ """The refs a slot names itself: its fallback, and the bases it always appends."""
+ refs = list(slot.get("append", ()))
+ if ":" in slot.get("fallback", ""):
+ refs.append(slot["fallback"])
+
+ return refs
+
+
+def test_every_ref_a_slot_names_itself_exists():
+ """A fallback is what a project without the feature gets, so it has to be importable there."""
+ named = [(entry["path"], ref) for entry in _entries() for slot in entry["slots"] for ref in _refs_of(slot)]
+
+ assert sorted(ref for _, ref in named) == [
+ "pydantic:BaseModel",
+ "src.infrastructure.config.base:CoreSettings",
+ "src.infrastructure.uncached:cached",
+ ]
+
+ for path, ref in named:
+ module, attribute, _ = _ref(ref)
+ if module.startswith("src."):
+ assert _defines(module, attribute), (path, ref)
+ else:
+ assert hasattr(importlib.import_module(module), attribute), (path, ref)
+
+
+def test_every_import_a_fallback_needs_names_something_that_exists():
+ """Spec 2.6: these lines are emitted only when the fallback is used, so nothing else checks them."""
+ lines = [
+ (entry["path"], line) for entry in _entries() for slot in entry["slots"] for line in slot.get("fallback_imports", ())
+ ]
+
+ assert len(lines) == 2
+
+ for path, line in lines:
+ module, _, name = line.removeprefix("from ").partition(" import ")
+ assert path.startswith("backend/src/wiring/"), path
+ assert _defines("src." + module.lstrip("."), name), line
+
+
+def test_the_header_every_generated_file_carries_is_fastros_own():
+ """Spec 2.12, verbatim: a project's wiring says what wrote it and how to change it."""
+ assert _catalog()["wiring_defaults"]["header"] == (
+ "Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change\n"
+ "fastro.toml (or [app] in it, for your own code) and run `fastro sync`."
+ )
+
+
+def test_the_header_fits_the_line_length_of_the_files_it_goes_into():
+ """Spec 2.8: each line is at most 100 characters, so a docstring passes E501 at 128."""
+ for line in _catalog()["wiring_defaults"]["header"].splitlines():
+ assert len(line) <= 100, line
+
+
+HAND_WRITTEN = "backend/src/wiring/__init__.py"
+"""The one module beside the generated ones that a person writes, and fastro never rewrites."""
+
+
+def _docstring(source: str) -> str | None:
+ """The module docstring as it is written, rather than as ``ast`` tidies it up."""
+ body = ast.parse(source).body
+ if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
+ return str(body[0].value.value)
+
+ return None
+
+
+@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()])
+def test_every_generated_file_carries_its_doc_and_then_the_header(path: str):
+ """Spec 2.8: the entry's `doc`, a blank line, then the header, each stripped before rendering.
+
+ This is the whole docstring, so a paragraph the file carries and the catalog doesn't is one
+ `fastro sync` would delete from a project without being asked.
+ """
+ entry = next(declared for declared in _entries() if declared["path"] == path)
+ header = _catalog()["wiring_defaults"]["header"]
+
+ assert _docstring(_committed(path)) == f"{entry['doc'].strip()}\n\n{header.strip()}\n"
+
+
+def test_the_hand_written_module_says_who_writes_the_ones_beside_it():
+ """It is not generated, so it is where the reason lives: once, in the file a person edits."""
+ docstring = _docstring(_committed(HAND_WRITTEN))
+
+ assert HAND_WRITTEN not in [entry["path"] for entry in _entries()]
+ assert docstring is not None
+ assert "fastro" in docstring
+ assert "blueprint.toml" in docstring
+ assert "imports and literals" in docstring
+
+
+LINE_LENGTH = _catalog()["wiring_defaults"]["line_length"]
+"""Spec 2.12: the length spec 2.8 wraps a generated import at, declared rather than assumed."""
+
+
+def test_the_generated_line_length_is_the_one_ruff_holds_the_project_to():
+ """Spec 2.12: an integer from 1 to 320. Declared shorter than ruff's, fastro would wrap an
+ import ruff is happy with; longer, and `ruff format --check` fails on a file nobody edited.
+ """
+ with BACKEND_PYPROJECT.open("rb") as handle:
+ backend = tomllib.load(handle)
+
+ assert 1 <= LINE_LENGTH <= 320
+ assert LINE_LENGTH == backend["tool"]["ruff"]["line-length"]
+
+
+@pytest.mark.parametrize("path", [entry["path"] for entry in _entries()])
+def test_no_import_in_a_generated_file_is_wrapped_before_it_has_to_be(path: str):
+ """Spec 2.8: a statement is wrapped only when one line of it would be too long."""
+ source = _committed(path)
+ for node in ast.parse(source).body:
+ if not isinstance(node, ast.Import | ast.ImportFrom):
+ continue
+
+ one_line = ast.unparse(node)
+ wrapped = (node.end_lineno or node.lineno) > node.lineno
+ assert wrapped == (len(one_line) > LINE_LENGTH), one_line
+
+
+@pytest.mark.parametrize(
+ ("path", "name"),
+ [(entry["path"], slot["name"]) for entry in _entries() for slot in entry["slots"] if slot["kind"] in {"tuple", "list"}],
+)
+def test_a_collection_of_more_than_one_is_written_one_entry_to_a_line(path: str, name: str):
+ """Spec 2.6: a tuple of two or more is always exploded, and a list always is."""
+ slot = next(slot for slot in next(e for e in _entries() if e["path"] == path)["slots"] if slot.get("name") == name)
+ defined = _defined(_committed(path), name)
+
+ assert isinstance(defined, ast.Tuple | ast.List)
+ exploded = (defined.end_lineno or defined.lineno) > defined.lineno
+
+ assert exploded == (len(defined.elts) >= (1 if slot["kind"] == "list" else 2))
+
+
+PROJECT_FILE = REPO_ROOT / "fastro.toml"
+
+GENERATOR_NAME = re.compile(r"^[a-z][a-z0-9-]*$")
+"""Spec 2.9. It becomes the word after `fastro make`, and `fastro make` takes no underscore."""
+
+COMMAND_WORD = re.compile(r"^[a-z][a-z0-9-]*$")
+
+ENV_VAR = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+"""Spec 2.5 and 2.12: the name of an environment variable."""
+
+PARAM_TYPES = {"int", "str", "bool", "cidr", "choice"}
+
+PYTHON_TYPES: dict[str, type] = {"int": int, "str": str, "bool": bool, "cidr": str, "choice": str}
+
+
+@functools.cache
+def _project() -> dict[str, Any]:
+ with PROJECT_FILE.open("rb") as handle:
+ return tomllib.load(handle)
+
+
+def _owned_paths() -> set[str]:
+ return {path for feature in _catalog()["features"].values() for path, _ in _declared(feature)}
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["generators"]))
+def test_every_generator_is_named_the_way_fastro_make_reads_it(name: str):
+ assert GENERATOR_NAME.match(name)
+ assert "register" not in _catalog()["generators"][name] or name == "module"
+ assert "types" not in _catalog()["generators"][name] or name == "module"
+
+
+@pytest.mark.parametrize("name", sorted(_catalog()["generators"]))
+def test_every_generators_templates_are_a_directory_this_repo_has(name: str):
+ """Spec 2.9: subdirectories when the generator has modes, which is one tree per mode."""
+ generator = _catalog()["generators"][name]
+ templates = REPO_ROOT / generator["templates"]
+
+ assert templates.is_dir()
+ assert any(child.is_dir() for child in templates.iterdir())
+
+
+@pytest.mark.parametrize(
+ ("generator", "param"),
+ sorted((name, param) for name, declared in _catalog()["generators"].items() for param in declared["params"]),
+)
+def test_every_param_is_declared_the_way_the_spec_asks(generator: str, param: str):
+ """Spec 2.9: a type and a default of that type, and the keys each type allows."""
+ declared = _catalog()["generators"][generator]["params"][param]
+
+ assert FEATURE_NAME.match(param)
+ assert declared["type"] in PARAM_TYPES
+ assert isinstance(declared["default"], PYTHON_TYPES[declared["type"]])
+ assert declared["type"] == "bool" or not isinstance(declared["default"], bool), "a bool is an int to isinstance"
+ assert declared["help"].strip() == declared["help"]
+ assert ("choices" in declared) == (declared["type"] == "choice")
+ for key in ("private_only", "max_prefix"):
+ assert key not in declared or declared["type"] == "cidr"
+
+
+def test_the_subnet_default_is_a_network_with_no_host_bits_set():
+ """Spec 2.9: `10.0.0.1/24` is not a network, and the tool would refuse the catalog for it."""
+ declared = _catalog()["generators"]["deploy"]["params"]["internal_subnet"]
+ network = ipaddress.ip_network(declared["default"], strict=True)
+
+ assert str(network) == declared["default"]
+ assert network.prefixlen >= declared["max_prefix"][f"v{network.version}"], "the default meets its own limit"
+
+
+def test_the_subnet_limit_is_set_for_both_families():
+ """Spec 2.9: a table with both `v4` (0 to 32) and `v6` (0 to 128), because one integer can't
+ carry the two. An IPv6 limit of 8 would accept a `/16`, which is half the address space.
+ """
+ limits = _catalog()["generators"]["deploy"]["params"]["internal_subnet"]["max_prefix"]
+
+ assert set(limits) == {"v4", "v6"}
+ assert 0 <= limits["v4"] <= 32
+ assert 0 <= limits["v6"] <= 128
+
+
+def test_every_param_the_templates_read_is_a_param_the_catalog_declares():
+ """Both ways: an undeclared param is a StrictUndefined crash, a declared one nothing reads is dead."""
+ generator = _catalog()["generators"]["deploy"]
+ templates = REPO_ROOT / generator["templates"]
+ read = {name for template in templates.rglob("*.j2") for name in re.findall(r"params\.([a-z_]+)", template.read_text())}
+
+ assert read == set(generator["params"])
+
+
+def _declared_commands() -> list[tuple[str | None, str, dict[str, Any]]]:
+ """Every declared command: the feature that owns it, or none, with its words and its table.
+
+ A list rather than a table keyed by the words, because two declarations of one command are
+ what spec 2.9 refuses, and a table would quietly keep the second.
+ """
+ declared: list[tuple[str | None, str, dict[str, Any]]] = [
+ (None, words, command) for words, command in _catalog()["commands"].items()
+ ]
+ for name, feature in _catalog()["features"].items():
+ declared.extend((name, words, command) for words, command in feature.get("commands", {}).items())
+
+ return declared
+
+
+def _script_of(command: dict[str, Any]) -> str:
+ return f"{_catalog()['blueprint']['python_root']}/{Path(*command['module'].split('.')).with_suffix('.py')}"
+
+
+def _under(script: str, paths: Iterable[str]) -> bool:
+ """Spec 1.1: a declaration names the file itself, or a subtree it sits in."""
+ return any(script == path or script.startswith(f"{path}/") for path in paths)
+
+
+def _sorted_commands() -> list[tuple[str | None, str, dict[str, Any]]]:
+ return sorted(_declared_commands(), key=lambda entry: entry[1])
+
+
+COMMANDS = [pytest.param(words, command, id=words) for _, words, command in _sorted_commands()]
+
+TOP_LEVEL_COMMANDS = [pytest.param(words, command, id=words) for owner, words, command in _sorted_commands() if owner is None]
+
+FEATURE_COMMANDS = [
+ pytest.param(owner, words, command, id=words) for owner, words, command in _sorted_commands() if owner is not None
+]
+
+
+@pytest.mark.parametrize(("words", "command"), COMMANDS)
+def test_every_command_is_spelled_the_way_the_spec_reads_it(words: str, command: dict[str, Any]):
+ """Spec 2.9: the words become the command path, one space apart."""
+ assert all(COMMAND_WORD.match(word) for word in words.split(" "))
+ assert " " not in words
+ assert all(part.isidentifier() and not keyword.iskeyword(part) for part in command["module"].split("."))
+ assert command["help"].strip() == command["help"]
+ assert "\n" not in command["help"]
+ assert command.get("outside_project", "error") in {"error", "token_hex"}
+
+
+@pytest.mark.parametrize(("words", "command"), COMMANDS)
+def test_every_command_runs_a_module_this_repo_can_run(words: str, command: dict[str, Any]):
+ """It is run as `python -m `, which needs the entry point that makes that work."""
+ path = REPO_ROOT / _catalog()["blueprint"]["python_root"] / Path(*command["module"].split(".")).with_suffix(".py")
+
+ assert path.is_file(), words
+ assert '__name__ == "__main__"' in path.read_text()
+
+
+def test_no_two_commands_claim_the_same_words():
+ """Spec 2.9: the words are unique across `[commands]` and every feature's.
+
+ fastro refuses the catalog at the second declaration, so a repeat is a catalog no project
+ can be generated from at all.
+ """
+ claimed = [words for _, words, _ in _declared_commands()]
+
+ assert sorted(claimed) == sorted(set(claimed))
+
+
+@pytest.mark.parametrize(("words", "command"), TOP_LEVEL_COMMANDS)
+def test_every_command_runs_a_script_no_feature_takes_away(words: str, command: dict[str, Any]):
+ """`[commands]` are always present (spec 2.9), so one naming a feature's script would break.
+
+ `scripts/unlock_account.py` goes with accounts, so it is accounts that declares
+ `fastro users unlock`: top-level, the command would be there in a project without the
+ module it runs.
+ """
+ assert not _under(_script_of(command), _owned_paths()), words
+
+
+@pytest.mark.parametrize(("owner", "words", "command"), FEATURE_COMMANDS)
+def test_every_feature_command_sits_under_its_features_own_paths(owner: str, words: str, command: dict[str, Any]):
+ """Spec 2.9: under the feature's own `paths`, not a `when`'s, which a selection still drops."""
+ declared = _declared(_catalog()["features"][owner])
+ script = _script_of(command)
+
+ assert _under(script, [path for path, condition in declared if condition is None]), words
+ assert not _under(script, [path for path, condition in declared if condition is not None]), words
+
+
+def test_the_feature_commands_are_every_feature_owned_script_a_project_could_run():
+ """Both ways, and against the repository rather than against the catalog's own account.
+
+ A runnable script of a feature's own that nothing declares is a command no project is
+ offered, and a command for a module its feature doesn't own is one some project is left
+ without.
+ """
+ python_root = _catalog()["blueprint"]["python_root"]
+ directory = REPO_ROOT / python_root / "scripts"
+ runnable = {
+ f"{python_root}/scripts/{script.name}"
+ for script in sorted(directory.glob("*.py"))
+ if _under(f"{python_root}/scripts/{script.name}", _owned_paths()) and '__name__ == "__main__"' in script.read_text()
+ }
+
+ assert runnable, directory
+ assert {_script_of(command) for owner, _, command in _declared_commands() if owner is not None} == runnable
+
+
+def test_every_selection_carries_the_commands_whose_module_it_keeps():
+ """A feature's command is there only where the feature is (spec 2.4).
+
+ That has to be exactly where the module it runs is still on disk: a command offered by a
+ project that cannot run it is worse than no command, and one a project could run but is
+ never offered is work thrown away.
+ """
+ features = _catalog()["features"]
+ owned = _owned_paths()
+
+ for chosen in _selections():
+ kept = _kept_by_the_catalog(features, chosen)
+ offered = {words for owner, words, _ in _declared_commands() if owner is None or owner in chosen}
+ runnable = {
+ words
+ for _, words, command in _declared_commands()
+ if not _under(_script_of(command), owned) or _under(_script_of(command), kept)
+ }
+
+ assert offered == runnable, sorted(chosen)
+
+
+def test_the_blueprint_repo_says_it_is_the_blueprint():
+ """Spec 3: `source = true` only in a blueprint repo, where generated files are committed."""
+ assert _project()["source"] is True
+ assert _project()["blueprint"] == {"name": _catalog()["blueprint"]["name"], "version": _catalog()["blueprint"]["version"]}
+
+
+def test_the_blueprint_repo_carries_every_feature():
+ """It has to: the committed wiring is the `everything` selection, and the tests cover all nine."""
+ assert _project()["features"] == list(_catalog()["features"])
+
+
+def test_the_blueprint_repo_runs_every_option_at_its_default():
+ """Spec 6.1: the `.env.example` lines the options rewrite are the ones this repo ships."""
+ declared = {
+ f"{name}.{option}": option_table["default"]
+ for name, feature in _catalog()["features"].items()
+ for option, option_table in feature.get("options", {}).items()
+ }
+
+ assert _project()["options"] == declared
+
+
+def test_the_project_is_named_the_way_its_python_package_is():
+ """`project.name` is what the deploy templates name the compose project after (spec 6.2)."""
+ with BACKEND_PYPROJECT.open("rb") as handle:
+ backend = tomllib.load(handle)
+
+ assert _project()["project"]["name"] == backend["project"]["name"]
+
+
+RETIRED_NAME = "fastro".title()
+
+STILL_CARRYING_THE_RETIRED_NAME = {
+ "docs/changelog.md": "B9 item 15",
+ "docs/assets/build-cover.cjs": "B5",
+ "docs/assets/build-card.cjs": "B5",
+}
+"""Files left as they are until the item named beside each, which rewrites them."""
+
+
+def test_no_tracked_file_calls_the_blueprint_by_its_retired_name():
+ """FastAPI-boilerplate is the blueprint, fastro the tool and FastroAI the paid blueprint: the
+ capitalised tool name, standing alone, names nothing. A wordmark that sets AI in its own
+ `` straight after it still spells FastroAI."""
+ alone = re.compile(rf"\b{RETIRED_NAME}\b(?!]*>AI)")
+ tracked = subprocess.run(["git", "ls-files", "-z"], cwd=REPO_ROOT, capture_output=True, text=True, check=True)
+ found = []
+ carrying = set()
+ for name in filter(None, tracked.stdout.split("\0")):
+ path = REPO_ROOT / name
+ if not path.is_file():
+ continue
+ try:
+ text = path.read_text(encoding="utf-8")
+ except UnicodeDecodeError:
+ continue
+ hits = [f"{name}:{number}" for number, line in enumerate(text.splitlines(), 1) if alone.search(line)]
+ if name in STILL_CARRYING_THE_RETIRED_NAME:
+ carrying |= {name} if hits else set()
+ else:
+ found += hits
+
+ assert not found, found
+ assert carrying == set(STILL_CARRYING_THE_RETIRED_NAME), "drop the exemption of a file that no longer carries it"
diff --git a/backend/tests/unit/test_docs_imports.py b/backend/tests/unit/test_docs_imports.py
index 5516fb52..22c5104a 100644
--- a/backend/tests/unit/test_docs_imports.py
+++ b/backend/tests/unit/test_docs_imports.py
@@ -6,8 +6,7 @@
The sweep checks that the module and the name exist, not that a relative import
counts the right number of dots: a sample rarely says which file it belongs to.
A relative import of a single name, ``.schemas``, is left alone -- which of them it
-means depends on the file it sits in, and in a project with features removed the
-name can turn unique and resolve to the wrong module.
+means depends on the file it sits in.
``ILLUSTRATIVE_MODULES`` lists the modules the guides invent to show how a project of
your own would look.
@@ -15,16 +14,13 @@
import ast
import importlib
-import importlib.util
import re
-import sys
from collections.abc import Iterator
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[3]
DOCS_ROOT = REPO_ROOT / "docs"
SRC_ROOT = REPO_ROOT / "backend" / "src"
-DRILL_PATH = REPO_ROOT / "tools" / "removal_drill.py"
PYTHON_BLOCK = re.compile(r"```python\n(.*?)```", re.DOTALL)
@@ -33,45 +29,9 @@
"src.modules.reports",
"src.modules.user.routes_v2",
"src.interfaces.api.v2",
- "src.infrastructure.observability",
)
-def _manifest():
- """The drill's feature manifest, which says which paths each feature owns."""
- spec = importlib.util.spec_from_file_location("removal_drill_manifest", DRILL_PATH)
- assert spec is not None and spec.loader is not None
- manifest = importlib.util.module_from_spec(spec)
- sys.modules[spec.name] = manifest
- spec.loader.exec_module(manifest)
-
- return manifest
-
-
-def _paths_of_features_left_out() -> tuple[str, ...]:
- """The paths owned by the features this project doesn't carry, which its docs still show."""
- manifest = _manifest()
- present = {
- name
- for name, feature in manifest.FEATURES.items()
- if (sources := [path for path in feature.paths if path.startswith("backend/src")])
- and all((REPO_ROOT / path).exists() for path in sources)
- }
-
- left_out: list[str] = []
- for name, feature in manifest.FEATURES.items():
- if name not in present:
- left_out.extend(feature.paths)
- for combination, paths in feature.combination_paths.items():
- if name not in present or combination not in present:
- left_out.extend(paths)
-
- return tuple(left_out)
-
-
-LEFT_OUT_PATHS = _paths_of_features_left_out()
-
-
def _import_statements(block: str) -> Iterator[tuple[ast.ImportFrom, int]]:
"""Every ``from ... import ...`` in a code block, with the line it starts on."""
lines = block.splitlines()
@@ -103,8 +63,7 @@ def _module_path(node: ast.ImportFrom) -> Path | None:
An absolute import names its module from ``src``. A relative one names a suffix of
at least two parts, resolved when exactly one module, or one package that would
- hold it, matches. A package the project doesn't carry at all resolves to nothing,
- so a sample for a feature this project removed is left alone.
+ hold it, matches.
"""
parts = (node.module or "").split(".")
if node.level == 0:
@@ -123,7 +82,7 @@ def _module_path(node: ast.ImportFrom) -> Path | None:
if existing.exists():
return existing
- return candidate.with_suffix(".py") if candidate.parent.is_dir() else None
+ return candidate.with_suffix(".py")
suffix = "/".join(parts)
modules = [path for path in SRC_ROOT.rglob(f"{parts[-1]}.py") if str(path).endswith(f"{suffix}.py")]
@@ -160,9 +119,6 @@ def _missing(where: str, node: ast.ImportFrom, path: Path) -> list[str]:
return []
if not path.exists():
- if LEFT_OUT_PATHS and str(path.relative_to(REPO_ROOT)).startswith(LEFT_OUT_PATHS):
- return []
-
return [f"{where}: no module {dotted}"]
module = importlib.import_module(dotted)
@@ -185,11 +141,7 @@ def test_every_documented_project_import_resolves():
def test_the_sweep_reads_the_samples_it_claims_to():
- """An extractor that quietly stopped matching would make the sweep above vacuous.
-
- Counts what every project carries, the documentation, rather than what the
- selected features leave resolvable.
- """
+ """An extractor that quietly stopped matching would make the sweep above vacuous."""
blocks = [block.group(1) for document in DOCS_ROOT.rglob("*.md") for block in PYTHON_BLOCK.finditer(document.read_text())]
statements = [node for block in blocks for node, _ in _import_statements(block)]
diff --git a/backend/tests/unit/test_docs_scripts.py b/backend/tests/unit/test_docs_scripts.py
index 194b09e9..b1f16e3a 100644
--- a/backend/tests/unit/test_docs_scripts.py
+++ b/backend/tests/unit/test_docs_scripts.py
@@ -18,6 +18,15 @@
"""What a script a reader runs has, which the modules beside them do not."""
+MIGRATIONS = REPO_ROOT / "docs" / "user-guide" / "database" / "migrations.md"
+"""The one guide whose manual recipe is a script of its own done by hand."""
+
+
+def test_the_migrations_guide_names_the_script_that_writes_the_baseline():
+ """`scripts/baseline.py` does what that recipe does, and a reader has no way to know it."""
+ assert "python -m scripts.baseline" in MIGRATIONS.read_text()
+
+
def _runnable_scripts() -> list[str]:
return sorted(path.name for path in SCRIPTS.glob("*.py") if RUNNABLE in path.read_text())
diff --git a/backend/tests/unit/test_docs_settings.py b/backend/tests/unit/test_docs_settings.py
new file mode 100644
index 00000000..45d1dc70
--- /dev/null
+++ b/backend/tests/unit/test_docs_settings.py
@@ -0,0 +1,127 @@
+"""Every settings class the documentation names is one the code has.
+
+A page that sends a reader to a class that isn't there leaves them grepping for it. A
+class a page defines in its own sample, to show how a project's settings would look, is
+the page's own; pydantic's ``BaseSettings`` is pydantic's; the changelog names classes as
+they were when each release shipped.
+"""
+
+import ast
+import importlib
+import inspect
+import re
+from pathlib import Path
+
+from pydantic_settings import BaseSettings
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SRC_ROOT = REPO_ROOT / "backend" / "src"
+PAGES = sorted([*(REPO_ROOT / "docs").rglob("*.md"), REPO_ROOT / "README.md"])
+HISTORY = REPO_ROOT / "docs" / "changelog.md"
+
+SETTINGS_NAME = re.compile(r"\b[A-Z][A-Za-z]*Settings\b")
+BACKTICKED_SETTINGS = re.compile(r"`([A-Z][A-Za-z]*Settings)`")
+SOURCE_PATH = re.compile(r"`(?:backend/)?(src/[\w/]+\.py)`")
+TABLE_ROW = re.compile(r"^\| `([A-Z][A-Za-z]*Settings)` \| (.+) \|$")
+BACKTICKED_FIELD = re.compile(r"`([A-Z][A-Z0-9_*]+)`")
+DEFINED_IN_A_SAMPLE = re.compile(r"^\s*class ([A-Z][A-Za-z]*Settings)\b", re.MULTILINE)
+
+
+def _classes_in_the_code() -> set[str]:
+ return {
+ node.name
+ for path in SRC_ROOT.rglob("*.py")
+ for node in ast.walk(ast.parse(path.read_text()))
+ if isinstance(node, ast.ClassDef)
+ }
+
+
+def test_every_settings_class_a_page_names_exists():
+ known = _classes_in_the_code() | {"BaseSettings"}
+ missing = []
+ for page in PAGES:
+ if page == HISTORY:
+ continue
+ text = page.read_text()
+ own = set(DEFINED_IN_A_SAMPLE.findall(text))
+ for number, line in enumerate(text.splitlines(), 1):
+ missing += [
+ f"{page.relative_to(REPO_ROOT)}:{number}: {name}"
+ for name in SETTINGS_NAME.findall(line)
+ if name not in known and name not in own
+ ]
+
+ assert not missing, "\n".join(missing)
+
+
+def _defined_in(path: Path) -> set[str]:
+ return {node.name for node in ast.walk(ast.parse(path.read_text())) if isinstance(node, ast.ClassDef)}
+
+
+def test_a_settings_class_named_beside_a_module_is_defined_in_it():
+ """A line that sends the reader to a file for a class sends them to the file that defines it."""
+ wrong = []
+ for page in PAGES:
+ if page == HISTORY:
+ continue
+ for number, line in enumerate(page.read_text().splitlines(), 1):
+ modules = [REPO_ROOT / "backend" / path for path in SOURCE_PATH.findall(line)]
+ classes = set(BACKTICKED_SETTINGS.findall(line)) - {"BaseSettings"}
+ if not modules or not classes:
+ continue
+ defined = set().union(*(_defined_in(module) for module in modules if module.exists()))
+ wrong += [f"{page.relative_to(REPO_ROOT)}:{number}: {name}" for name in sorted(classes - defined)]
+
+ assert not wrong, "\n".join(wrong)
+
+
+def _settings_class(name: str) -> type[BaseSettings]:
+ for path in SRC_ROOT.rglob("*.py"):
+ if name in _defined_in(path):
+ module = ".".join(path.relative_to(SRC_ROOT.parent).with_suffix("").parts)
+ found = getattr(importlib.import_module(module), name)
+ assert isinstance(found, type) and issubclass(found, BaseSettings), name
+
+ return found
+
+ raise LookupError(name)
+
+
+def test_every_setting_a_row_of_the_settings_table_names_is_on_that_class():
+ page = REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md"
+ rows = [found.groups() for found in map(TABLE_ROW.match, page.read_text().splitlines()) if found]
+
+ assert rows
+ wrong = []
+ for name, covers in rows:
+ settings_class = _settings_class(name)
+ wrong += [
+ f"{name}: {field}"
+ for field in BACKTICKED_FIELD.findall(covers)
+ if "*" not in field
+ and field not in settings_class.model_fields
+ and not isinstance(inspect.getattr_static(settings_class, field, None), property)
+ ]
+
+ assert not wrong, "\n".join(wrong)
+
+
+def _bases(source: str) -> list[str]:
+ (settings,) = [node for node in ast.walk(ast.parse(source)) if isinstance(node, ast.ClassDef) and node.name == "Settings"]
+
+ return [base.id for base in settings.bases if isinstance(base, ast.Name)]
+
+
+def test_the_settings_page_composes_settings_as_the_wiring_does():
+ page = (REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md").read_text()
+ sample = page.split("```python\n# src/wiring/settings.py", 1)[1].split("\n", 1)[1].split("```", 1)[0]
+
+ assert _bases(sample) == _bases((SRC_ROOT / "wiring" / "settings.py").read_text())
+
+
+def test_the_default_tier_name_is_said_to_be_on_the_class_that_has_it():
+ assert "DEFAULT_TIER_NAME" in _settings_class("TierSettings").model_fields
+ for page in ("docs/user-guide/configuration/settings-classes.md", "docs/user-guide/admin-panel/configuration.md"):
+ lines = [line for line in (REPO_ROOT / page).read_text().splitlines() if "`DEFAULT_TIER_NAME`" in line]
+ assert lines, page
+ assert all("`TierSettings`" in line for line in lines), (page, lines)
diff --git a/backend/tests/unit/test_docs_wiring.py b/backend/tests/unit/test_docs_wiring.py
index ee5ef6c3..9e38a3ba 100644
--- a/backend/tests/unit/test_docs_wiring.py
+++ b/backend/tests/unit/test_docs_wiring.py
@@ -7,26 +7,29 @@
"""
import re
+import tomllib
from pathlib import Path
-from tests.unit.test_docs_imports import LEFT_OUT_PATHS
+from src.modules.tier.settings import TierSettings
REPO_ROOT = Path(__file__).resolve().parents[3]
WIRING = REPO_ROOT / "backend" / "src" / "wiring"
STRUCTURE = REPO_ROOT / "docs" / "user-guide" / "project-structure.md"
COMPOSABLE = REPO_ROOT / "docs" / "user-guide" / "composable-features.md"
DIAGRAMS = REPO_ROOT / "docs" / "assets" / "build-diagrams.cjs"
+CHANGELOG = REPO_ROOT / "docs" / "changelog.md"
+ENVIRONMENT = REPO_ROOT / "docs" / "user-guide" / "configuration" / "environment-variables.md"
DRAWN_TREE = re.compile(r"```text\n(.*?)```", re.DOTALL)
+def _catalog() -> dict:
+ with (REPO_ROOT / "blueprint.toml").open("rb") as handle:
+ return tomllib.load(handle)
+
+
def _wiring_modules() -> list[str]:
- """The composition root's modules, as a project that carries them has them."""
- return sorted(
- path.name
- for path in WIRING.glob("*.py")
- if path.name != "__init__.py" and f"backend/src/wiring/{path.name}" not in LEFT_OUT_PATHS
- )
+ return sorted(path.name for path in WIRING.glob("*.py") if path.name != "__init__.py")
def _tree_drawing_the_wiring() -> str:
@@ -65,11 +68,107 @@ def test_the_diagram_draws_every_module_of_the_composition_root():
assert [name for name in _wiring_modules() if name not in drawn] == []
-def test_the_diagram_names_every_preset_the_drill_runs():
- """A preset added to the matrix and not to the picture is a diagram that has aged."""
- drill = (REPO_ROOT / "tools" / "removal_drill.py").read_text()
- presets = re.findall(r'^ "([a-z0-9-]+)": \(', drill, re.M)
- drawn = DIAGRAMS.read_text()
+def test_the_diagram_names_every_set_verify_sets_declares():
+ """A set added to `[verify.sets]` and not to the picture is a diagram that has aged."""
+ sets = _catalog()["verify"]["sets"]
+ drawn = set(re.findall(r">([a-z0-9-]+)", DIAGRAMS.read_text()))
+
+ assert sets
+ assert [name for name in sets if name not in drawn] == []
+
+
+def _section(page: Path, heading: str) -> str:
+ text = page.read_text()
+ assert heading in text, heading
+
+ return text.split(heading, 1)[1].split("\n## ", 1)[0]
+
+
+def test_the_ci_table_is_every_declared_set_and_names_the_presets_beside_it():
+ """CI runs `fastro blueprint verify` once for each set: the declared ones, each preset and `everything`."""
+ section = _section(COMPOSABLE, "## Checking that removal still works")
+ rows = re.findall(r"^\| `([a-z0-9-]+)` \|", section, re.M)
+ catalog = _catalog()
+
+ assert rows == [*catalog["verify"]["sets"], "everything"]
+ assert [preset for preset in catalog["presets"] if f"`{preset}`" not in section] == []
+
+
+def test_the_steps_for_a_removable_feature_declare_it_in_the_catalog_and_verify_it():
+ section = _section(COMPOSABLE, "## Writing a feature that can be removed")
+
+ assert "`blueprint.toml`" in section and "`[features.]`" in section
+ assert "`[[features..when]]`" in section and 'if = ""' in section
+ assert "`fastro blueprint verify`" in section
+ assert any(feature.get("when") for feature in _catalog()["features"].values())
+
+
+def test_the_new_module_steps_declare_its_paths_in_the_catalog():
+ steps = STRUCTURE.read_text().split("**Generate a migration**", 1)[0]
+
+ assert "`blueprint.toml`" in steps.rsplit("\n9. ", 1)[1]
+ assert "`fastro blueprint verify`" in steps.rsplit("\n9. ", 1)[1]
+
+
+def test_the_changelog_names_the_wiring_the_cache_reads_the_scope_fingerprint_from():
+ unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0]
+ entry = unreleased.split("**A project with the cache feature and without accounts imports.**", 1)[1].split("\n- **", 1)[0]
+ wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/scope.py")
+ (slot,) = wiring["slots"]
+
+ assert f"`{slot['name']}`" in entry and f"{slot['name']}:" in (WIRING / "scope.py").read_text()
+ assert "`src/wiring/scope.py`" in entry
+ assert slot["fallback"] == "None" and "`None` without accounts" in entry
+
+
+def test_the_changelog_names_the_test_a_project_without_the_cache_no_longer_ships():
+ unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0]
+ entry = unreleased.split("**A project with the cache feature and without accounts imports.**", 1)[1].split("\n- **", 1)[0]
+ path = "tests/integration/tier_limits/test_cached_listing.py"
+ (block,) = [block for block in _catalog()["features"]["tier_limits"]["when"] if f"backend/{path}" in block["paths"]]
+
+ assert f"`{path}`" in " ".join(entry.split())
+ assert block["if"] == "cache"
+
+
+def test_the_composable_features_page_says_the_scope_fingerprint_is_none_without_accounts():
+ (row,) = [line for line in COMPOSABLE.read_text().splitlines() if line.startswith("| `scope.py` |")]
+ wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/scope.py")
+ (slot,) = wiring["slots"]
+
+ assert slot["fallback"] == "None" and "`None` without it" in row
+
+
+def _unreleased_entry(heading: str) -> str:
+ unreleased = CHANGELOG.read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0]
+
+ return " ".join(unreleased.split(f"**{heading}**", 1)[1].split("\n- **", 1)[0].split())
+
+
+def test_the_changelog_names_the_wiring_a_new_account_takes_its_default_tier_from():
+ entry = _unreleased_entry("A new account is given the default tier.")
+ wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/signup.py")
+ (slot,) = wiring["slots"]
+
+ assert f"`{slot['name']}`" in entry and "`src/wiring/signup.py`" in entry
+ assert _catalog()["features"]["tiers"]["contributes"][slot["point"]] == ["src.modules.tier.hooks:default_tier"]
+ assert "`DEFAULT_TIER_NAME`" in entry
+
+
+def test_the_environment_page_says_both_signup_paths_take_the_default_tier():
+ page = ENVIRONMENT.read_text()
+ block, after = page.split("```env\nDEFAULT_TIER_NAME=", 1)[1].split("\n```", 1)
+ paragraph = " ".join(after.strip().split("\n\n", 1)[0].split())
+
+ assert block == TierSettings.model_fields["DEFAULT_TIER_NAME"].default
+ assert "signup route" in paragraph and "provider" in paragraph and "deleted" in paragraph
+
+
+def test_the_composable_features_page_says_tiers_sets_the_tier_default_tier_name_names():
+ (row,) = [line for line in COMPOSABLE.read_text().splitlines() if line.startswith("| `signup.py` |")]
+ wiring = next(module for module in _catalog()["wiring"] if module["path"] == "backend/src/wiring/signup.py")
+ (slot,) = wiring["slots"]
- assert presets, "no presets found in the drill"
- assert [preset for preset in presets if "-" in preset and preset not in drawn] == []
+ assert f"`{slot['name']}`" in row
+ assert _catalog()["features"]["tiers"]["contributes"][slot["point"]] == ["src.modules.tier.hooks:default_tier"]
+ assert "DEFAULT_TIER_NAME" in TierSettings.model_fields and "`DEFAULT_TIER_NAME`" in row
diff --git a/backend/tests/unit/test_image_contents.py b/backend/tests/unit/test_image_contents.py
index 425fa24f..adfe5819 100644
--- a/backend/tests/unit/test_image_contents.py
+++ b/backend/tests/unit/test_image_contents.py
@@ -12,8 +12,6 @@
import re
from pathlib import Path
-from tests.unit.test_docs_imports import LEFT_OUT_PATHS
-
REPO_ROOT = Path(__file__).resolve().parents[3]
DOCKERFILE = REPO_ROOT / "backend" / "Dockerfile"
DOCS_ROOT = REPO_ROOT / "docs"
@@ -47,23 +45,9 @@ def test_alembic_finds_its_configuration_from_the_working_directory_the_stages_u
assert "ENV ALEMBIC_CONFIG=/app/alembic.ini" in stage
-def _carried_by_this_project(module: str) -> bool:
- """Whether this project still has the script, rather than having removed its feature.
-
- The documentation describes every feature, so a build without one still shows commands
- for scripts it no longer carries.
- """
- return f"backend/scripts/{module.split('.')[1]}.py" not in LEFT_OUT_PATHS
-
-
def test_every_script_the_docs_run_in_a_container_exists():
"""The module name in the documented command has to name a file the image copies."""
- documented = {
- module
- for page in DOCS_ROOT.rglob("*.md")
- for module in RUN_IN_A_CONTAINER.findall(page.read_text())
- if _carried_by_this_project(module)
- }
+ documented = {module for page in DOCS_ROOT.rglob("*.md") for module in RUN_IN_A_CONTAINER.findall(page.read_text())}
assert documented, "no documented in-container script run found"
assert [module for module in sorted(documented) if not (SCRIPTS / f"{module.split('.')[1]}.py").exists()] == []
diff --git a/backend/tests/unit/test_removal_drill.py b/backend/tests/unit/test_removal_drill.py
deleted file mode 100644
index 97ecc211..00000000
--- a/backend/tests/unit/test_removal_drill.py
+++ /dev/null
@@ -1,258 +0,0 @@
-"""The drill's own manifest: a selection has to pull in everything it needs.
-
-The drill lives outside the backend package, so it is loaded from its path rather
-than imported.
-"""
-
-import ast
-import importlib.util
-import shutil
-import sys
-from pathlib import Path
-
-import pytest
-
-BACKEND_ROOT = Path(__file__).resolve().parents[2]
-DRILL_PATH = BACKEND_ROOT.parent / "tools" / "removal_drill.py"
-
-_spec = importlib.util.spec_from_file_location("removal_drill", DRILL_PATH)
-assert _spec is not None and _spec.loader is not None
-drill = importlib.util.module_from_spec(_spec)
-sys.modules[_spec.name] = drill
-_spec.loader.exec_module(drill)
-
-
-def test_a_selection_pulls_in_what_its_features_need_all_the_way_down():
- """tier_limits needs tiers and ratelimit, and both of those need accounts."""
- assert drill._selected_from(("tier_limits",)) == {"tier_limits", "tiers", "ratelimit", "accounts"}
-
-
-@pytest.mark.parametrize("preset", sorted(drill.PRESETS))
-def test_every_preset_is_closed_under_its_requirements(preset: str):
- chosen = drill._selected(preset)
-
- for feature in chosen:
- assert set(drill.REQUIRES.get(feature, ())) <= chosen, feature
-
-
-def test_every_feature_the_wiring_knows_is_in_the_manifest():
- """A feature missing here would never be removed by any preset."""
- assert set(drill.FEATURES) >= set(drill.REQUIRES)
- assert set(drill.PRESETS["everything"]) == set(drill.FEATURES)
-
-
-class TestReportingACheck:
- """A failing preset has to say what failed: the drill is the only place that output exists."""
-
- def test_a_failing_check_prints_what_it_printed(self):
- failed = drill.Result(
- "tests",
- False,
- "1 failed, 664 passed",
- "FAILED tests/integration/test_x.py::test_y - assert 2 == 1\n1 failed, 664 passed",
- )
-
- report = drill._report(failed)
-
- assert "FAIL" in report
- assert "tests/integration/test_x.py::test_y" in report
-
- def test_a_long_failure_prints_its_end_and_says_what_it_dropped(self):
- """A ``-q`` run is mostly progress dots; the failure sits at the end of it."""
- printed = "\n".join(f"line {number}" for number in range(100))
-
- report = drill._report(drill.Result("tests", False, "line 99", printed))
-
- assert "line 99" in report
- assert "line 0" not in report
- assert "60 earlier lines" in report
-
- def test_a_build_that_raises_leaves_its_scratch_copy_behind(self, monkeypatch, capsys):
- """Whatever the build tripped over is only visible in the copy it got to."""
-
- def failing_build(preset: str, scratch: Path) -> Path:
- raise RuntimeError("copy failed")
-
- monkeypatch.setattr(drill, "build", failing_build)
- monkeypatch.setattr(sys, "argv", ["removal_drill.py", "core-only"])
-
- with pytest.raises(RuntimeError, match="copy failed"):
- drill.main()
-
- printed = capsys.readouterr().out
-
- assert "scratch copies left in" in printed
-
- left = Path(printed.split("scratch copies left in ")[1].strip())
-
- assert left.exists()
- shutil.rmtree(left, ignore_errors=True)
-
- def test_a_passing_check_prints_its_last_line_only(self):
- passed = drill.Result("tests", True, "665 passed", "a long run of dots\n665 passed")
-
- report = drill._report(passed)
-
- assert report.strip() == "PASS tests 665 passed"
-
-
-def test_a_scratch_project_never_carries_the_repository_env_file(tmp_path):
- """It would point a build at whatever the developer runs locally."""
- source = tmp_path / "source"
- (source / "backend").mkdir(parents=True)
- (source / ".git").mkdir()
- (source / "backend" / ".env").write_text("POSTGRES_PASSWORD=the-developers-own\n")
- (source / ".env").write_text("SECRET_KEY=the-developers-own\n")
- (source / "backend" / ".env.example").write_text("POSTGRES_PASSWORD=postgres\n")
- (source / ".git" / "HEAD").write_text("ref: refs/heads/main\n")
-
- drill.copy_repository(source, tmp_path / "project")
-
- copied = sorted(path.relative_to(tmp_path / "project").as_posix() for path in (tmp_path / "project").rglob("*"))
-
- assert copied == ["backend", "backend/.env.example"]
-
-
-def test_a_scratch_project_is_built_from_the_repository(tmp_path):
- """The copy above is the one ``build`` makes, so build it once for real."""
- project = drill.build("core-only", tmp_path)
-
- assert (project / "backend" / ".env.example").exists()
- assert [path for path in project.rglob("*") if path.name == ".env"] == []
-
-
-def _features_on_disk() -> set[str]:
- """The features this project still carries, read from the source paths they own."""
- repository = BACKEND_ROOT.parent
- present = set()
- for name, feature in drill.FEATURES.items():
- sources = [path for path in feature.paths if path.startswith("backend/src")]
- if sources and all((repository / path).exists() for path in sources):
- present.add(name)
-
- return present
-
-
-def _needs(*features: str) -> None:
- """Skip where this project no longer carries the sources a preset is built from."""
- missing = sorted(set(features) - _features_on_disk())
- if missing:
- pytest.skip(f"this project carries no {', '.join(missing)} to build from")
-
-
-class TestTheTaskModulesAProjectRegisters:
- """A task module imports the feature it belongs to and the broker it registers on."""
-
- @pytest.mark.parametrize("chosen", [{"accounts", "api_keys"}, {"accounts", "taskiq"}, {"taskiq"}, set()])
- def test_the_usage_prune_is_registered_by_neither_feature_alone(self, chosen: set[str]):
- assert "src.modules.api_keys.tasks" not in drill._wiring_tasks(chosen)
-
- def test_the_usage_prune_is_registered_where_both_features_are_present(self):
- assert "src.modules.api_keys.tasks" in drill._wiring_tasks({"accounts", "api_keys", "taskiq"})
-
- def test_a_project_with_the_keys_and_no_worker_has_no_task_module(self, tmp_path):
- _needs("accounts", "api_keys")
- project = drill.build("accounts-api-keys", tmp_path)
-
- assert (project / "backend/src/modules/api_keys/service.py").exists()
- assert not (project / "backend/src/modules/api_keys/tasks.py").exists()
-
- def test_a_project_with_a_worker_and_no_keys_has_no_task_module(self, tmp_path):
- _needs("accounts", "taskiq")
- project = drill.build("accounts-cache-taskiq", tmp_path)
-
- assert (project / "backend/src/infrastructure/taskiq/worker.py").exists()
- assert not (project / "backend/src/modules/api_keys").exists()
-
-
-class TestTheSenderAProjectIsWiredTo:
- """The request never waits for a mail server, queue or no queue."""
-
- def test_a_project_with_a_worker_queues_the_message(self):
- wired = drill._wiring_email({"accounts", "taskiq"})
-
- assert "EMAIL_SENDER: EmailSender = queued_sender" in wired
-
- def test_a_project_without_one_hands_the_delivery_over(self):
- """crudauth awaits the sender, so a sender that returns is what keeps the answer quick."""
- wired = drill._wiring_email({"accounts"})
-
- assert "from ..infrastructure.email.senders import HandingOverSender" in wired
- assert "EMAIL_SENDER: EmailSender = HandingOverSender(build_sender())" in wired
-
- def test_a_project_without_one_drains_at_shutdown(self):
- """What was handed over is mail somebody asked for, so a deploy waits for it."""
- wired = drill._wiring_app({"accounts"})
-
- assert "from ..infrastructure.handover import lifecycle as handover_lifecycle" in wired
- assert "handover_lifecycle" in wired.split("LIFECYCLES")[1]
-
- def test_a_project_with_a_worker_drains_before_it_closes_the_broker(self):
- """The worker's own lifecycle drains, where a message may still be on its way out."""
- wired = drill._wiring_app({"accounts", "taskiq"})
-
- assert "handover_lifecycle" not in wired
- assert "taskiq_lifecycle" in wired.split("LIFECYCLES")[1]
-
-
-GENERATED_FILES = (
- ("src/wiring/settings.py", "_wiring_settings"),
- ("src/wiring/app.py", "_wiring_app"),
- ("src/wiring/hooks.py", "_wiring_hooks"),
- ("src/wiring/email.py", "_wiring_email"),
- ("src/wiring/tasks.py", "_wiring_tasks"),
- ("src/wiring/tables.py", "_wiring_tables"),
- ("src/wiring/transports.py", "_wiring_transports"),
- ("src/wiring/cache.py", "_wiring_cache"),
- ("src/wiring/models.py", "_wiring_models"),
- ("src/wiring/admin.py", "_wiring_admin"),
- ("scripts/seeders.py", "_seeders"),
- ("tests/wiring.py", "_tests_wiring"),
-)
-
-
-def _without_formatting(source: str) -> tuple[tuple[str, ...], tuple[str, ...]]:
- """A module's imports and statements, as trees: no docstring, no comments, no layout."""
- body = ast.parse(source).body
- if body and isinstance(body[0], ast.Expr) and isinstance(body[0].value, ast.Constant):
- body = body[1:]
-
- imports = sorted(ast.dump(node) for node in body if isinstance(node, ast.Import | ast.ImportFrom))
- statements = [ast.dump(node) for node in body if not isinstance(node, ast.Import | ast.ImportFrom)]
-
- return tuple(imports), tuple(statements)
-
-
-def test_the_generator_rebuilds_what_this_project_committed():
- """The drill proves a regenerated project reproduces this one, which needs them equal."""
- present = _features_on_disk()
-
- assert (BACKEND_ROOT / "src/wiring/admin.py").exists() == ("admin" in present)
-
- for name, generator in GENERATED_FILES:
- committed = BACKEND_ROOT / name
- if name == "src/wiring/admin.py" and "admin" not in present:
- continue
-
- assert _without_formatting(getattr(drill, generator)(present)) == _without_formatting(committed.read_text()), name
-
-
-TRACING_RECIPE = BACKEND_ROOT.parent / "docs/user-guide/observability.md"
-"""The one guide that asks a reader to install something of their own on the app."""
-
-
-def test_a_rebuild_leaves_the_composition_root_as_it_is(tmp_path):
- """That recipe wires its installer there, where no regeneration reaches it."""
- project = drill.build("core-only", tmp_path)
-
- rebuilt = project / "backend/src/interfaces/main.py"
-
- assert rebuilt.read_text() == (BACKEND_ROOT / "src/interfaces/main.py").read_text()
-
-
-def test_the_tracing_recipe_wires_itself_outside_the_generated_wiring():
- """Written into ``INSTALLERS`` instead, it would fail the comparison above."""
- recipe = TRACING_RECIPE.read_text()
-
- assert "installers=(*INSTALLERS, tracing_install)" in recipe
- assert "INSTALLERS: tuple" not in recipe
diff --git a/backend/tests/unit/test_tarball_contents.py b/backend/tests/unit/test_tarball_contents.py
new file mode 100644
index 00000000..406d0c14
--- /dev/null
+++ b/backend/tests/unit/test_tarball_contents.py
@@ -0,0 +1,66 @@
+"""What a source tarball carries, which is whatever `git archive` writes.
+
+GitHub builds a release's tarball the same way, so a path marked `export-ignore` is one a
+download doesn't have. What's left out is the blueprint's own: the documentation site and the
+issue templates are things to read in this repository, not things a reader builds the project
+from.
+"""
+
+import io
+import subprocess
+import tarfile
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+LEFT_OUT = (".github/ISSUE_TEMPLATE/", "docs/", "zensical.toml")
+"""The paths `.gitattributes` keeps out of the tarball."""
+
+CARRIED = ("README.md", "backend/Dockerfile", "backend/pyproject.toml", "backend/src/interfaces/main.py")
+"""A few a reader could not build the project without, so the archive is read, not assumed.
+
+The compose file is not among them: `.gitignore` keeps it out, because the deploy generator
+writes it."""
+
+
+def _archived() -> set[str]:
+ """Every path `git archive` writes for the current commit.
+
+ The attributes are read from the working tree rather than from `HEAD`, so a `.gitattributes`
+ that isn't committed yet still counts and the answer doesn't wait for the commit.
+ """
+ written = subprocess.run(
+ ["git", "archive", "--worktree-attributes", "--format=tar", "HEAD"],
+ cwd=REPO_ROOT,
+ capture_output=True,
+ check=True,
+ )
+ with tarfile.open(fileobj=io.BytesIO(written.stdout)) as archive:
+ return {member.name for member in archive.getmembers()}
+
+
+def test_the_tarball_leaves_out_what_only_this_repository_needs():
+ archived = _archived()
+
+ assert {name for name in archived for path in LEFT_OUT if name.startswith(path.rstrip("/"))} == set()
+
+
+def test_the_tarball_carries_what_the_project_is_built_from():
+ """The other direction, and the proof that the archive was read at all."""
+ archived = _archived()
+
+ assert archived
+ assert set(CARRIED) <= archived
+
+
+def test_every_path_kept_out_is_one_this_repository_has():
+ """A path that moved would be ignored silently, leaving the real one in the tarball."""
+ for path in LEFT_OUT:
+ assert (REPO_ROOT / path).exists(), path
+
+
+def test_the_paths_kept_out_are_the_ones_gitattributes_ignores():
+ """Both ways: an entry left behind in `.gitattributes` is one no test reads."""
+ rules = [line.split() for line in (REPO_ROOT / ".gitattributes").read_text().splitlines()]
+
+ assert sorted(rule[0] for rule in rules if rule[1:] == ["export-ignore"]) == sorted(LEFT_OUT)
diff --git a/backend/tests/wiring.py b/backend/tests/wiring.py
index 35b14696..c33cbdd0 100644
--- a/backend/tests/wiring.py
+++ b/backend/tests/wiring.py
@@ -1,6 +1,7 @@
"""Fixture modules of the selected features, loaded by ``tests/conftest.py``.
-Written by the generator in `tools/removal_drill.py`, which a test compares this file against.
+Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`.
"""
PYTEST_PLUGINS: list[str] = [
diff --git a/blueprint.toml b/blueprint.toml
new file mode 100644
index 00000000..7360703c
--- /dev/null
+++ b/blueprint.toml
@@ -0,0 +1,798 @@
+[blueprint]
+name = "fastapi-boilerplate"
+version = "0.20.0"
+schema = 1
+requires_fastro = ">=0.1.0.dev0,<0.2"
+python_root = "backend"
+overlay = "blueprint/overlay"
+import_root = "src"
+blueprint_only = [
+ ".gitattributes",
+ ".gitignore",
+ ".github/",
+ ".pre-commit-config.yaml",
+ "CODE_OF_CONDUCT.md",
+ "CONTRIBUTING.md",
+ "README.md",
+ "backend/tests/unit/infrastructure/config/defaults.json",
+ "backend/tests/unit/infrastructure/config/example_values.json",
+ "backend/tests/unit/infrastructure/config/test_settings_tables.py",
+ "backend/tests/unit/test_blueprint_catalog.py",
+ "backend/tests/unit/test_docs_imports.py",
+ "backend/tests/unit/test_docs_recipes.py",
+ "backend/tests/unit/test_docs_scripts.py",
+ "backend/tests/unit/test_docs_settings.py",
+ "backend/tests/unit/test_docs_wiring.py",
+ "backend/tests/unit/test_image_contents.py",
+ "backend/tests/unit/test_tarball_contents.py",
+ "blueprint/",
+ "blueprint.toml",
+ "docs/",
+ "fastro.toml",
+ "pyproject.toml",
+ "uv.lock",
+ "zensical.toml",
+]
+
+[blueprint.dependencies]
+runtime = [
+ "alembic>=1.16.4",
+ "anyio>=4.15.1",
+ "asyncpg>=0.30.0",
+ "crudauth[all]>=0.8.2,<0.9.0",
+ "fastapi[standard]>=0.115.8,<0.140.7",
+ "fastcrud>=0.21.0",
+ "greenlet>=3.1.1",
+ "pydantic>=2.10.6",
+ "pydantic-settings>=2.14.2",
+ "redis>=6.1.0",
+ "sqlalchemy>=2.0.37",
+ "starlette>=1.3.1",
+]
+dev = [
+ "mypy>=1.14.1",
+ "ruff>=0.9.4",
+ "pytest>=8.3.5",
+ "pytest-asyncio>=0.25.3",
+ "pytest-mock>=3.14.0",
+ "testcontainers[postgres]>=4.10.0",
+ "pytest-xdist[psutil]>=3.8.0",
+ "pre-commit>=4.0.0",
+ "faker>=37.1.0",
+ "httpx>=0.28.1",
+ "jinja2>=3.1.6",
+]
+
+[presets]
+minimal = ["accounts"]
+standard = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "admin", "cache"]
+full = ["accounts", "rbac", "ratelimit", "tiers", "tier_limits", "api_keys", "admin", "cache", "taskiq"]
+
+[verify]
+app = "src.interfaces.main"
+
+[verify.sets]
+core-only = []
+core-taskiq = ["taskiq"]
+accounts-only = ["accounts"]
+accounts-rbac = ["accounts", "rbac"]
+accounts-admin = ["accounts", "admin"]
+accounts-api-keys = ["accounts", "api_keys"]
+accounts-rbac-tiers = ["accounts", "rbac", "tiers", "ratelimit"]
+accounts-cache-taskiq = ["accounts", "cache", "taskiq"]
+
+[core.contributes]
+critical_readiness = [
+ "src.infrastructure.database.health:readiness as database_readiness",
+ "src.infrastructure.database.health:schema_readiness",
+]
+
+[points.routers]
+cardinality = "many"
+doc = "A router the API mounts under its version prefix."
+
+[points.root_routers]
+cardinality = "one"
+doc = "The routers mounted beside the API rather than under its prefix."
+
+[points.api_throttle]
+cardinality = "many"
+doc = "A dependency every throttled route runs before answering."
+
+[points.lifecycles]
+cardinality = "many"
+doc = "Startup and shutdown work, started in order and torn down in reverse."
+
+[points.installers]
+cardinality = "many"
+doc = "Something that installs itself on the app as the app is built."
+
+[points.docs_guard]
+cardinality = "one"
+doc = "The dependency that guards the documentation routes where they are served."
+
+[points.settings]
+cardinality = "many"
+doc = "A settings mixin the project's Settings inherits, with the core one last."
+
+[points.permission_sources]
+cardinality = "many"
+doc = "Answers which permissions an account holds."
+
+[points.rate_limit_resolvers]
+cardinality = "many"
+doc = "Answers the limit for a request, or declines to."
+
+[points.tier_delete_guards]
+cardinality = "many"
+doc = "Answers why a tier cannot be deleted yet."
+
+[points.tier_delete_releases]
+cardinality = "many"
+doc = "Releases the rows a feature keeps for a tier that is being deleted."
+
+[points.critical_readiness]
+cardinality = "many"
+doc = "A dependency a request needs, so readiness answers 503 while it is unreachable."
+
+[points.informational_readiness]
+cardinality = "many"
+doc = "A dependency readiness reports on without refusing traffic over it."
+
+[points.user_model]
+cardinality = "many"
+doc = "Columns a feature adds to the user model."
+
+[points.user_schema]
+cardinality = "many"
+doc = "Fields a feature adds to the user schemas."
+
+[points.admin_views]
+cardinality = "many"
+doc = "A model view the admin panel registers."
+
+[points.email_sender]
+cardinality = "one"
+doc = "The sender the account emails go out through."
+
+[points.cache_decorator]
+cardinality = "one"
+doc = "The decorator a route caches its response with."
+
+[points.task_modules]
+cardinality = "many"
+doc = "A module whose background tasks the worker registers."
+
+[points.table_modules]
+cardinality = "many"
+doc = "A module outside src/modules that declares tables on the metadata."
+
+[points.extra_transports]
+cardinality = "many"
+doc = "An authentication transport registered beside the session one."
+
+[points.scope_fingerprint]
+cardinality = "one"
+doc = "What tells a credential that carries a scope apart from its account's others."
+
+[points.new_account_fields]
+cardinality = "many"
+doc = "Columns a feature sets on an account as it is created, on every signup path."
+
+[points.seeders]
+cardinality = "many"
+doc = "A step the initial-data script runs, in order."
+
+[points.test_plugins]
+cardinality = "many"
+doc = "A fixture module pytest loads for the features the project carries."
+
+[features.accounts]
+summary = "Users, sessions, CSRF, login lockout, OAuth"
+group = "Accounts"
+dependencies = ["user-agents>=2.2.0"]
+paths = [
+ "backend/scripts/canonicalize_emails.py",
+ "backend/scripts/create_first_superuser.py",
+ "backend/scripts/unlock_account.py",
+ "backend/src/infrastructure/auth/",
+ "backend/src/modules/user/",
+ "backend/tests/fixtures/accounts.py",
+ "backend/tests/integration/accounts/",
+ "backend/tests/integration/api/v1/users/",
+ "backend/tests/integration/auth/",
+ "backend/tests/unit/infrastructure/auth/",
+ "backend/tests/unit/modules/user/",
+ "backend/tests/unit/scripts/test_canonicalize_emails.py",
+ "backend/tests/unit/scripts/test_create_first_superuser.py",
+ "backend/tests/unit/scripts/test_setup_initial_data.py",
+ "backend/tests/unit/scripts/test_unlock_account.py",
+]
+
+[features.accounts.contributes]
+routers = [
+ { ref = "src.modules.user.routes:router as users_router", prefix = "/users", throttled = true, order = 10 },
+ { ref = "src.infrastructure.auth.routes:router as auth_router", prefix = "/auth", throttled = false, order = 22 },
+]
+root_routers = ["src.infrastructure.auth.routes:root_routers as accounts_root_routers"]
+lifecycles = [
+ "src.infrastructure.auth.setup:lifecycle as accounts_lifecycle",
+ { ref = "src.infrastructure.handover:lifecycle as handover_lifecycle", if = "not taskiq", order = 950 },
+]
+installers = ["src.infrastructure.auth.install:install as accounts_install"]
+docs_guard = ["src.infrastructure.auth.dependencies:get_current_superuser"]
+settings = ["src.infrastructure.auth.settings:AccountsSettings"]
+critical_readiness = [
+ "src.infrastructure.auth.health:limiter_readiness",
+ "src.infrastructure.auth.health:sessions_readiness",
+]
+table_modules = [{ value = "src.infrastructure.auth.store" }]
+seeders = [{ ref = "scripts.create_first_superuser:create_first_superuser", order = 11 }]
+test_plugins = [{ value = "tests.fixtures.accounts" }]
+scope_fingerprint = ["src.infrastructure.auth.scope:scope_fingerprint"]
+
+[features.accounts.commands."users unlock"]
+module = "scripts.unlock_account"
+help = "Clear the login lockout an account is held in."
+
+[features.accounts.commands."users canonicalize-emails"]
+module = "scripts.canonicalize_emails"
+help = "Rewrite the user addresses stored with case or whitespace in them."
+
+[features.accounts.commands."users create-superuser"]
+module = "scripts.create_first_superuser"
+help = "Create the first superuser from the admin environment variables."
+
+[[features.accounts.when]]
+if = "admin"
+paths = [
+ "backend/src/modules/user/admin.py",
+ "backend/tests/unit/modules/user/test_admin.py",
+]
+contributes.admin_views = [{ ref = "src.modules.user.admin:UserAdmin", order = 10 }]
+
+[features.rbac]
+summary = "Roles and permissions"
+group = "Accounts"
+requires = ["accounts"]
+paths = [
+ "backend/src/modules/role/",
+ "backend/tests/integration/rbac/",
+ "backend/tests/unit/modules/role/",
+]
+
+[features.rbac.contributes]
+routers = [
+ { ref = "src.modules.role.routes:user_roles_router", prefix = "/users", throttled = true, order = 13 },
+ { ref = "src.modules.role.routes:permissions_router", prefix = "/permissions", throttled = true, order = 24 },
+ { ref = "src.modules.role.routes:router as roles_router", prefix = "/roles", throttled = true, order = 25 },
+]
+permission_sources = ["src.modules.role.sources:role_permissions"]
+user_model = ["src.modules.role.contrib:UserRoleColumns"]
+
+[[features.rbac.when]]
+if = "admin"
+paths = [
+ "backend/src/modules/role/admin.py",
+ "backend/tests/unit/modules/role/test_admin.py",
+]
+contributes.admin_views = [
+ { ref = "src.modules.role.admin:RoleAdmin", order = 12 },
+ { ref = "src.modules.role.admin:RolePermissionAdmin", order = 13 },
+ { ref = "src.modules.role.admin:UserRoleAdmin", order = 14 },
+]
+
+[features.ratelimit]
+summary = "Per-caller API throttle"
+group = "Accounts"
+requires = ["accounts"]
+paths = [
+ "backend/src/infrastructure/ratelimit/",
+ "backend/tests/integration/ratelimit/",
+ "backend/tests/unit/infrastructure/ratelimit/",
+]
+
+[features.ratelimit.contributes]
+api_throttle = ["src.infrastructure.ratelimit.dependency:api_rate_limit_dependency"]
+settings = ["src.infrastructure.ratelimit.settings:RateLimitSettings"]
+
+[features.tiers]
+summary = "User tiers other features key off"
+group = "Accounts"
+requires = ["accounts"]
+paths = [
+ "backend/scripts/create_first_tier.py",
+ "backend/src/modules/tier/",
+ "backend/tests/fixtures/tiers.py",
+ "backend/tests/integration/tiers/",
+ "backend/tests/unit/modules/tier/",
+]
+
+[features.tiers.contributes]
+routers = [
+ { ref = "src.modules.tier.routes:user_tier_router", prefix = "/users", throttled = true, order = 11 },
+ { ref = "src.modules.tier.routes:router as tiers_router", prefix = "/tiers", throttled = true, order = 20 },
+]
+settings = ["src.modules.tier.settings:TierSettings"]
+user_model = ["src.modules.tier.contrib:UserTierColumns"]
+user_schema = ["src.modules.tier.contrib:UserTierFields"]
+seeders = [{ ref = "scripts.create_first_tier:create_first_tier", order = 10 }]
+test_plugins = [{ value = "tests.fixtures.tiers" }]
+new_account_fields = ["src.modules.tier.hooks:default_tier"]
+
+[features.tiers.commands."tiers create-default"]
+module = "scripts.create_first_tier"
+help = "Create the default tier DEFAULT_TIER_NAME names, if it isn't there yet."
+
+[[features.tiers.when]]
+if = "admin"
+paths = [
+ "backend/src/modules/tier/admin.py",
+ "backend/tests/unit/modules/tier/test_admin.py",
+]
+contributes.admin_views = [{ ref = "src.modules.tier.admin:TierAdmin", order = 11 }]
+
+[features.tier_limits]
+summary = "Per-tier rate limits"
+group = "Accounts"
+requires = ["tiers", "ratelimit"]
+paths = [
+ "backend/src/modules/rate_limit/",
+ "backend/tests/integration/tier_limits/",
+ "backend/tests/unit/modules/rate_limit/",
+]
+
+[features.tier_limits.contributes]
+routers = [
+ { ref = "src.modules.rate_limit.routes:user_rate_limits_router", prefix = "/users", throttled = true, order = 12 },
+ { ref = "src.modules.rate_limit.routes:router as rate_limits_router", prefix = "/rate-limits", throttled = true, order = 21 },
+]
+rate_limit_resolvers = ["src.modules.rate_limit.hooks:tier_rate_limit"]
+tier_delete_guards = ["src.modules.rate_limit.hooks:rate_limits_reference_tier"]
+tier_delete_releases = ["src.modules.rate_limit.hooks:release_deleted_rate_limits"]
+
+[[features.tier_limits.when]]
+if = "cache"
+paths = [
+ "backend/tests/integration/tier_limits/test_cached_listing.py",
+]
+
+[features.api_keys]
+summary = "API keys: create, revoke, meter"
+group = "Accounts"
+requires = ["accounts"]
+paths = [
+ "backend/scripts/cleanup_api_key_json.py",
+ "backend/scripts/prune_key_usage.py",
+ "backend/scripts/revoke_scrypt_api_keys.py",
+ "backend/src/modules/api_keys/",
+ "backend/tests/integration/api/v1/api_keys/",
+ "backend/tests/unit/modules/api_keys/",
+]
+
+[features.api_keys.contributes]
+routers = [
+ { ref = "src.modules.api_keys.routes:router as api_keys_router", prefix = "/api-keys", throttled = true, order = 23 },
+]
+installers = ["src.modules.api_keys.install:install as api_keys_install"]
+settings = ["src.modules.api_keys.settings:APIKeySettings"]
+extra_transports = [{ ref = "src.modules.api_keys.transport:APIKeyTransport", call = true }]
+
+[features.api_keys.commands."keys cleanup-json"]
+module = "scripts.cleanup_api_key_json"
+help = "Repair the API key rows whose JSON columns hold something nothing can read."
+
+[features.api_keys.commands."keys prune-usage"]
+module = "scripts.prune_key_usage"
+help = "Delete the API key usage rows past the retention."
+
+[features.api_keys.commands."keys revoke-scrypt"]
+module = "scripts.revoke_scrypt_api_keys"
+help = "Name the API keys still stored under a scrypt hash, and revoke them when asked."
+
+[[features.api_keys.when]]
+if = "ratelimit"
+paths = [
+ "backend/tests/integration/api_keys_ratelimit/",
+]
+
+[[features.api_keys.when]]
+if = "rbac"
+paths = [
+ "backend/tests/integration/api_keys_rbac/",
+]
+
+[[features.api_keys.when]]
+if = "taskiq"
+paths = [
+ "backend/src/modules/api_keys/tasks.py",
+ "backend/tests/unit/modules/api_keys/test_tasks.py",
+]
+contributes.task_modules = [{ value = "src.modules.api_keys.tasks", order = 11 }]
+
+[[features.api_keys.when]]
+if = "tier_limits"
+paths = [
+ "backend/tests/integration/api_keys_tiers/",
+]
+
+[features.admin]
+summary = "SQLAdmin panel at /admin"
+group = "Operations"
+requires = ["accounts"]
+dependencies = ["sqladmin>=0.28.0", "itsdangerous>=2.2.0"]
+paths = [
+ "backend/src/interfaces/admin/",
+ "backend/tests/unit/interfaces/admin/",
+]
+
+[features.admin.contributes]
+installers = ["src.interfaces.admin.initialize:install as admin_install"]
+settings = ["src.interfaces.admin.settings:SQLAdminSettings"]
+
+[features.cache]
+summary = "@cache over Redis or Memcached"
+group = "Operations"
+paths = [
+ "backend/src/infrastructure/cache/",
+ "backend/tests/unit/infrastructure/cache/",
+]
+
+[features.cache.contributes]
+lifecycles = ["src.infrastructure.cache.initialize:lifecycle as cache_lifecycle"]
+settings = ["src.infrastructure.cache.settings:CacheSettings"]
+informational_readiness = ["src.infrastructure.cache.health:readiness as cache_readiness"]
+cache_decorator = ["src.infrastructure.cache.decorator:cache as cached"]
+
+[[features.cache.when]]
+if = "accounts"
+paths = [
+ "backend/tests/unit/infrastructure/cache/test_scoped_callers.py",
+]
+
+[features.cache.options.backend]
+choices = ["redis", "memcached"]
+default = "redis"
+env = { CACHE_BACKEND = "{value}" }
+services = { memcached = ["memcached"] }
+dependencies = { memcached = ["aiomcache>=0.8.2"] }
+
+[features.taskiq]
+summary = "Background tasks on Redis or RabbitMQ"
+group = "Operations"
+services = ["worker", "scheduler"]
+dependencies = [
+ "taskiq>=0.11.20",
+ "taskiq-redis>=1.1.2",
+ "taskiq-aio-pika>=0.4.3",
+ "cryptography>=42.0.0",
+]
+dev_dependencies = ["taskiq[reload]>=0.11.20"]
+paths = [
+ "backend/src/infrastructure/taskiq/",
+ "backend/tests/unit/infrastructure/taskiq/",
+]
+
+[features.taskiq.contributes]
+lifecycles = ["src.infrastructure.taskiq.lifecycle:lifecycle as taskiq_lifecycle"]
+settings = ["src.infrastructure.taskiq.settings:TaskiqSettings"]
+informational_readiness = ["src.infrastructure.taskiq.health:readiness as broker_readiness"]
+
+[features.taskiq.options.broker]
+choices = ["redis", "rabbitmq"]
+default = "redis"
+env = { TASKIQ_BROKER_TYPE = "{value}" }
+services = { rabbitmq = ["rabbitmq"] }
+
+[[features.taskiq.when]]
+if = "accounts"
+paths = [
+ "backend/src/infrastructure/taskiq/email.py",
+ "backend/tests/unit/infrastructure/taskiq/test_email.py",
+]
+contributes.email_sender = ["src.infrastructure.taskiq.email:queued_sender"]
+contributes.task_modules = [{ value = "src.infrastructure.taskiq.email", order = 10 }]
+
+
+[checks.toolchain.env]
+ENVIRONMENT = "local"
+SECRET_KEY = "a-key-only-the-toolchain-checks-run-with"
+SESSION_BACKEND = "memory"
+RATE_LIMITER_BACKEND = "memory"
+
+[wiring_defaults]
+line_length = 128
+header = """Generated by fastro from blueprint.toml and fastro.toml. Don't edit: change
+fastro.toml (or [app] in it, for your own code) and run `fastro sync`."""
+
+[[wiring]]
+path = "backend/src/wiring/settings.py"
+doc = """The project's settings: each selected feature's mixin on top of the core.
+
+Core comes last, so a feature can override a core default rather than the other way round."""
+
+[[wiring.slots]]
+kind = "class"
+name = "Settings"
+point = "settings"
+append = ["src.infrastructure.config.base:CoreSettings"]
+doc = "The settings of every selected feature, on top of the core."
+
+[[wiring.slots]]
+kind = "raw"
+code = "settings = Settings()"
+
+[[wiring]]
+path = "backend/src/wiring/app.py"
+doc = "The composition root: what the app mounts, starts and installs."
+imports = [
+ "from collections.abc import Callable",
+ "from typing import Any",
+ "from fastapi import APIRouter, FastAPI",
+ "from ..infrastructure.composition import Lifecycle, RouterMount",
+]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "ROUTER_MOUNTS"
+point = "routers"
+annotation = "tuple[RouterMount, ...]"
+item = 'RouterMount({name}, "{prefix}", throttled={throttled})'
+
+[[wiring.slots]]
+kind = "value"
+name = "ROOT_ROUTERS"
+point = "root_routers"
+annotation = "tuple[APIRouter, ...]"
+fallback = "()"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "API_THROTTLE"
+point = "api_throttle"
+annotation = "tuple[Any, ...]"
+item = "Depends({name})"
+item_imports = ["from fastapi import Depends"]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "LIFECYCLES"
+point = "lifecycles"
+annotation = "tuple[Lifecycle, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "INSTALLERS"
+point = "installers"
+annotation = "tuple[Callable[[FastAPI], None], ...]"
+
+[[wiring.slots]]
+kind = "value"
+name = "DOCS_GUARD"
+point = "docs_guard"
+annotation = "Callable[..., Any] | None"
+fallback = "None"
+
+[[wiring]]
+path = "backend/src/wiring/hooks.py"
+doc = "The contributions features make to each other's extension points."
+imports = [
+ "from ..infrastructure.composition import PermissionSource, RateLimitResolver, ReadinessCheck, TierDeleteGuard, TierDeleteRelease",
+]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "PERMISSION_SOURCES"
+point = "permission_sources"
+annotation = "tuple[PermissionSource, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "RATE_LIMIT_RESOLVERS"
+point = "rate_limit_resolvers"
+annotation = "tuple[RateLimitResolver, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "TIER_DELETE_GUARDS"
+point = "tier_delete_guards"
+annotation = "tuple[TierDeleteGuard, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "TIER_DELETE_RELEASES"
+point = "tier_delete_releases"
+annotation = "tuple[TierDeleteRelease, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "CRITICAL_READINESS_CHECKS"
+point = "critical_readiness"
+annotation = "tuple[ReadinessCheck, ...]"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "INFORMATIONAL_READINESS_CHECKS"
+point = "informational_readiness"
+annotation = "tuple[ReadinessCheck, ...]"
+
+[[wiring]]
+path = "backend/src/wiring/models.py"
+doc = "Extension points of the user model: what other features add to ``User``."
+
+[[wiring.slots]]
+kind = "class"
+name = "UserModelExtensions"
+point = "user_model"
+doc = "Columns and relationships other features add to ``User``."
+
+[[wiring.slots]]
+kind = "class"
+name = "UserSchemaExtensions"
+point = "user_schema"
+fallback = "pydantic:BaseModel"
+doc = "Fields other features add to the user read schemas."
+
+[[wiring]]
+path = "backend/src/wiring/email.py"
+doc = """The sender the account emails go out through.
+
+It is its own module because ``hooks`` reaches features that import the accounts feature back."""
+imports = ["from crudauth import EmailSender"]
+
+[[wiring.slots]]
+kind = "value"
+name = "EMAIL_SENDER"
+point = "email_sender"
+annotation = "EmailSender"
+fallback = "HandingOverSender(build_sender())"
+fallback_imports = [
+ "from ..infrastructure.email.factory import build_sender",
+ "from ..infrastructure.email.senders import HandingOverSender",
+]
+
+[[wiring]]
+path = "backend/src/wiring/cache.py"
+doc = "The decorator a route caches its response with."
+
+[[wiring.slots]]
+kind = "reexport"
+name = "cached"
+point = "cache_decorator"
+fallback = "src.infrastructure.uncached:cached"
+
+[[wiring]]
+path = "backend/src/wiring/scope.py"
+doc = """What tells a credential that carries a scope apart from its account's others.
+
+It is its own module, importing none of the other wiring, so that whatever keys what it stores by caller can read it."""
+imports = ["from collections.abc import Callable", "from crudauth import Principal"]
+
+[[wiring.slots]]
+kind = "value"
+name = "SCOPE_FINGERPRINT"
+point = "scope_fingerprint"
+annotation = "Callable[[Principal], str | None] | None"
+fallback = "None"
+
+[[wiring]]
+path = "backend/src/wiring/signup.py"
+doc = """The columns features set on an account as it is created, on every signup path.
+
+The account setup reads it, so it is its own module: `wiring/hooks.py` reaches features that import the account setup back."""
+imports = ["from ..infrastructure.composition import NewAccountFields"]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "NEW_ACCOUNT_FIELDS"
+point = "new_account_fields"
+annotation = "tuple[NewAccountFields, ...]"
+
+[[wiring]]
+path = "backend/src/wiring/transports.py"
+doc = "The authentication transports this project registers beside the session one."
+imports = ["from crudauth import Transport"]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "EXTRA_TRANSPORTS"
+point = "extra_transports"
+annotation = "tuple[Transport, ...]"
+
+[[wiring]]
+path = "backend/src/wiring/tasks.py"
+doc = """The modules whose background tasks the worker registers.
+
+A task the worker reports as unknown drops its message, so a module declaring one belongs in this list."""
+
+[[wiring.slots]]
+kind = "tuple"
+name = "TASK_MODULES"
+point = "task_modules"
+annotation = "tuple[str, ...]"
+literal = true
+
+[[wiring]]
+path = "backend/src/wiring/tables.py"
+doc = "Modules outside ``src/modules`` that declare tables on ``Base.metadata``."
+
+[[wiring.slots]]
+kind = "tuple"
+name = "TABLE_MODULES"
+point = "table_modules"
+annotation = "tuple[str, ...]"
+literal = true
+
+[[wiring]]
+path = "backend/src/wiring/admin.py"
+doc = "The model views the admin panel registers."
+if = "admin"
+
+[[wiring.slots]]
+kind = "tuple"
+name = "ADMIN_VIEWS"
+point = "admin_views"
+annotation = "tuple[type, ...]"
+
+[[wiring]]
+path = "backend/scripts/seeders.py"
+doc = "The initial-data steps ``scripts/setup_initial_data.py`` runs, in order."
+imports = ["from collections.abc import Awaitable, Callable"]
+
+[[wiring.slots]]
+kind = "tuple"
+name = "SEEDERS"
+point = "seeders"
+annotation = "tuple[Callable[[], Awaitable[None]], ...]"
+
+[[wiring]]
+path = "backend/tests/wiring.py"
+doc = "Fixture modules of the selected features, loaded by ``tests/conftest.py``."
+
+[[wiring.slots]]
+kind = "list"
+name = "PYTEST_PLUGINS"
+point = "test_plugins"
+annotation = "list[str]"
+literal = true
+
+[generators.deploy]
+templates = "blueprint/templates/deploy"
+modes = ["local", "prod", "nginx"]
+
+[generators.deploy.params.api_port]
+type = "int"
+default = 8000
+help = "Host port to publish the API on."
+
+[generators.deploy.params.workers]
+type = "int"
+default = 4
+help = "Number of API workers, for the prod and nginx modes."
+
+[generators.deploy.params.internal_subnet]
+type = "cidr"
+default = "172.31.240.0/24"
+max_prefix = { v4 = 8, v6 = 48 }
+help = "The compose network, and the only peers uvicorn takes forwarded headers from, in nginx mode."
+
+[commands."env secret"]
+module = "scripts.gen_secret"
+help = "Print a secret key the project's own rules accept."
+outside_project = "token_hex"
+
+[commands."env validate"]
+module = "scripts.validate_env"
+help = "Audit this environment the way production would."
+
+[commands."db baseline"]
+module = "scripts.baseline"
+help = "Write this project's baseline migration, checked against the models."
+
+[commands."db tables"]
+module = "scripts.create_tables"
+help = "Create the tables the models declare, without alembic."
+
+[commands."db seed"]
+module = "scripts.setup_initial_data"
+help = "Run the initial-data steps of the selected features, in order."
diff --git a/blueprint/overlay/.github/workflows/ci.yml.j2 b/blueprint/overlay/.github/workflows/ci.yml.j2
new file mode 100644
index 00000000..f4818f01
--- /dev/null
+++ b/blueprint/overlay/.github/workflows/ci.yml.j2
@@ -0,0 +1,46 @@
+name: CI
+
+on: [push, pull_request]
+
+permissions:
+ contents: read
+
+jobs:
+ check:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@v5
+ with:
+ enable-cache: true
+ cache-dependency-glob: backend/uv.lock
+
+ - name: Set up Python
+ run: uv python install 3.11
+
+ - name: Install
+ run: uv sync --all-extras --locked --project backend --python 3.11
+
+ - name: Lint
+ working-directory: backend
+ run: |
+ uv run --no-sync ruff check .
+ uv run --no-sync ruff format --check .
+
+ - name: Types
+ working-directory: backend
+ run: uv run --no-sync mypy src scripts migrations tests
+
+ - name: Tests
+ working-directory: backend
+ run: uv run --no-sync pytest
+ env:
+ ENVIRONMENT: local
+ SECRET_KEY: a-secret-key-this-run-only-with-32-bytes
+
+ - name: The project matches what it declares
+ run: |
+ uvx fastro@{{ fastro.version }} sync --check
+ uvx fastro@{{ fastro.version }} check
diff --git a/blueprint/overlay/.gitignore b/blueprint/overlay/.gitignore
new file mode 100644
index 00000000..81525504
--- /dev/null
+++ b/blueprint/overlay/.gitignore
@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Configuration: .env.example is the one that is committed
+.env
+.env.*
+!.env.example
+
+# Editors
+.idea/
+.vscode/
+.DS_Store
diff --git a/blueprint/overlay/.pre-commit-config.yaml.j2 b/blueprint/overlay/.pre-commit-config.yaml.j2
new file mode 100644
index 00000000..9cc54f0d
--- /dev/null
+++ b/blueprint/overlay/.pre-commit-config.yaml.j2
@@ -0,0 +1,46 @@
+default_language_version:
+ python: python3.11
+
+repos:
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v6.0.0
+ hooks:
+ - id: end-of-file-fixer
+ - id: trailing-whitespace
+ - id: check-yaml
+ - id: check-case-conflict
+ - id: check-merge-conflict
+ - id: check-added-large-files
+ args: ["--maxkb=750", "--enforce-all"]
+ - id: detect-private-key
+
+ - repo: https://github.com/asottile/pyupgrade
+ rev: v3.20.0
+ hooks:
+ - id: pyupgrade
+ args: [--py311-plus]
+ name: Upgrade code to Python 3.11+
+
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.15.12
+ hooks:
+ - id: ruff-check
+ args: [--fix]
+ - id: ruff-format
+
+ - repo: local
+ hooks:
+ - id: mypy
+ name: Mypy
+ language: system
+ entry: bash -c 'cd backend && uv run --no-sync mypy src scripts migrations tests --config-file pyproject.toml'
+ pass_filenames: false
+ files: ^backend/(src|scripts|migrations|tests)/
+ types: [python]
+
+ - id: wiring
+ name: The wiring matches fastro.toml
+ language: system
+ entry: uvx fastro@{{ fastro.version }} sync --check
+ pass_filenames: false
+ files: ^(fastro\.toml|backend/src/wiring/)
diff --git a/blueprint/overlay/AGENTS.md b/blueprint/overlay/AGENTS.md
new file mode 100644
index 00000000..d64f738b
--- /dev/null
+++ b/blueprint/overlay/AGENTS.md
@@ -0,0 +1,44 @@
+# Working in this project
+
+A FastAPI backend generated from the FastAPI-boilerplate blueprint by fastro. `backend/` holds
+everything that runs.
+
+## The layers
+
+- `src/interfaces/`: the app itself, the FastAPI factory and the routers it mounts.
+- `src/modules//`: one domain each, as `models.py`, `schemas.py`, `crud.py`, `service.py`
+ and `routes.py`. A module owns its tables and its rules, and reaches another module through
+ its service rather than its tables.
+- `src/infrastructure/`: what every module uses, such as the settings and the database, plus
+ whatever each selected feature brought with it.
+- `src/wiring/`: generated. It lists what this project selected, so the app imports one name per
+ extension point instead of asking what exists.
+
+## Adding code
+
+Add a domain as a module under `src/modules/`, following an existing one: the names and the file
+split are the pattern to copy. Register its router and anything else it contributes under
+`[app].contributes` in `fastro.toml`, then run `fastro sync`.
+
+**Never edit `src/wiring/`.** Those files are written from `blueprint.toml` and `fastro.toml`, and
+`fastro sync` overwrites them. To change what is wired, change `[app]` in `fastro.toml` and sync.
+
+A setting of your own goes on a settings class in the module that reads it, contributed under
+`[app].contributes.settings` in `fastro.toml` and picked up by `fastro sync`. Add its variable to
+`backend/.env.example` outside the marked sections, which belong to the features that own them.
+The files under `src/infrastructure/config/` are the blueprint's: a change there is one
+`fastro update` has to merge, so keep your own settings in your module.
+
+## Before finishing
+
+From `backend/`:
+
+```bash
+uv run --no-sync ruff check . && uv run --no-sync ruff format --check .
+uv run --no-sync mypy src scripts migrations tests
+uv run --no-sync pytest
+```
+
+Then `fastro check --json` from the project root, and read what it reports. A schema change needs a
+migration: `uv run --no-sync alembic revision --autogenerate -m "what changed"`, reviewed by hand
+before it is applied.
diff --git a/blueprint/overlay/CLAUDE.md b/blueprint/overlay/CLAUDE.md
new file mode 100644
index 00000000..43c994c2
--- /dev/null
+++ b/blueprint/overlay/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/blueprint/overlay/README.md.j2 b/blueprint/overlay/README.md.j2
new file mode 100644
index 00000000..e965771b
--- /dev/null
+++ b/blueprint/overlay/README.md.j2
@@ -0,0 +1,109 @@
+# {{ project.name }}
+
+A FastAPI backend, generated from the FastAPI-boilerplate blueprint (`{{ blueprint.name }}`
+{{ blueprint.version }}) by fastro {{ fastro.version }}.
+{% if features %}
+Selected: {{ features | join(", ") }}.
+{%- else %}
+Nothing optional is selected: this is the core, and `uvx fastro@{{ fastro.version }} add` brings
+a feature in.
+{%- endif %}
+
+Every command below runs from this directory: the ones in a subshell step into `backend/` and come
+back. `uvx fastro@{{ fastro.version }}` fetches the tool that generated the project, so a checkout
+needs nothing installed first.
+
+## Get it running
+
+```bash
+uv sync --all-extras --project backend
+cp backend/.env.example backend/.env
+uvx fastro@{{ fastro.version }} env secret # put the key it prints in backend/.env
+uvx fastro@{{ fastro.version }} make deploy local # writes the compose files
+docker compose up -d
+```
+
+That stack runs the API{% if has("taskiq") %}, the worker and the scheduler{% endif %} and the data stores it needs, with `backend/src` mounted so a change reloads. Outside production the app builds the schema from the models as it boots, so there is nothing to migrate yet: the API is on , and its docs on `/docs`.
+{%- if has("accounts") %}
+Create the first superuser from the `ADMIN_*` variables in `backend/.env`:
+
+```bash
+docker compose exec api python -m scripts.setup_initial_data
+```
+{%- endif %}
+{%- if has("admin") %}
+
+## The admin panel
+
+It ships switched off. Set `ADMIN_ENABLED=true` in `backend/.env`, with `ADMIN_USERNAME` and
+`ADMIN_PASSWORD` values of your own, and it is served at `/admin`. Without both credentials it
+stays unmounted, whatever the flag says.
+{%- endif %}
+
+## Migrations
+
+When alembic should own the schema instead of the boot-time `create_all`, write the first revision
+from the models and start the database empty, because the one that booted already holds the whole
+schema and an upgrade against it fails on tables that exist:
+
+```bash
+uvx fastro@{{ fastro.version }} db baseline
+docker compose down -v
+```
+
+Set `CREATE_TABLES_ON_STARTUP=false` in `backend/.env`, then bring the stack back: a container
+reads that file as it starts, so an edit needs `up -d` again.
+
+```bash
+docker compose up -d
+docker compose exec api alembic upgrade head
+```
+
+`db baseline` starts a throwaway Postgres of its own, so it runs here rather than in the container,
+and leaves the revision in `backend/migrations/versions/` to commit. To keep what is already in the
+development database instead of dropping it, run `docker compose exec api alembic stamp head`: the
+schema is there, and stamping records it as applied.
+
+## Running the app on your machine
+
+The stack publishes Postgres{% if has("accounts") or has("cache") or has("taskiq") %} and Redis{% endif %} on localhost, so the app can run outside it. Point `POSTGRES_SERVER` and every `*_HOST` in `backend/.env` at `localhost`, then:
+
+```bash
+docker compose stop api{% if has("taskiq") %} worker scheduler{% endif %}
+docker compose up -d postgres{% if has("accounts") or has("cache") or has("taskiq") %} redis{% endif %}
+(cd backend && uv run --no-sync uvicorn src.interfaces.main:app --reload)
+```
+
+The first line frees the port the stack publishes; without it nothing can bind it.
+{%- if has("taskiq") %}
+
+The worker and the scheduler run the same way, against the broker `TASKIQ_BROKER_TYPE` names:
+
+```bash
+(cd backend && uv run --no-sync taskiq worker src.infrastructure.taskiq.worker:default_broker)
+(cd backend && uv run --no-sync taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler)
+```
+{%- endif %}
+
+## Work on it
+
+```bash
+(cd backend && uv run --no-sync ruff check . && uv run --no-sync ruff format --check .)
+(cd backend && uv run --no-sync mypy src scripts migrations tests)
+(cd backend && uv run --no-sync pytest)
+```
+
+`AGENTS.md` says where code goes and what not to edit. From this directory,
+`uvx fastro@{{ fastro.version }} check` reads the project the way CI does, and
+`uvx fastro@{{ fastro.version }} sync --check` tells you whether `src/wiring/` matches
+`fastro.toml`.
+
+## Change what it carries
+
+```bash
+uvx fastro@{{ fastro.version }} features # what is selected, and what else there is
+uvx fastro@{{ fastro.version }} add
+uvx fastro@{{ fastro.version }} remove
+```
+
+Either one rewrites `src/wiring/`, the dependencies and `.env.example`, and says what it changed.
diff --git a/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2 b/blueprint/templates/deploy/local/docker-compose.yml.j2
similarity index 74%
rename from cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2
rename to blueprint/templates/deploy/local/docker-compose.yml.j2
index 7f5d74f5..c2e4e5b1 100644
--- a/cli/src/cli/features/_builtins/deploy/templates/local/docker-compose.yml.j2
+++ b/blueprint/templates/deploy/local/docker-compose.yml.j2
@@ -1,40 +1,40 @@
-# Generated by `bp deploy generate local`.
+# Generated by `fastro make deploy local`.
# Hot-reload dev stack: API + Taskiq worker + Postgres + Redis.
# Source is mounted into the container so file changes trigger a reload.
-name: {{ project_name }}
+name: {{ project.slug }}
services:
api:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: dev
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
RATE_LIMITER_REDIS_HOST: redis
TASKIQ_REDIS_HOST: redis
volumes:
- - {{ backend_context }}/src:/app/src
- - {{ backend_context }}/tests:/app/tests
+ - ./backend/src:/app/src
+ - ./backend/tests:/app/tests
ports:
- - "{{ api_port }}:8000"
+ - "{{ params.api_port }}:8000"
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
-{% if taskiq %}
+{% if "worker" in services %}
worker:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: dev
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -45,21 +45,22 @@ services:
taskiq worker src.infrastructure.taskiq.worker:default_broker
--reload
volumes:
- - {{ backend_context }}/src:/app/src
+ - ./backend/src:/app/src
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
-
+{% endif %}
+{%- if "scheduler" in services %}
# Run exactly one of these: each scheduler fires every schedule it finds.
scheduler:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: dev
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -69,7 +70,7 @@ services:
command: >
taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler
volumes:
- - {{ backend_context }}/src:/app/src
+ - ./backend/src:/app/src
depends_on:
postgres:
condition: service_healthy
@@ -77,9 +78,9 @@ services:
condition: service_healthy
{% endif %}
postgres:
- image: {{ postgres_image }}
+ image: postgres:16-alpine
env_file:
- - {{ env_file }}
+ - ./backend/.env
volumes:
- postgres-data:/var/lib/postgresql/data
ports:
@@ -91,7 +92,7 @@ services:
retries: 10
redis:
- image: {{ redis_image }}
+ image: redis:7-alpine
volumes:
- redis-data:/data
ports:
diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2 b/blueprint/templates/deploy/nginx/docker-compose.yml.j2
similarity index 82%
rename from cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2
rename to blueprint/templates/deploy/nginx/docker-compose.yml.j2
index b5863e7d..b8873080 100644
--- a/cli/src/cli/features/_builtins/deploy/templates/nginx/docker-compose.yml.j2
+++ b/blueprint/templates/deploy/nginx/docker-compose.yml.j2
@@ -1,9 +1,9 @@
-# Generated by `bp deploy generate nginx`.
+# Generated by `fastro make deploy nginx`.
# Production stack with an nginx reverse proxy in front of the API.
# Public traffic enters on port 80 (and 443 once you wire TLS); the
# API container only exposes itself on the internal compose network.
-name: {{ project_name }}
+name: {{ project.slug }}
services:
# One-shot, and nothing waits on it: run it and only then restart the rest, so a
@@ -11,11 +11,11 @@ services:
# docker compose --profile migrate run --rm migrate
migrate:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: migrate
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CONFIRM_PRODUCTION_MIGRATION: "yes"
@@ -27,19 +27,19 @@ services:
api:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
RATE_LIMITER_REDIS_HOST: redis
TASKIQ_REDIS_HOST: redis
TRUSTED_PROXY_HOPS: "1"
- FORWARDED_ALLOW_IPS: "{{ internal_subnet }}"
- WORKERS: "{{ workers }}"
+ FORWARDED_ALLOW_IPS: "{{ params.internal_subnet }}"
+ WORKERS: "{{ params.workers }}"
expose:
- "8000"
depends_on:
@@ -54,14 +54,14 @@ services:
retries: 5
start_period: 20s
restart: unless-stopped
-{% if taskiq %}
+{% if "worker" in services %}
worker:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -75,15 +75,16 @@ services:
redis:
condition: service_healthy
restart: unless-stopped
-
+{% endif %}
+{%- if "scheduler" in services %}
# Run exactly one of these: each scheduler fires every schedule it finds.
scheduler:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -99,7 +100,7 @@ services:
restart: unless-stopped
{% endif %}
nginx:
- image: {{ nginx_image }}
+ image: nginx:1.27-alpine
ports:
- "80:80"
volumes:
@@ -109,9 +110,9 @@ services:
restart: unless-stopped
postgres:
- image: {{ postgres_image }}
+ image: postgres:16-alpine
env_file:
- - {{ env_file }}
+ - ./backend/.env
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
@@ -122,7 +123,7 @@ services:
restart: unless-stopped
redis:
- image: {{ redis_image }}
+ image: redis:7-alpine
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redis-data:/data
@@ -144,4 +145,4 @@ networks:
default:
ipam:
config:
- - subnet: "{{ internal_subnet }}"
+ - subnet: "{{ params.internal_subnet }}"
diff --git a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2 b/blueprint/templates/deploy/nginx/nginx/default.conf.j2
similarity index 87%
rename from cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2
rename to blueprint/templates/deploy/nginx/nginx/default.conf.j2
index 4c06380a..8873337b 100644
--- a/cli/src/cli/features/_builtins/deploy/templates/nginx/default.conf.j2
+++ b/blueprint/templates/deploy/nginx/nginx/default.conf.j2
@@ -1,7 +1,7 @@
-# Generated by `bp deploy generate nginx`.
+# Generated by `fastro make deploy nginx`.
# Drop-in nginx vhost in front of the FastAPI app container.
-upstream {{ project_name }}_api {
+upstream {{ project.slug }}_api {
server api:8000;
}
@@ -27,7 +27,7 @@ server {
proxy_read_timeout 300s;
location / {
- proxy_pass http://{{ project_name }}_api;
+ proxy_pass http://{{ project.slug }}_api;
proxy_redirect off;
}
}
diff --git a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2 b/blueprint/templates/deploy/prod/docker-compose.yml.j2
similarity index 81%
rename from cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2
rename to blueprint/templates/deploy/prod/docker-compose.yml.j2
index 22bec610..d792a5a8 100644
--- a/cli/src/cli/features/_builtins/deploy/templates/prod/docker-compose.yml.j2
+++ b/blueprint/templates/deploy/prod/docker-compose.yml.j2
@@ -1,9 +1,9 @@
-# Generated by `bp deploy generate prod`.
+# Generated by `fastro make deploy prod`.
# Production-ish single-host stack: multi-worker API + Taskiq worker
# + Postgres + Redis. The API is exposed directly on the host port —
# add a reverse proxy (or use the `nginx` mode) before public traffic.
-name: {{ project_name }}
+name: {{ project.slug }}
services:
# One-shot, and nothing waits on it: run it and only then restart the rest, so a
@@ -11,11 +11,11 @@ services:
# docker compose --profile migrate run --rm migrate
migrate:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: migrate
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CONFIRM_PRODUCTION_MIGRATION: "yes"
@@ -27,19 +27,19 @@ services:
api:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
RATE_LIMITER_REDIS_HOST: redis
TASKIQ_REDIS_HOST: redis
- WORKERS: "{{ workers }}"
+ WORKERS: "{{ params.workers }}"
ports:
- - "{{ api_port }}:8000"
+ - "{{ params.api_port }}:8000"
depends_on:
postgres:
condition: service_healthy
@@ -52,14 +52,14 @@ services:
retries: 5
start_period: 20s
restart: unless-stopped
-{% if taskiq %}
+{% if "worker" in services %}
worker:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -73,15 +73,16 @@ services:
redis:
condition: service_healthy
restart: unless-stopped
-
+{% endif %}
+{%- if "scheduler" in services %}
# Run exactly one of these: each scheduler fires every schedule it finds.
scheduler:
build:
- context: {{ build_context }}
- dockerfile: {{ backend_dockerfile }}
+ context: .
+ dockerfile: backend/Dockerfile
target: prod
env_file:
- - {{ env_file }}
+ - ./backend/.env
environment:
POSTGRES_SERVER: postgres
CACHE_REDIS_HOST: redis
@@ -97,9 +98,9 @@ services:
restart: unless-stopped
{% endif %}
postgres:
- image: {{ postgres_image }}
+ image: postgres:16-alpine
env_file:
- - {{ env_file }}
+ - ./backend/.env
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
@@ -110,7 +111,7 @@ services:
restart: unless-stopped
redis:
- image: {{ redis_image }}
+ image: redis:7-alpine
command: ["redis-server", "--appendonly", "yes"]
volumes:
- redis-data:/data
diff --git a/blueprint/tests/conftest.py b/blueprint/tests/conftest.py
new file mode 100644
index 00000000..e13b6c19
--- /dev/null
+++ b/blueprint/tests/conftest.py
@@ -0,0 +1,42 @@
+import shutil
+import subprocess
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+FastroRunner = Callable[..., subprocess.CompletedProcess[str]]
+
+
+@pytest.fixture
+def tracked_tree(tmp_path: Path) -> Path:
+ """A copy of every file git tracks or would track, so a test can change it freely."""
+ destination = tmp_path / "blueprint"
+ listed = subprocess.run(
+ ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+ cwd=REPO_ROOT,
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout
+ for name in filter(None, listed.split("\0")):
+ source = REPO_ROOT / name
+ if source.is_file():
+ (destination / name).parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(source, destination / name)
+
+ return destination
+
+
+@pytest.fixture
+def fastro() -> FastroRunner:
+ """Run the fastro the repository root installs, in a directory of the caller's choosing."""
+
+ def run(*arguments: str, cwd: Path) -> subprocess.CompletedProcess[str]:
+ command = [sys.executable, "-m", "fastro", *arguments]
+ return subprocess.run(command, cwd=cwd, capture_output=True, text=True, check=False)
+
+ return run
diff --git a/blueprint/tests/retired.py b/blueprint/tests/retired.py
new file mode 100644
index 00000000..ef3b8061
--- /dev/null
+++ b/blueprint/tests/retired.py
@@ -0,0 +1,60 @@
+"""The developer CLI this repository used to ship, and the drill that built the repository
+without each feature, as the scans that keep them gone read them.
+
+Every needle is assembled from pieces, so the files that hold them never match themselves.
+"""
+
+import re
+import subprocess
+from collections.abc import Iterator
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+OLD_COMMAND = "b" + "p"
+
+RUNS_OLD_COMMAND = re.compile(rf"\b{OLD_COMMAND} (?:deploy|env)\b|`{OLD_COMMAND}`")
+"""A line that runs the old command, or names it in code."""
+
+NAMES_OLD_COMMAND = re.compile(rf"{RUNS_OLD_COMMAND.pattern}|\brun {OLD_COMMAND}\b|\b{OLD_COMMAND}(?:<[^>]*>)? CLI\b")
+"""A line that runs the old command, names it in code, or calls it a CLI."""
+
+SAYS_OLD_COMMAND_EXITS = re.compile(rf"^`{OLD_COMMAND} deploy generate` exits 2 too, in a project made before fastro\.$")
+"""The one line a reader sees that names the old command: the fastro page saying it is refused."""
+
+OLD_PACKAGE = "c" + "li"
+
+NAMES_OLD_PACKAGE = re.compile(rf"(? Iterator[tuple[str, str]]:
+ """Every file git tracks or would add, that reads as UTF-8, by its path from the root, with its text."""
+ listed = subprocess.run(
+ ["git", "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+ cwd=REPO_ROOT,
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+ for name in filter(None, listed.stdout.split("\0")):
+ path = REPO_ROOT / name
+ if not path.is_file():
+ continue
+ try:
+ yield name, path.read_text(encoding="utf-8")
+ except UnicodeDecodeError:
+ continue
+
+
+def shown_pages() -> Iterator[tuple[str, str]]:
+ """The Markdown a reader sees: the README and the docs, the changelog's history aside."""
+ for name, text in tracked_text():
+ if name == "README.md" or (name.startswith("docs/") and name.endswith(".md") and name != "docs/changelog.md"):
+ yield name, text
diff --git a/blueprint/tests/test_deploy_generator.py b/blueprint/tests/test_deploy_generator.py
new file mode 100644
index 00000000..5cc2e62e
--- /dev/null
+++ b/blueprint/tests/test_deploy_generator.py
@@ -0,0 +1,29 @@
+"""The catalog's `[generators.deploy]` modes, against the template trees and what `fastro make deploy` offers."""
+
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+GENERATOR = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())["generators"]["deploy"]
+
+
+def test_the_deploy_modes_are_the_template_trees_and_the_ones_fastro_offers():
+ """A mode with no template tree would be offered and then fail; a tree with no mode is dead."""
+ templates = REPO_ROOT / GENERATOR["templates"]
+ offered = subprocess.run(
+ [sys.executable, "-m", "fastro", "make", "deploy", "--help"], cwd=REPO_ROOT, capture_output=True, text=True
+ )
+
+ assert sorted(child.name for child in templates.iterdir() if child.is_dir()) == sorted(GENERATOR["modes"])
+ assert f"Modes: {', '.join(GENERATOR['modes'])}" in offered.stdout
+
+
+def test_the_nginx_config_sits_where_the_nginx_compose_file_mounts_it():
+ """Files are written relative to the mode's tree, and the compose file mounts ./nginx/default.conf."""
+ tree = REPO_ROOT / GENERATOR["templates"] / "nginx"
+ compose = (tree / "docker-compose.yml.j2").read_text()
+
+ assert (tree / "nginx" / "default.conf.j2").is_file()
+ assert "./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro" in compose
diff --git a/cli/tests/test_deploy_templates.py b/blueprint/tests/test_deploy_templates.py
similarity index 61%
rename from cli/tests/test_deploy_templates.py
rename to blueprint/tests/test_deploy_templates.py
index 131b47e6..707c5a35 100644
--- a/cli/tests/test_deploy_templates.py
+++ b/blueprint/tests/test_deploy_templates.py
@@ -1,40 +1,60 @@
-"""What the generated compose files say about running this app behind a proxy."""
+"""What the generated compose files say about running this app behind a proxy.
+The templates are rendered with the generator context of catalog spec 6.2, under
+``StrictUndefined``: a template that reaches for anything the tool doesn't pass fails here.
+"""
+
+import tomllib
from pathlib import Path
+from typing import Any
import pytest
import yaml
-from jinja2 import Environment, FileSystemLoader
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())
+
+TEMPLATES = Path(__file__).resolve().parents[1] / "templates" / "deploy"
-from cli.features._builtins.deploy.feature import DEFAULT_INTERNAL_SUBNET
+INTERNAL_SUBNET = "172.31.240.0/24"
+"""The default of the ``internal_subnet`` param."""
-TEMPLATES = Path(__file__).resolve().parents[1] / "src/cli/features/_builtins/deploy/templates"
+TASKIQ_SERVICES = ("scheduler", "worker")
+"""What the taskiq feature puts in ``services``."""
-CONTEXT = {
- "mode": "nginx",
- "project_name": "example",
- "api_port": 8000,
- "workers": 4,
- "postgres_image": "postgres:16-alpine",
- "redis_image": "redis:7-alpine",
- "nginx_image": "nginx:1.27-alpine",
- "backend_context": "./backend",
- "build_context": ".",
- "backend_dockerfile": "backend/Dockerfile",
- "env_file": "./backend/.env",
- "internal_subnet": DEFAULT_INTERNAL_SUBNET,
- "taskiq": True,
-}
+def _context(
+ features: tuple[str, ...] = ("accounts", "taskiq"),
+ services: tuple[str, ...] = TASKIQ_SERVICES,
+ **params: Any,
+) -> dict[str, Any]:
+ """The spec 6.2 context, as the tool builds it for a generator."""
+ return {
+ "project": {"name": "example", "slug": "example"},
+ "blueprint": {"name": CATALOG["blueprint"]["name"], "version": CATALOG["blueprint"]["version"]},
+ "fastro": {"version": "0.1.0"},
+ "features": list(features),
+ "options": {},
+ "services": sorted(services),
+ "params": {"api_port": 8000, "workers": 4, "internal_subnet": INTERNAL_SUBNET, **params},
+ "has": lambda name: name in features,
+ }
-def _render(template: str, mode: str = "nginx", **overrides) -> str:
- environment = Environment(loader=FileSystemLoader(TEMPLATES), keep_trailing_newline=True)
- return environment.get_template(template).render({**CONTEXT, "mode": mode, **overrides})
+def _render(template: str, **overrides: Any) -> str:
+ environment = Environment(
+ loader=FileSystemLoader(TEMPLATES),
+ keep_trailing_newline=True,
+ undefined=StrictUndefined,
+ )
+ return environment.get_template(template).render(_context(**overrides))
-def _compose(mode: str, **overrides) -> dict:
- return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", mode, **overrides))
+
+def _compose(mode: str, **overrides: Any) -> dict:
+ return yaml.safe_load(_render(f"{mode}/docker-compose.yml.j2", **overrides))
@pytest.mark.parametrize("mode", ["prod", "nginx"])
@@ -62,12 +82,12 @@ def test_forwarded_headers_are_trusted_only_from_the_compose_network():
"""With a wildcard, uvicorn reads the leftmost X-Forwarded-For entry, which the client sets."""
compose = _compose("nginx")
- assert compose["services"]["api"]["environment"]["FORWARDED_ALLOW_IPS"] == DEFAULT_INTERNAL_SUBNET
- assert compose["networks"]["default"]["ipam"]["config"] == [{"subnet": DEFAULT_INTERNAL_SUBNET}]
+ assert compose["services"]["api"]["environment"]["FORWARDED_ALLOW_IPS"] == INTERNAL_SUBNET
+ assert compose["networks"]["default"]["ipam"]["config"] == [{"subnet": INTERNAL_SUBNET}]
def test_nginx_hides_its_version():
- assert "server_tokens off;" in _render("nginx/default.conf.j2")
+ assert "server_tokens off;" in _render("nginx/nginx/default.conf.j2")
def test_the_local_compose_does_not_claim_a_proxy():
@@ -87,16 +107,16 @@ def test_the_local_compose_publishes_its_databases_to_the_host_only():
def test_nginx_sends_only_the_address_it_saw():
"""A client's own X-Forwarded-For must not reach the app as its address."""
- conf = _render("nginx/default.conf.j2")
+ conf = _render("nginx/nginx/default.conf.j2")
assert "proxy_set_header X-Forwarded-For $remote_addr;" in conf
assert "$proxy_add_x_forwarded_for" not in conf
def test_the_compose_network_quotes_the_subnet():
- rendered = _render("nginx/docker-compose.yml.j2", "nginx")
+ rendered = _render("nginx/docker-compose.yml.j2")
- assert f'- subnet: "{DEFAULT_INTERNAL_SUBNET}"' in rendered
+ assert f'- subnet: "{INTERNAL_SUBNET}"' in rendered
SCHEDULER_COMMAND = "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler"
@@ -113,7 +133,7 @@ def test_a_project_with_taskiq_gets_one_scheduler(mode: str):
@pytest.mark.parametrize("mode", ["local", "prod", "nginx"])
def test_a_project_without_taskiq_gets_neither_worker_nor_scheduler(mode: str):
- services = _compose(mode, taskiq=False)["services"]
+ services = _compose(mode, features=("accounts",), services=())["services"]
assert "worker" not in services
assert "scheduler" not in services
@@ -157,3 +177,26 @@ def test_the_database_probe_reads_the_user_inside_the_container(mode: str):
probe = " ".join(_compose(mode)["services"]["postgres"]["healthcheck"]["test"])
assert "$${POSTGRES_USER" in probe
+
+
+@pytest.mark.parametrize("mode", ["local", "prod", "nginx"])
+def test_the_compose_project_is_named_after_the_project(mode: str):
+ """The slug is what compose accepts as a project name, and what the nginx upstream is keyed on."""
+ assert _compose(mode)["name"] == "example"
+
+
+def test_the_api_runs_the_workers_the_params_asked_for():
+ """``workers`` and ``api_port`` are generator params, so a flag has to reach the template."""
+ compose = _compose("prod", workers=7, api_port=9001)
+
+ assert compose["services"]["api"]["environment"]["WORKERS"] == "7"
+ assert compose["services"]["api"]["ports"] == ["9001:8000"]
+
+
+@pytest.mark.parametrize("mode", ["local", "prod", "nginx"])
+def test_each_background_service_follows_its_own_entry(mode: str):
+ """The blocks are keyed on ``services``, not on the feature, so one without the other works."""
+ services = _compose(mode, services=("worker",))["services"]
+
+ assert "worker" in services
+ assert "scheduler" not in services
diff --git a/blueprint/tests/test_docs_commands.py b/blueprint/tests/test_docs_commands.py
new file mode 100644
index 00000000..7050ab56
--- /dev/null
+++ b/blueprint/tests/test_docs_commands.py
@@ -0,0 +1,228 @@
+"""The commands the README and the docs tell a reader to run are ones the pinned fastro has."""
+
+import re
+import shlex
+import tomllib
+from collections.abc import Iterator
+
+import click
+import pytest
+import typer.main
+from fastro import make as making
+from fastro.cli import app
+from fastro.engine import blueprint
+from fastro.tools import installed_version
+from fastro.verify import verify_sets
+from retired import OLD_COMMAND, OLD_DRILL, REPO_ROOT, RUNS_OLD_COMMAND, SAYS_OLD_COMMAND_EXITS, shown_pages
+
+
+def _fastro() -> click.Group:
+ command = typer.main.get_command(app)
+ assert isinstance(command, click.Group)
+
+ return command
+
+
+FASTRO = _fastro()
+
+LAUNCHERS = (("uv", "run", "--no-sync"), ("uv", "run"), ("uvx",), ("python", "-m"))
+
+STOPS = {"|", "&&", "||", ";"}
+
+
+def _code(text: str) -> Iterator[tuple[str, bool]]:
+ """Every line of every fenced block, a commented-out alternative included, and every inline
+ code span outside them, each with whether it is a line a reader runs."""
+ fenced = False
+ for line in text.splitlines():
+ if line.lstrip().startswith("```"):
+ fenced = not fenced
+ elif fenced:
+ yield re.sub(r"^\s*#\s*(?:or:\s*)?", "", line), True
+ else:
+ yield from ((span, False) for span in re.findall(r"`([^`\n]+)`", line))
+
+
+def _fastro_words(code: str) -> list[str] | None:
+ """The words after `fastro` when the code runs it, through any launcher; `None` when it doesn't."""
+ lexer = shlex.shlex(code.strip().removeprefix("$ "), posix=True, punctuation_chars=True)
+ lexer.whitespace_split = True
+ try:
+ words = list(lexer)
+ except ValueError:
+ return None
+ for index, word in enumerate(words):
+ if word in STOPS:
+ words = words[:index]
+ break
+ for launcher in LAUNCHERS:
+ if tuple(words[: len(launcher)]) == launcher:
+ words = words[len(launcher) :]
+ break
+ if not words or words[0].split("@")[0] != "fastro":
+ return None
+
+ return words[1:]
+
+
+def _commands() -> list[tuple[str, list[str], bool]]:
+ return [
+ (f"{name}: {code.strip()}", words, runs)
+ for name, text in shown_pages()
+ for code, runs in _code(text)
+ if (words := _fastro_words(code)) is not None
+ ]
+
+
+def _refusal(words: list[str], runs: bool = True) -> str | None:
+ """Why the pinned fastro would refuse these words, or `None` when it takes them.
+
+ A command named in a sentence, with nothing after it, only has to exist; a line a reader
+ runs has to parse."""
+ command: click.Command = FASTRO
+ remaining = list(words)
+ while isinstance(command, click.Group) and remaining and not remaining[0].startswith("-"):
+ if remaining[0] not in command.commands:
+ return f"{command.name} has no command {remaining[0]!r}"
+ command = command.commands[remaining.pop(0)]
+ if isinstance(command, click.Group) and remaining:
+ return f"{command.name} takes a command before {remaining[0]!r}"
+ if command is FASTRO.commands["make"]:
+ return _make_refusal(remaining, runs)
+ if not remaining and not runs:
+ return None
+ try:
+ command.make_context(command.name, remaining)
+ except click.ClickException as refused:
+ return refused.format_message()
+
+ return None
+
+
+def _make_refusal(words: list[str], runs: bool) -> str | None:
+ """Why `fastro make` would refuse these words: it reads them itself, against this blueprint's generators."""
+ if not words or words[0] == making.HELP:
+ return None
+ catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version())
+ if not runs and len(words) <= 1:
+ return None if not words or words[0] in catalog.generators else f"make has no generator {words[0]!r}"
+ try:
+ making.parse(catalog, words)
+ except (making.UsageError, making.Refused) as refused:
+ return str(refused)
+
+ return None
+
+
+def test_no_page_a_reader_sees_runs_the_retired_command():
+ """B3 item 2 removes the old developer CLI; every command it ran is a fastro command now."""
+ found = [
+ f"{name}:{number}"
+ for name, text in shown_pages()
+ for number, line in enumerate(text.splitlines(), 1)
+ if RUNS_OLD_COMMAND.search(line) and not (name == "docs/user-guide/fastro.md" and SAYS_OLD_COMMAND_EXITS.match(line))
+ ]
+
+ assert not found, found
+
+
+def test_no_code_block_a_reader_sees_runs_the_drill():
+ """A page may still name it in prose, but a block a reader copies runs fastro."""
+ found = [
+ f"{name}: {code.strip()}" for name, text in shown_pages() for code, runs in _code(text) if runs and OLD_DRILL in code
+ ]
+
+ assert found == []
+
+
+def test_the_pages_show_fastro_commands():
+ """The rule below has something to read, so a reader that stopped finding commands would show."""
+ assert any(words[:2] == ["make", "deploy"] and runs for _, words, runs in _commands())
+
+
+@pytest.mark.parametrize(("where", "words", "runs"), _commands(), ids=[where for where, _, _ in _commands()])
+def test_every_fastro_command_a_page_shows_is_one_the_pinned_fastro_takes(where: str, words: list[str], runs: bool):
+ assert _refusal(words, runs) is None, (where, _refusal(words, runs))
+
+
+FENCE = "`" * 3
+
+
+@pytest.mark.parametrize(
+ ("page", "refused"),
+ [
+ (f"{FENCE}bash\nuv run --no-sync fastro make deploy prod --wokers 8\n{FENCE}", True),
+ ("Run `fastro env gen-secret`.", True),
+ ("Run `fastro make deploy prodd`.", True),
+ ("Run `fastro env secret --bytes 8`.", True),
+ ("Run `fastro make deploy prod --workers many`.", True),
+ ("Run `fastro make deploy prod extra`.", True),
+ (f"{FENCE}bash\n# or: uv run --no-sync fastro make deploy prodd\n{FENCE}", True),
+ (f"{FENCE}bash\nuv run --no-sync fastro make deploy # writes the compose file\n{FENCE}", True),
+ ("`fastro make deploy` writes it.", False),
+ ("Run `fastro make deploy --workers 8 prod`.", True),
+ ("Run `fastro make deploy prod --workers 8`.", False),
+ ("Run `fastro make deploy local --internal-subnet '*'`.", True),
+ ("Run `fastro make deploy prod|cat`.", False),
+ (f"{FENCE}bash\nuv run --no-sync fastro make\n{FENCE}", False),
+ ("Run `fastro make --help`.", False),
+ (f"{FENCE}bash\n# or: uv run --no-sync fastro make deploy prod\n{FENCE}", False),
+ (f"{FENCE}bash\n$ uv run --no-sync fastro env secret --bytes 16 | gh secret set SECRET_KEY\n{FENCE}", False),
+ ("Run `uv run --no-sync fastro make deploy nginx --internal-subnet=10.89.0.0/24 --dry-run`.", False),
+ (f"{FENCE}bash\nfastro sync --check # in the blueprint repo\n{FENCE}", False),
+ ],
+)
+def test_the_reader_refuses_what_fastro_would(page: str, refused: bool):
+ read = [(words, runs) for code, runs in _code(page) if (words := _fastro_words(code)) is not None]
+
+ assert len(read) == 1, read
+ assert (_refusal(*read[0]) is not None) is refused
+
+
+@pytest.mark.parametrize(
+ ("line", "runs"),
+ [
+ (f"uv run --no-sync {OLD_COMMAND} env validate", True),
+ (f"the `{OLD_COMMAND}` tool", True),
+ (f"{OLD_COMMAND}-and-fastro", False),
+ ("redis-cli ping", False),
+ ],
+)
+def test_the_old_command_is_read_where_it_runs(line: str, runs: bool):
+ assert bool(RUNS_OLD_COMMAND.search(line)) is runs
+
+
+def test_every_root_sync_a_page_shows_installs_the_backend():
+ """The root project doesn't depend on the backend, so `--all-packages` is what installs it."""
+ root = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text())
+ backend = tomllib.loads((REPO_ROOT / "backend" / "pyproject.toml").read_text())["project"]["name"]
+ groups = root.get("dependency-groups", {}).values()
+ requirements = [*root["project"].get("dependencies", []), *(requirement for group in groups for requirement in group)]
+ pages = [*shown_pages(), ("CONTRIBUTING.md", (REPO_ROOT / "CONTRIBUTING.md").read_text())]
+ syncs = [
+ f"{name}: {code.strip()}" for name, text in pages for code, _ in _code(text) if code.strip().startswith("uv sync ")
+ ]
+
+ assert not [requirement for requirement in requirements if re.match(rf"{re.escape(backend)}(?![\w.-])", requirement)]
+ assert syncs
+ assert [sync for sync in syncs if "--all-packages" not in sync.split()] == []
+
+
+def _verify_sets() -> set[str]:
+ catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version())
+
+ return set(verify_sets(catalog))
+
+
+def test_every_set_a_page_verifies_is_one_verify_builds():
+ named = [
+ (name, word)
+ for name, text in shown_pages()
+ for code, runs in _code(text)
+ if runs and (words := _fastro_words(code)) and words[:2] == ["blueprint", "verify"]
+ for word in words[2:]
+ if not word.startswith("-")
+ ]
+
+ assert named
+ assert [(name, word) for name, word in named if word not in _verify_sets()] == []
diff --git a/blueprint/tests/test_docs_links.py b/blueprint/tests/test_docs_links.py
new file mode 100644
index 00000000..5ac75306
--- /dev/null
+++ b/blueprint/tests/test_docs_links.py
@@ -0,0 +1,129 @@
+"""Every link between the docs pages lands on a page, and on a heading when it names one.
+
+zensical builds with `toc` and no custom slugify, so a heading's id is Python-Markdown's default
+slug of its text, or the `{#id}` it sets.
+"""
+
+import re
+import tomllib
+import unicodedata
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+import pytest
+from retired import OLD_PACKAGE
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+DOCS = REPO_ROOT / "docs"
+SITE = tomllib.loads((REPO_ROOT / "zensical.toml").read_text())["project"]
+
+LINK = re.compile(r"!?\[[^\]]*\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")
+
+
+def _pages() -> list[Path]:
+ return sorted(DOCS.rglob("*.md"))
+
+
+def _outside_fences(text: str) -> Iterator[tuple[int, str]]:
+ fenced = False
+ for number, line in enumerate(text.splitlines(), 1):
+ if line.lstrip().startswith("```"):
+ fenced = not fenced
+ elif not fenced:
+ yield number, line
+
+
+def slug(heading: str) -> str:
+ """Python-Markdown's default `toc` slug of a heading's text."""
+ text = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", heading)
+ text = re.sub(r"[`*]", "", text)
+ text = unicodedata.normalize("NFKD", text).encode("ascii", "ignore").decode("ascii")
+ text = re.sub(r"[^\w\s-]", "", text).strip().lower()
+
+ return re.sub(r"[-\s]+", "-", text)
+
+
+def _anchors(page: Path) -> set[str]:
+ anchors = set()
+ for _, line in _outside_fences(page.read_text()):
+ heading = re.match(r"^#{1,6}\s+(.*?)\s*$", line)
+ if not heading:
+ continue
+ given = re.search(r"\{[^}]*#([\w-]+)[^}]*\}\s*$", heading[1])
+ anchors.add(given[1] if given else slug(heading[1]))
+
+ return anchors
+
+
+def _links() -> list[tuple[str, str]]:
+ return [
+ (f"{page.relative_to(DOCS)}:{number}", target)
+ for page in _pages()
+ for number, line in _outside_fences(page.read_text())
+ for target in LINK.findall(re.sub(r"`[^`]*`", "", line))
+ if not re.match(r"^[a-z]+:", target)
+ ]
+
+
+def _resolved(where: str, target: str) -> tuple[Path, str]:
+ page = DOCS / where.rsplit(":", 1)[0]
+ path, _, anchor = target.partition("#")
+
+ return ((page.parent / path).resolve() if path else page), anchor
+
+
+def test_the_docs_link_to_one_another():
+ """The rule below has links to read."""
+ assert len(_links()) > 50
+
+
+@pytest.mark.parametrize(("where", "target"), _links(), ids=[f"{where} {target}" for where, target in _links()])
+def test_every_relative_link_lands_on_a_file_and_a_heading(where: str, target: str):
+ path, anchor = _resolved(where, target)
+
+ assert path.is_file(), (where, target)
+ if anchor and path.suffix == ".md":
+ assert anchor in _anchors(path), (where, target, sorted(_anchors(path)))
+
+
+def _nav_pages(entries: Any) -> Iterator[str]:
+ if isinstance(entries, str):
+ yield entries
+ elif isinstance(entries, list):
+ for entry in entries:
+ yield from _nav_pages(entry)
+ elif isinstance(entries, dict):
+ for value in entries.values():
+ yield from _nav_pages(value)
+
+
+def test_every_page_is_in_the_nav_and_every_nav_entry_is_a_page():
+ listed = sorted(_nav_pages(SITE["nav"]))
+
+ assert sorted(set(listed)) == listed, "a page listed twice"
+ assert listed == sorted(page.relative_to(DOCS).as_posix() for page in _pages())
+
+
+def test_every_redirect_leaves_a_page_that_is_gone_for_one_that_is_there():
+ redirects = SITE["plugins"]["redirects"]["redirect_maps"]
+
+ assert redirects == {f"{OLD_PACKAGE}/{page}.md": "user-guide/fastro.md" for page in ("index", "commands", "plugins")}
+ for gone, there in redirects.items():
+ assert not (DOCS / gone).exists(), gone
+ assert (DOCS / there).is_file(), there
+
+
+@pytest.mark.parametrize(
+ ("heading", "expected"),
+ [
+ ("Authentication & Security", "authentication-security"),
+ ("Writing the compose files: `fastro make deploy`", "writing-the-compose-files-fastro-make-deploy"),
+ ("What `fastro make deploy local` Writes", "what-fastro-make-deploy-local-writes"),
+ ("Neon (Serverless Postgres)", "neon-serverless-postgres"),
+ ("Generating a Strong `SECRET_KEY`", "generating-a-strong-secret_key"),
+ ("Café Résumé", "cafe-resume"),
+ ],
+)
+def test_the_slug_is_the_one_toc_writes(heading: str, expected: str):
+ assert slug(heading) == expected
diff --git a/blueprint/tests/test_docs_settings.py b/blueprint/tests/test_docs_settings.py
new file mode 100644
index 00000000..d13bfc3c
--- /dev/null
+++ b/blueprint/tests/test_docs_settings.py
@@ -0,0 +1,131 @@
+"""The settings pattern the docs show is the one the project's settings use."""
+
+import ast
+import importlib
+import re
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+import pytest
+from retired import REPO_ROOT, shown_pages
+
+BASE = REPO_ROOT / "backend" / "src" / "infrastructure" / "config" / "base.py"
+SETTINGS_PAGE = REPO_ROOT / "docs" / "user-guide" / "configuration" / "settings-classes.md"
+BASE_IMPORTS = {"from src.infrastructure.config.base import EnvSettings"}
+FENCED_PYTHON = re.compile(r"^\s*```python\n(.*?)^\s*```", re.M | re.S)
+
+
+def _python_blocks() -> list[tuple[str, str]]:
+ return [(name, block) for name, text in shown_pages() for block in FENCED_PYTHON.findall(text)]
+
+
+def test_the_pages_show_settings_classes():
+ """The rules below have code to read."""
+ assert any("EnvSettings" in block for _, block in _python_blocks())
+
+
+def test_no_block_reads_a_setting_through_the_import_time_loader():
+ found = [name for name, block in _python_blocks() if re.search(r"=\s*config\(\s*[\"']", block)]
+
+ assert found == []
+
+
+def test_no_block_derives_a_settings_group_from_basesettings_directly():
+ found = [name for name, block in _python_blocks() if re.search(r"^\s*class \w+\(BaseSettings\):", block, re.M)]
+
+ assert found == []
+
+
+def test_the_base_the_page_names_is_where_it_says():
+ defined = {node.name for node in ast.parse(BASE.read_text()).body if isinstance(node, ast.ClassDef)}
+
+ assert "`EnvSettings` in `src/infrastructure/config/base.py`" in SETTINGS_PAGE.read_text()
+ assert "EnvSettings" in defined
+
+
+@contextmanager
+def _backend_importable() -> Iterator[None]:
+ sys.path.insert(0, str(REPO_ROOT / "backend"))
+ try:
+ yield
+ finally:
+ sys.path.remove(str(REPO_ROOT / "backend"))
+
+
+def _base() -> Any:
+ """`src.infrastructure.config.base`, imported from the backend."""
+ with _backend_importable():
+ return importlib.import_module("src.infrastructure.config.base")
+
+
+def _section(heading: str) -> str:
+ text = SETTINGS_PAGE.read_text()
+ assert heading in text, heading
+
+ return text.split(heading, 1)[1].split("\n## ", 1)[0]
+
+
+def test_the_page_s_own_example_reads_a_value_set_after_it_is_defined(monkeypatch: pytest.MonkeyPatch):
+ block = FENCED_PYTHON.findall(_section("### Basic Custom Group"))[0]
+ example = block.split("\nclass Settings(", 1)[0]
+ scope: dict[str, Any] = {}
+ with _backend_importable():
+ exec(compile(example, "settings-classes.md", "exec"), scope)
+
+ assert "from src.infrastructure.config.base import EnvSettings" in example
+ assert scope["StorageSettings"].__mro__[1] is _base().EnvSettings
+
+ monkeypatch.setenv("STORAGE_BACKEND", "s3")
+
+ assert scope["StorageSettings"]().STORAGE_BACKEND == "s3"
+
+
+def test_the_validator_the_page_shows_is_the_one_the_database_settings_use():
+ anatomy = _section("## Anatomy of a Settings Group")
+ database = next(
+ node for node in ast.parse(BASE.read_text()).body if isinstance(node, ast.ClassDef) and node.name == "DatabaseSettings"
+ )
+ before = [
+ method.name
+ for method in database.body
+ if isinstance(method, ast.FunctionDef)
+ and any("model_validator(mode='before')" in ast.unparse(decorator) for decorator in method.decorator_list)
+ ]
+
+ assert before == ["_tables_follow_the_environment"]
+ assert '@model_validator(mode="before")' in anatomy and "def _tables_follow_the_environment" in anatomy
+
+
+def test_the_file_reads_the_way_the_page_says(monkeypatch: pytest.MonkeyPatch, tmp_path: Path):
+ key_points = _section("## Anatomy of a Settings Group")
+ stored = tmp_path / ".env"
+ stored.write_text("APP_NAME=ab${HOME}cd # kept\n")
+ monkeypatch.delenv("APP_NAME", raising=False)
+
+ assert "no `${...}` expansion" in key_points and "a `#` is part of the value" in key_points
+ assert _base().AppSettings(_env_file=stored).APP_NAME == "ab${HOME}cd # kept"
+
+
+def test_every_block_that_imports_the_base_takes_it_from_where_the_mixins_do():
+ imports = [line.strip() for _, block in _python_blocks() for line in block.splitlines() if "import EnvSettings" in line]
+
+ assert imports
+ assert [line for line in imports if line.split("#", 1)[0].strip() not in BASE_IMPORTS] == []
+
+
+def test_a_flag_and_a_number_read_the_way_the_page_says(monkeypatch: pytest.MonkeyPatch):
+ key_points = _section("## Anatomy of a Settings Group")
+
+ class Probe(_base().EnvSettings): # type: ignore[misc,name-defined]
+ DOC_FLAG: bool = False
+ DOC_COUNT: int = 0
+
+ assert "`true`, `false`, `1` or `0`" in key_points and "`int()`" in key_points
+ for name, written in (("DOC_FLAG", "yes"), ("DOC_COUNT", "1.0")):
+ monkeypatch.setenv(name, written)
+ with pytest.raises(ValueError):
+ Probe()
+ monkeypatch.delenv(name)
diff --git a/blueprint/tests/test_fastro.py b/blueprint/tests/test_fastro.py
new file mode 100644
index 00000000..e6e5ec34
--- /dev/null
+++ b/blueprint/tests/test_fastro.py
@@ -0,0 +1,23 @@
+"""What the fastro the repository root installs gives the people who work on the blueprint."""
+
+import tomllib
+from pathlib import Path
+
+from conftest import FastroRunner
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def test_plain_sync_regenerates_what_the_check_compares(tracked_tree: Path, fastro: FastroRunner):
+ """CONTRIBUTING.md sends a failed `fastro sync --check` to `fastro sync`."""
+ tree = tracked_tree
+ wiring = tree / tomllib.loads((tree / "blueprint.toml").read_text())["wiring"][0]["path"]
+ generated = wiring.read_text()
+ wiring.write_text(generated + "\nedited = True\n")
+
+ assert fastro("sync", "--check", cwd=tree).returncode == 1
+
+ synced = fastro("sync", cwd=tree)
+
+ assert synced.returncode == 0, synced.stderr
+ assert fastro("sync", "--check", cwd=tree).returncode == 0
diff --git a/blueprint/tests/test_fastro_page.py b/blueprint/tests/test_fastro_page.py
new file mode 100644
index 00000000..866a0672
--- /dev/null
+++ b/blueprint/tests/test_fastro_page.py
@@ -0,0 +1,424 @@
+"""What the fastro page states about fastro's commands and the compose files they write.
+
+The files are rendered through `fastro make deploy ` in this repository, from the catalog's
+`[generators.deploy]`, so a template fastro doesn't see because git doesn't track it is missing here.
+"""
+
+import hashlib
+import importlib.util
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import click
+import pytest
+import typer.main
+import yaml
+from fastro.cli import app
+from jinja2 import Environment, FileSystemLoader, StrictUndefined
+from retired import OLD_COMMAND
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+PAGE = REPO_ROOT / "docs" / "user-guide" / "fastro.md"
+PRODUCTION = REPO_ROOT / "docs" / "user-guide" / "production.md"
+CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())
+GENERATOR = CATALOG["generators"]["deploy"]
+MODES = GENERATOR["modes"]
+
+FASTRO = typer.main.get_command(app)
+MAKE_DEPLOY = "## Writing the compose files: `fastro make deploy`"
+ENV = "## Preparing the environment: `fastro env`"
+PROJECT_TOML = 'features = []\nblueprint = { name = "fastapi-boilerplate", version = "0.20.0" }\n\n[project]\nname = "my-app"\n'
+
+
+def _fastro(*args: str, cwd: Path = REPO_ROOT) -> subprocess.CompletedProcess[str]:
+ return subprocess.run(
+ [sys.executable, "-m", "fastro", *args], cwd=cwd, capture_output=True, text=True, stdin=subprocess.DEVNULL
+ )
+
+
+def _made(mode: str, out: Path, *flags: str) -> dict[str, str]:
+ """What `fastro make deploy ` writes into ``out``, by path."""
+ run = _fastro("make", "deploy", mode, "--output-dir", str(out), "--force", *flags)
+ assert run.returncode == 0, run.stdout + run.stderr
+
+ return {path.relative_to(out).as_posix(): path.read_text() for path in sorted(out.rglob("*")) if path.is_file()}
+
+
+def _compose(mode: str, out: Path, *flags: str) -> dict[str, Any]:
+ return dict(yaml.safe_load(_made(mode, out, *flags)["docker-compose.yml"]))
+
+
+def _command(*words: str) -> click.Command:
+ command: click.Command = FASTRO
+ for word in words:
+ assert isinstance(command, click.Group)
+ command = command.commands[word]
+
+ return command
+
+
+def _section(heading: str) -> str:
+ text = PAGE.read_text()
+ assert heading in text, heading
+
+ return " ".join(text.split(heading, 1)[1].split("\n## ", 1)[0].split())
+
+
+def _rows() -> list[list[str]]:
+ """The body rows of the tables under `fastro make deploy`, as their cells."""
+ text = PAGE.read_text().split(MAKE_DEPLOY, 1)[1].split("\n## ", 1)[0]
+ rows = [line for line in text.splitlines() if line.startswith("|") and not re.fullmatch(r"\|[-| ]+\|", line)]
+ headers = ("| Mode |", "| Option |")
+
+ return [[cell.strip() for cell in row.strip("|").split("|")] for row in rows if not row.startswith(headers)]
+
+
+def _ticked(cell: str) -> list[str]:
+ return re.findall(r"`([^`]+)`", cell)
+
+
+def _mode_rows() -> dict[str, list[str]]:
+ return {_ticked(row[0])[0]: row for row in _rows() if not row[0].startswith("`-")}
+
+
+def _option_rows() -> dict[str, list[str]]:
+ return {_ticked(row[0])[0]: row for row in _rows() if row[0].startswith("`-")}
+
+
+def _help_flags() -> list[list[str]]:
+ """The flags of each option `fastro make deploy --help` lists, one option per entry."""
+ run = _fastro("make", "deploy", "--help")
+ assert run.returncode == 0, run.stdout + run.stderr
+ options = run.stdout.split("Options:", 1)[1].splitlines()
+
+ return [re.findall(r"--?[a-z][a-z-]*", line.split(" ")[1]) for line in options if line.startswith(" -")]
+
+
+def test_the_page_names_the_modes_the_catalog_declares():
+ assert sorted(_mode_rows()) == sorted(MODES)
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_each_mode_writes_the_files_and_the_stack_its_row_names(mode: str, tmp_path: Path):
+ row = _mode_rows()[mode]
+ written = _made(mode, tmp_path)
+ services = yaml.safe_load(written["docker-compose.yml"])["services"]
+ stage = re.search(r"`(\w+)` stage", row[1])
+ port = re.search(r"\bport (\d+)\b", row[1])
+ published = services.get("nginx", {}).get("ports", [])
+
+ assert sorted(written) == sorted(_ticked(row[2]))
+ assert stage, row
+ assert services["api"]["build"]["target"] == stage[1]
+ assert ("`migrate`" in row[1]) == ("migrate" in services)
+ assert ("Postgres" in row[1]) == ("postgres" in services)
+ assert ("Redis" in row[1]) == ("redis" in services)
+ assert (f"{port[1]}:{port[1]}" in published) if port else not published
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_each_file_names_the_command_that_wrote_it_and_the_project_is_the_slug(mode: str, tmp_path: Path):
+ written = _made(mode, tmp_path)
+ project = tomllib.loads((REPO_ROOT / "fastro.toml").read_text())["project"]["name"]
+ section = _section(MAKE_DEPLOY)
+ headers = {text.splitlines()[0] for text in written.values()}
+
+ assert headers == {f"# Generated by `fastro make deploy {mode}`."}
+ assert yaml.safe_load(written["docker-compose.yml"])["name"] == project.lower() == "fastapi-boilerplate"
+ assert "a header naming the command that wrote it" in section
+ assert "named after the project's slug, `fastapi-boilerplate` here" in section
+
+
+def _rendered_directly(mode: str, services: list[str]) -> dict[str, Any]:
+ """A mode's compose file rendered with jinja under fastro's settings, for a project named "My App" whose
+ selection brings ``services``. Only the names the templates read are in the context."""
+ environment = Environment(
+ loader=FileSystemLoader(REPO_ROOT / GENERATOR["templates"]), keep_trailing_newline=True, undefined=StrictUndefined
+ )
+ context = {
+ "project": {"name": "My App", "slug": "my-app"},
+ "services": services,
+ "params": {name: param["default"] for name, param in GENERATOR["params"].items()},
+ }
+
+ return dict(yaml.safe_load(environment.get_template(f"{mode}/docker-compose.yml.j2").render(context)))
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_the_compose_project_is_the_slug_not_the_name(mode: str):
+ assert _rendered_directly(mode, [])["name"] == "my-app"
+
+
+LEGACY = {
+ "local/docker-compose.yml": "0b8f3746c257de3fb36564f72e7786ff2863b00e636c40dde6cd368c7d94b706",
+ "prod/docker-compose.yml": "b315b3bfa74e2d7ffb70890bb4d44766bbc176e85412238871cbdefb5520a854",
+ "nginx/docker-compose.yml": "7f7f158f9c83d01279f6c8ce67e0f798236d07cbf9a0eda2317c5bf007471afa",
+ "nginx/nginx/default.conf": "dec9a1f2b30190a783d34d1b9336de8a0666b603fb453ae33acce7f75952f161",
+}
+"""The sha256 of what fastro a07bbc1's legacy deploy command wrote for each mode, with the default params, past
+the header line and with the project name written as ``{project}``."""
+
+
+def _past_the_header_and_name(text: str) -> str:
+ return re.sub(r"(?i)fastapi-boilerplate", "{project}", "".join(text.splitlines(keepends=True)[1:]))
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_apart_from_the_header_and_name_the_files_are_what_the_legacy_command_wrote(mode: str, tmp_path: Path):
+ written = _made(mode, tmp_path)
+ digests = {
+ f"{mode}/{path}": hashlib.sha256(_past_the_header_and_name(text).encode()).hexdigest() for path, text in written.items()
+ }
+
+ assert digests == {path: digest for path, digest in LEGACY.items() if path.startswith(f"{mode}/")}
+ assert "Apart from the header and the project name, the files are byte for byte" in _section(MAKE_DEPLOY)
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_a_project_with_taskiq_gets_a_worker_and_one_scheduler_in_every_mode(mode: str, tmp_path: Path):
+ with_taskiq = _compose(mode, tmp_path)["services"]
+
+ assert "taskiq feature also gets a `worker` and one `scheduler` in every mode" in _section(MAKE_DEPLOY)
+ assert sorted(CATALOG["features"]["taskiq"]["services"]) == ["scheduler", "worker"]
+ assert {"worker", "scheduler"} <= set(with_taskiq)
+ assert with_taskiq["scheduler"].get("deploy", {}).get("replicas", 1) == 1
+ assert not {"worker", "scheduler"} & set(_rendered_directly(mode, [])["services"])
+
+
+def test_the_options_and_their_defaults_are_the_ones_fastro_has():
+ stated = _option_rows()
+ listed = {flags[-1] if flags[-1].startswith("--") else flags[0]: flags for flags in _help_flags()}
+ defaults = {f"--{name.replace('_', '-')}": param["default"] for name, param in GENERATOR["params"].items()}
+
+ assert sorted(stated) == sorted(listed)
+ for flag, row in stated.items():
+ assert sorted(_ticked(row[0])) == sorted(listed[flag]), flag
+ if flag in defaults:
+ assert row[1] == f"`{defaults[flag]}`", flag
+ elif flag == "--output-dir":
+ assert row[1] == "the repository root"
+ else:
+ assert row[1] == "", flag
+
+
+def test_the_subnet_limits_are_the_catalogs():
+ limits = GENERATOR["params"]["internal_subnet"]["max_prefix"]
+
+ assert f"`/{limits['v4']}` or smaller for IPv4, and `/{limits['v6']}` or smaller for IPv6" in _section(MAKE_DEPLOY)
+ assert f"`/{limits['v4']}` (IPv4) or `/{limits['v6']}` (IPv6)" in PRODUCTION.read_text()
+
+
+@pytest.mark.parametrize("mode", MODES)
+@pytest.mark.parametrize(
+ ("subnet", "refused"),
+ [
+ ("172.31.240.1/24", True),
+ ("*", True),
+ ("10.0.0.0/7", True),
+ ("fd00::/47", True),
+ ("10.0.0.0/8", False),
+ ("fd00::/48", False),
+ ],
+)
+def test_every_mode_checks_the_subnet_and_refuses_what_the_pages_name(mode: str, subnet: str, refused: bool, tmp_path: Path):
+ run = _fastro("make", "deploy", mode, "--internal-subnet", subnet, "--output-dir", str(tmp_path), "--dry-run")
+ section = _section(MAKE_DEPLOY)
+
+ assert run.returncode == (2 if refused else 0), run.stdout + run.stderr
+ assert "Every value is checked in every mode" in section and "exits 2 before any file is written" in section
+ assert "`local` and `prod` always use the default network" in section
+
+
+def test_the_nginx_subnet_is_the_network_and_the_peers_uvicorn_trusts(tmp_path: Path):
+ subnet = "10.89.0.0/24"
+ compose = _compose("nginx", tmp_path, "--internal-subnet", subnet)
+ networks = [config["subnet"] for network in compose["networks"].values() for config in network["ipam"]["config"]]
+ environment = compose["services"]["api"]["environment"]
+ trusted = (
+ environment["FORWARDED_ALLOW_IPS"]
+ if isinstance(environment, dict)
+ else dict(entry.split("=", 1) for entry in environment)["FORWARDED_ALLOW_IPS"]
+ )
+ section = _section(MAKE_DEPLOY)
+
+ assert networks == [subnet]
+ assert trusted == subnet
+ assert "`FORWARDED_ALLOW_IPS`" in section and "compose network's subnet" in section
+
+
+def _modes_named(cell: str) -> set[str]:
+ named = re.search(r"for ((?:`\w+`(?: and )?)+)$", cell)
+
+ return set(_ticked(named[1])) if named else set(MODES)
+
+
+@pytest.mark.parametrize("mode", MODES)
+def test_the_port_and_the_workers_reach_the_modes_their_rows_name(mode: str, tmp_path: Path):
+ rows = _option_rows()
+ written = _made(mode, tmp_path, "--api-port", "9123", "--workers", "7")
+ api = yaml.safe_load(written["docker-compose.yml"])["services"]["api"]
+ environment = api.get("environment", {})
+
+ if mode in _modes_named(rows["--api-port"][2]):
+ assert api["ports"] == ["9123:8000"]
+ else:
+ assert "ports" not in api
+ assert "9123" not in "".join(written.values())
+ if mode in _modes_named(rows["--workers"][2]):
+ assert environment["WORKERS"] == "7"
+ else:
+ assert "WORKERS" not in environment
+
+
+def test_make_prints_a_line_per_file_and_keeps_a_changed_one_without_a_terminal(tmp_path: Path):
+ target = tmp_path / "docker-compose.yml"
+ shown = str(target)
+ section = _section(MAKE_DEPLOY)
+
+ first = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path))
+ again = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path))
+ target.write_text("edited by hand\n")
+ kept = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path))
+ left = target.read_text()
+ dry = _fastro("make", "deploy", "local", "--output-dir", str(tmp_path), "--dry-run")
+ generated = _made("local", tmp_path / "fresh")["docker-compose.yml"]
+ size = len(generated.encode())
+ replaced = {}
+ for flag in ("--force", "-f", "--yes", "-y"):
+ target.write_text("edited by hand\n")
+ replaced[flag] = (_fastro("make", "deploy", "local", "--output-dir", str(tmp_path), flag).stdout, target.read_text())
+
+ assert (first.returncode, first.stdout.splitlines()) == (0, [f"wrote {shown}"])
+ assert (again.returncode, again.stdout.splitlines()) == (0, [f"unchanged {shown}"])
+ assert kept.returncode == 0 and kept.stdout.startswith(f"kept {shown}")
+ assert left == "edited by hand\n"
+ assert dry.stdout.startswith(f"would write {shown} ({size} bytes)")
+ assert replaced == dict.fromkeys(("--force", "-f", "--yes", "-y"), (f"wrote {shown}\n", generated))
+ assert "or with `--force` or `--yes`" in section
+ assert all(f"`{line} X`" in section for line in ("wrote", "unchanged", "kept"))
+ assert "`would write X (N bytes)`" in section
+ assert "with no terminal to ask on, it is kept and named, and the exit is still 0" in section
+
+
+@pytest.mark.parametrize("command", [["fastro", "make", "deploy", "local"], [OLD_COMMAND, "deploy", "generate", "local"]])
+def test_make_in_a_project_exits_2(command: list[str], tmp_path: Path):
+ """fastro's own command in a project fastro created; the old one in a project made before fastro, with no
+ ``fastro.toml``."""
+ if command[0] == "fastro":
+ (tmp_path / "fastro.toml").write_text(PROJECT_TOML)
+ else:
+ (tmp_path / "backend").mkdir()
+ run = subprocess.run(
+ [str(Path(sys.executable).parent / command[0]), *command[1:]], cwd=tmp_path, capture_output=True, text=True
+ )
+ section = _section(MAKE_DEPLOY)
+
+ assert run.returncode == 2, run.stdout + run.stderr
+ assert not (tmp_path / "docker-compose.yml").exists()
+ assert "In a project fastro created it exits 2" in section
+ assert f"`{OLD_COMMAND} deploy generate` exits 2 too, in a project made before fastro" in section
+
+
+def test_the_secret_size_is_the_one_fastro_takes():
+ size = next(param for param in _command("env", "secret").params if param.name == "bytes_")
+ assert isinstance(size.type, click.IntRange)
+ section = _section(ENV)
+
+ assert f"from `{size.type.min}` to `{size.type.max}`, `{size.default}` by default" in section
+ assert f"so {2 * size.default} hex characters" in section
+
+
+def test_the_built_in_secret_prints_a_token_outside_a_project(tmp_path: Path):
+ run = _fastro("env", "secret", cwd=tmp_path)
+
+ assert run.returncode == 0
+ assert re.fullmatch(r"[0-9a-f]{64}\n", run.stdout)
+ assert "It is built in, so it prints a token anywhere" in _section(ENV)
+
+
+@pytest.mark.parametrize("project", [False, True])
+def test_validate_outside_this_repository_exits_2_saying_why(project: bool, tmp_path: Path):
+ if project:
+ (tmp_path / "fastro.toml").write_text(PROJECT_TOML)
+ run = _fastro("env", "validate", cwd=tmp_path)
+ section = _section(ENV)
+
+ assert run.returncode == 2
+ assert run.stderr.strip()
+ assert "Anywhere else it exits 2 and says why" in section
+ assert "outside a project, and in a project fastro created, for now" in section
+
+
+def test_every_command_the_page_heads_a_section_with_is_one_fastro_has(tmp_path: Path):
+ headed = re.findall(r"^#+ .*?`fastro ([a-z ]+)`", PAGE.read_text(), re.M)
+
+ assert headed
+ for words in headed:
+ run = _fastro(*words.split(), "--help", cwd=tmp_path)
+ assert run.returncode == 0, (words, run.stdout + run.stderr)
+
+
+def test_the_env_commands_run_the_scripts_the_page_names():
+ section = _section(ENV)
+
+ for words in ("env secret", "env validate"):
+ module = CATALOG["commands"][words]["module"]
+ assert f"`{module}`" in section
+ assert (REPO_ROOT / "backend" / f"{module.replace('.', '/')}.py").is_file()
+
+
+@pytest.mark.parametrize(("found", "code"), [((["critical"], ["warning"]), 1), (([], ["warning"]), 0)])
+def test_validate_exits_and_reports_the_way_the_page_says(
+ found: tuple[list[str], list[str]], code: int, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+ monkeypatch.syspath_prepend(str(REPO_ROOT / "backend"))
+ spec = importlib.util.spec_from_file_location("validate_env", REPO_ROOT / "backend" / "scripts" / "validate_env.py")
+ assert spec and spec.loader
+ script = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(script)
+ monkeypatch.setattr(script, "audit", lambda: found)
+
+ exited = script.main()
+ printed = capsys.readouterr().out
+ section = _section(ENV)
+
+ assert exited == code
+ assert "exits 1 when anything is critical and 0 otherwise" in section
+ assert "critical findings first" in section
+ if found[0]:
+ assert printed.index("Critical") < printed.index("Warnings")
+
+
+BLUEPRINT_REPO = "## In the blueprint repository: `fastro sync` and `fastro blueprint`"
+
+
+def test_the_wiring_the_page_names_is_where_sync_writes():
+ named = re.search(r"`\[\[wiring\]\]` tables list, most of them under `([^`]+)`", _section(BLUEPRINT_REPO))
+ assert named
+ paths = [wiring["path"] for wiring in CATALOG["wiring"]]
+
+ assert (REPO_ROOT / named[1]).is_dir()
+ assert 2 * sum(path.startswith(named[1]) for path in paths) > len(paths)
+
+
+def test_the_root_dev_group_installs_fastro():
+ root = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text())
+ dev = [re.split(r"[\s<>=!~\[;@]", specifier, maxsplit=1)[0] for specifier in root["dependency-groups"]["dev"]]
+
+ assert "fastro" in dev
+ assert "The root dev group installs it" in _section("# Generating and updating projects with fastro")
+
+
+def test_the_changelog_says_what_make_deploy_changed(tmp_path: Path):
+ unreleased = (REPO_ROOT / "docs" / "changelog.md").read_text().split("## Unreleased", 1)[1].split("\n## ", 1)[0]
+ heading = "**`fastro make deploy` renders this repository's `[generators.deploy]`.**"
+ entry = " ".join(unreleased.split(heading, 1)[1].split("\n- **", 1)[0].split())
+ name = _compose("local", tmp_path)["name"]
+
+ assert f"the project's slug, `{name}`" in entry
+ assert "`fastro make deploy `" in entry
+ assert "a bad one exits 2" in entry and "`fastro env validate` exits 2" in entry
diff --git a/blueprint/tests/test_observability_recipe.py b/blueprint/tests/test_observability_recipe.py
new file mode 100644
index 00000000..1c2a28e1
--- /dev/null
+++ b/blueprint/tests/test_observability_recipe.py
@@ -0,0 +1,183 @@
+"""The observability guide's tracing recipe, followed in a copy of the repository."""
+
+import ast
+import re
+import tomllib
+from pathlib import Path
+
+import pytest
+from conftest import FastroRunner
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+RECIPE = REPO_ROOT / "docs" / "user-guide" / "observability.md"
+
+
+def _blocks(language: str) -> list[str]:
+ return [str(block) for block in re.findall(rf"^```{language}\n(.*?)^```$", RECIPE.read_text(), re.M | re.S)]
+
+
+def _block(language: str) -> str:
+ blocks = _blocks(language)
+ assert len(blocks) == 1, f"expected one {language} block in the recipe, found {len(blocks)}"
+
+ return blocks[0]
+
+
+def _python_block_defining(name: str) -> str:
+ for block in _blocks("python"):
+ if any(isinstance(node, ast.FunctionDef) and node.name == name for node in ast.parse(block).body):
+ return block
+ raise AssertionError(f"no python block in the recipe defines {name}()")
+
+
+def _installers_slot() -> tuple[str, str]:
+ """The wiring file whose slot holds the installers point, and that slot's name."""
+ catalog = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())
+ return next(
+ (wiring["path"], slot["name"])
+ for wiring in catalog["wiring"]
+ for slot in wiring.get("slots", [])
+ if slot.get("point") == "installers"
+ )
+
+
+def test_the_recipe_registers_its_installer_through_fastro_toml_and_a_sync(tracked_tree: Path, fastro: FastroRunner):
+ project = tracked_tree
+ wiring_file, slot = _installers_slot()
+ registration = _block("toml")
+ reference = re.search(r'installers = \["([\w.]+):(\w+) as (\w+)"\]', registration)
+ assert reference, registration
+ module, function, alias = reference.groups()
+ (project / "backend" / f"{module.replace('.', '/')}.py").write_text(_python_block_defining(function))
+ with (project / "fastro.toml").open("a") as handle:
+ handle.write(f"\n{registration}")
+ wiring_path = project / wiring_file
+
+ synced = fastro("sync", cwd=project)
+ wiring = wiring_path.read_text()
+
+ assert synced.returncode == 0, synced.stdout + synced.stderr
+ assert f"from ..{module.removeprefix('src.')} import {function} as {alias}" in wiring
+ installers = re.search(rf"^{slot}\b.*?= \(\n(.*?)^\)", wiring, re.M | re.S)
+ assert installers, wiring
+ assert installers[1].splitlines()[-1].strip() == f"{alias},", installers[1]
+ recipe = RECIPE.read_text()
+ assert {f"`{alias}`", f"`{slot}`", f"`{wiring_file.removeprefix('backend/')}`", "`fastro sync --check`"} <= set(
+ re.findall(r"`[^`\n]+`", recipe)
+ )
+ assert re.search(rf"^\| [^|]*\| `{re.escape(wiring_file)}` \|$", recipe, re.M)
+ assert re.search(r"^\| [^|]*\| `fastro.toml`, under `\[app.contributes\]` \|$", recipe, re.M)
+ assert fastro("sync", "--check", cwd=project).returncode == 0
+ assert any("fastro sync" in block.splitlines() for block in _blocks("bash"))
+
+ wiring_path.write_text(wiring.replace(f" {alias},\n", ""))
+ assert fastro("sync", "--check", cwd=project).returncode == 1
+ assert fastro("sync", cwd=project).returncode == 0
+ assert wiring_path.read_text() == wiring
+
+
+def test_the_registered_module_is_the_one_the_recipe_writes():
+ registration = _block("toml")
+ module = re.search(r'installers = \["([\w.]+):', registration)
+ assert module, registration
+ path = f"backend/{module[1].replace('.', '/')}.py"
+
+ assert f"`{path.removeprefix('backend/')}`" in RECIPE.read_text()
+ assert re.search(rf'^paths = \["{re.escape(path)}"\]$', registration, re.M), registration
+
+
+def test_the_installer_configures_tracing_before_it_instruments_the_app():
+ """Registered as an installer, `install` is all the app calls, so it has to configure Logfire itself."""
+ module = ast.parse(_python_block_defining("install"))
+ install = next(node for node in module.body if isinstance(node, ast.FunctionDef) and node.name == "install")
+ calls = [ast.unparse(node.func) for node in ast.walk(install) if isinstance(node, ast.Call)]
+
+ assert any(isinstance(node, ast.FunctionDef) and node.name == "configure_tracing" for node in module.body)
+ assert calls.index("configure_tracing") < calls.index("logfire.instrument_fastapi"), calls
+
+
+@pytest.mark.parametrize("arguments", [("sync",), ("sync", "--check")])
+def test_the_pinned_fastro_cannot_sync_a_project_yet(tracked_tree: Path, fastro: FastroRunner, arguments: tuple[str, ...]):
+ """The recipe's hand-edit fallback is there only while this holds; when it fails, delete that sentence."""
+ config = tracked_tree / "fastro.toml"
+ config.write_text(re.sub(r"^source = true\n", "", config.read_text(), flags=re.M))
+
+ synced = fastro(*arguments, cwd=tracked_tree)
+
+ assert f"`fastro {' '.join(arguments)}`" in RECIPE.read_text()
+ assert synced.returncode != 0
+ assert "fastro sync in a project isn't here yet" in synced.stdout + synced.stderr, (
+ "the pinned fastro syncs projects now: drop the main.py fallback sentence from observability.md"
+ )
+
+
+def test_the_hand_edit_fallback_names_the_lines_main_py_has_and_the_recipe_registers(tracked_tree: Path):
+ recipe = RECIPE.read_text()
+ reference = re.search(r'installers = \["([\w.]+):(\w+) as (\w+)"\]', _block("toml"))
+ assert reference, recipe
+ module, function, alias = reference.groups()
+ importing = f"from ..{module.removeprefix('src.')} import {function} as {alias}"
+ passed, replaced = re.findall(r"`(installers=[^`]+,)`", recipe)
+ main = tracked_tree / "backend" / "src" / "interfaces" / "main.py"
+ source = main.read_text()
+
+ assert f"`{importing}`" in recipe
+ assert f"`{main.relative_to(tracked_tree / 'backend')}`" in recipe
+ assert "`fastro sync`" in recipe and "project-mode sync" in recipe
+ assert source.count(f" {passed}\n") == 1, passed
+ assert replaced == f"installers=(*INSTALLERS, {alias}),", replaced
+ edited = f"{importing}\n{source.replace(f' {passed}', f' {replaced}')}"
+ ast.parse(edited)
+
+
+def test_the_worker_note_names_the_worker_module_and_a_call_configure_tracing_takes():
+ recipe = RECIPE.read_text()
+ command = re.search(r"`taskiq worker (src(?:\.\w+)+):(\w+)`", recipe)
+ assert command, recipe
+ worker = REPO_ROOT / "backend" / f"{command[1].replace('.', '/')}.py"
+ tree = ast.parse(worker.read_text())
+ bound = {
+ target.id
+ for node in tree.body
+ if isinstance(node, ast.Assign)
+ for target in node.targets
+ if isinstance(target, ast.Name)
+ }
+ bound |= {alias.asname or alias.name for node in tree.body if isinstance(node, ast.ImportFrom) for alias in node.names}
+ imported = {node.module for node in ast.walk(tree) if isinstance(node, ast.ImportFrom)}
+ imported |= {alias.name for node in ast.walk(tree) if isinstance(node, ast.Import) for alias in node.names}
+ call = re.search(r"`(configure_tracing\([^`]*\))`", recipe)
+ assert call, recipe
+ configure = next(
+ node
+ for node in ast.parse(_python_block_defining("configure_tracing")).body
+ if isinstance(node, ast.FunctionDef) and node.name == "configure_tracing"
+ )
+ given = ast.parse(call[1], mode="eval").body
+ assert isinstance(given, ast.Call)
+
+ assert command[2] in bound
+ assert f"`{worker.relative_to(REPO_ROOT / 'backend')}`" in recipe
+ assert not any(module and module.endswith("interfaces.main") for module in imported)
+ assert {keyword.arg for keyword in given.keywords} <= {argument.arg for argument in configure.args.args}
+ assert given.keywords
+ defaults = dict(
+ zip([argument.arg for argument in configure.args.args][-len(configure.args.defaults) :], configure.args.defaults)
+ )
+ for keyword in given.keywords:
+ assert ast.literal_eval(keyword.value) != ast.literal_eval(defaults[keyword.arg]), keyword.arg
+
+
+def test_the_feature_section_names_the_tables_a_feature_is_declared_with():
+ """A project's own code is `[app]`; a feature lives in the blueprint's catalog, with these tables."""
+ section = RECIPE.read_text().split("## If you turn this into a feature", 1)[1].split("\n## ", 1)[0]
+ catalog = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())
+ feature = re.search(r"`\[features\.(\w+)\]`", section)
+ assert feature, section
+ name = feature[1]
+
+ assert "`blueprint.toml`" in section and "`[app]`" in section
+ assert "`paths`" in section and f"`[features.{name}.contributes]`" in section
+ assert any(
+ "paths" in declared and "installers" in declared.get("contributes", {}) for declared in catalog["features"].values()
+ )
diff --git a/blueprint/tests/test_overlay.py b/blueprint/tests/test_overlay.py
new file mode 100644
index 00000000..66a5a7f9
--- /dev/null
+++ b/blueprint/tests/test_overlay.py
@@ -0,0 +1,317 @@
+"""What the overlay puts in a project, and what it is allowed to say.
+
+Spec 2.1: the overlay's tree is copied into projects, and a `*.j2` file is rendered with the
+spec 6.2 context and loses the suffix. So every path here lands in a project beside the files
+core copies, and every name a template reads has to be one the tool passes.
+"""
+
+import re
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import pytest
+import yaml
+from jinja2 import Environment, FileSystemLoader, StrictUndefined, meta
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+CATALOG = tomllib.loads((REPO_ROOT / "blueprint.toml").read_text())
+
+OVERLAY = REPO_ROOT / CATALOG["blueprint"]["overlay"]
+
+CONTEXT_NAMES = {"project", "blueprint", "fastro", "features", "options", "services", "params", "has"}
+"""Spec 6.2, in full. A template reaching for anything else fails under `StrictUndefined`."""
+
+BUILT_IN_COMMANDS = {"add", "check", "eject", "features", "init", "make", "new", "remove", "sync", "update"}
+"""fastro's own verbs, which take arguments of their own: `fastro add admin` names a feature, not
+a command. Anything else after `fastro` has to be a command the catalog declares, and
+`make ` has to name one it has."""
+
+A_FASTRO_COMMAND = re.compile(r"\bfastro(?:@(?:\{\{[^}]*\}\}|[^\s{]+))? ((?:[a-z][a-z0-9-]*)(?: [a-z][a-z0-9-]*)?)")
+"""A command, however it is run: `fastro sync`, or `uvx fastro@{{ fastro.version }} sync`, or
+`uvx fastro@0.1.0 sync`. Without the pin in the pattern every pinned command goes unread, and
+with a pin that takes any non-space text, the template's own `{{ fastro.version }}` reads as one, leaving `fastro` as
+the command."""
+
+A_CODE_SPAN = re.compile(r"`([^`\n]+)`|```[a-z]*\n(.*?)```", re.DOTALL)
+"""Only what is written as code is read as a command: prose says "generated by fastro from
+blueprint.toml", and `fastro from` is not a command anybody runs. Each span is read on its own,
+or two of them in one sentence would read as one command."""
+
+
+def _context(features: tuple[str, ...] = (), **options: str) -> dict[str, Any]:
+ """The spec 6.2 context, as the tool builds it for the overlay: no generator params."""
+ return {
+ "project": {"name": "Example App", "slug": "example-app"},
+ "blueprint": {"name": CATALOG["blueprint"]["name"], "version": CATALOG["blueprint"]["version"]},
+ "fastro": {"version": "0.1.0"},
+ "features": list(features),
+ "options": dict(options),
+ "services": [],
+ "params": {},
+ "has": lambda name: name in features,
+ }
+
+
+def _files() -> list[Path]:
+ return sorted(path for path in OVERLAY.rglob("*") if path.is_file())
+
+
+def _declared_commands() -> set[str]:
+ """Every command the catalog declares, the features' own included."""
+ words = set(CATALOG.get("commands", {}))
+ for feature in CATALOG["features"].values():
+ words.update(feature.get("commands", {}))
+
+ return words
+
+
+def _landing(path: Path) -> Path:
+ """Where an overlay file lands in a project: a `*.j2` is rendered and loses the suffix."""
+ relative = path.relative_to(OVERLAY)
+
+ return relative.with_suffix("") if relative.suffix == ".j2" else relative
+
+
+def _received() -> set[str]:
+ """Paths a project receives besides the overlay's: the repository's own files that aren't
+ withheld, and every `[[wiring]]` path, which the tool writes whether or not this repository
+ has the file yet."""
+ written = {entry["path"] for entry in CATALOG["wiring"]}
+
+ return written | {
+ path.relative_to(REPO_ROOT).as_posix()
+ for path in REPO_ROOT.rglob("*")
+ if path.is_file() and not _withheld(path.relative_to(REPO_ROOT).as_posix())
+ }
+
+
+def _withheld(path: str) -> bool:
+ return any(
+ path == entry.rstrip("/") or (entry.endswith("/") and path.startswith(entry))
+ for entry in CATALOG["blueprint"]["blueprint_only"]
+ )
+
+
+def test_the_overlay_is_where_the_catalog_says():
+ assert OVERLAY.is_dir()
+ assert _files(), OVERLAY
+
+
+@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files()])
+def test_no_overlay_file_lands_on_a_file_a_project_already_receives(path: str):
+ """Spec 1.27: two files at one path is refused, and a `[[wiring]]` path counts as taken even
+ where this repository has no file yet. The overlay's `.gitignore` is the project's, which is
+ why this repository's own is `blueprint_only`."""
+ landing = _landing(OVERLAY / path).as_posix()
+
+ assert landing not in _received(), landing
+
+
+def test_no_two_overlay_files_land_on_one_path():
+ """Spec 1.27: `x` and `x.j2` in the overlay would both land on `x`, and nothing says which
+ of the two a project gets."""
+ landings = [_landing(path).as_posix() for path in _files()]
+
+ assert sorted(landings) == sorted(set(landings))
+
+
+@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"])
+def test_every_template_reads_only_what_the_tool_passes(path: str):
+ """Spec 6.2: the context is fixed, so a template that asks for anything else renders nothing."""
+ loader = FileSystemLoader(OVERLAY)
+ environment = Environment(loader=loader, undefined=StrictUndefined, keep_trailing_newline=True)
+ source = loader.get_source(environment, path)[0]
+
+ assert meta.find_undeclared_variables(environment.parse(source)) <= CONTEXT_NAMES
+
+
+@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"])
+def test_every_template_renders_for_a_project_with_no_features(path: str):
+ """Core only is the harshest selection: every feature's lines have to be behind a condition."""
+ environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True)
+
+ assert environment.get_template(path).render(_context()).strip()
+
+
+@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files()])
+def test_every_fastro_command_the_overlay_names_is_one_a_project_has(path: str):
+ """A project told to run a command its blueprint doesn't declare is a project that can't.
+
+ `fastro make ` is checked against `[generators]` too, which is why this file says
+ nothing about `make module` yet: that generator arrives with the module scaffold.
+ """
+ spans = [span or fenced for span, fenced in A_CODE_SPAN.findall((OVERLAY / path).read_text())]
+ declared = _declared_commands()
+
+ for named in (found for span in spans for found in A_FASTRO_COMMAND.findall(span)):
+ verb, _, rest = named.partition(" ")
+ if verb == "make" and rest:
+ assert rest in CATALOG["generators"], named
+ elif verb in BUILT_IN_COMMANDS:
+ continue
+ else:
+ assert named in declared if rest else verb in declared, named
+
+
+README = "README.md.j2"
+
+FEATURE_LINES = {
+ "accounts": "setup_initial_data",
+ "admin": "/admin",
+ "taskiq": "taskiq worker",
+}
+"""What the README writes for a feature, and nothing else writes: a project without the feature
+must be told none of it."""
+
+
+def _rendered(path: str, features: tuple[str, ...]) -> str:
+ environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined, keep_trailing_newline=True)
+
+ return environment.get_template(path).render(_context(features))
+
+
+@pytest.mark.parametrize("features", [(), ("accounts",), tuple(CATALOG["features"])], ids=["core", "accounts", "all"])
+def test_the_readme_tells_a_project_only_what_it_carries(features: tuple[str, ...]):
+ """Each feature's lines appear exactly where the feature does. A README is the first thing a
+ reader follows, and a step for something the project hasn't got is a step that fails."""
+ rendered = _rendered(README, features)
+
+ for feature, line in FEATURE_LINES.items():
+ assert (line in rendered) == (feature in features), feature
+
+ for name in CATALOG["features"]:
+ if name not in features:
+ assert not re.search(rf"\b{name}\b", rendered), name
+
+
+def test_the_readme_describes_the_admin_panel_the_example_ships():
+ """The README and `.env.example` go to the same project, so one can't say the panel is off
+ while the other turns it on."""
+ example = (REPO_ROOT / CATALOG["blueprint"]["python_root"] / ".env.example").read_text()
+ rendered = _rendered(README, ("accounts", "admin"))
+ shipped_off = "\nADMIN_ENABLED=false\n" in example
+
+ assert ("ships switched off" in rendered) == shipped_off
+ assert ("Set `ADMIN_ENABLED=true`" in rendered) == shipped_off
+
+
+def test_the_readme_says_what_a_project_with_no_features_is():
+ """Core only is a real answer, so the file says so rather than leaving the line empty."""
+ rendered = _rendered(README, ())
+
+ assert "Nothing optional is selected" in rendered
+ assert "Selected:" not in rendered
+
+
+def test_the_readme_names_the_features_a_project_selected():
+ rendered = _rendered(README, ("accounts", "admin"))
+
+ assert "Selected: accounts, admin." in rendered
+
+
+@pytest.mark.parametrize("features", [(), ("accounts", "admin")])
+def test_the_readme_names_the_blueprint_a_project_came_from(features: tuple[str, ...]):
+ """The catalog's `name` is an id; a reader meets the blueprint by its name in full."""
+ environment = Environment(loader=FileSystemLoader(OVERLAY), undefined=StrictUndefined)
+ blueprint = {"name": "a-blueprint-id", "version": "9.8.7"}
+ rendered = environment.get_template(README).render({**_context(features), "blueprint": blueprint})
+
+ assert f"the FastAPI-boilerplate blueprint (`{blueprint['name']}` {blueprint['version']})" in " ".join(rendered.split())
+
+
+def test_the_agents_file_names_the_blueprint_a_project_came_from():
+ assert re.search(r"\bFastAPI-boilerplate\b", (OVERLAY / "AGENTS.md").read_text())
+
+
+@pytest.mark.parametrize("path", [str(path.relative_to(OVERLAY)) for path in _files() if path.suffix == ".j2"])
+def test_every_fastro_command_a_template_writes_runs_the_tool_that_generated_the_project(path: str):
+ """`uvx fastro@` needs nothing installed first and pins the project to the tool it
+ was generated with, so a reader never gets a newer tool's behaviour by accident.
+
+ Templates only: `AGENTS.md` is written by hand and has no version to interpolate. In Markdown
+ the commands are what is written as code; anywhere else every line is run, so the whole file
+ counts. `fastro.toml` is a file and `fastro.version` a context value, so neither is read as a
+ command, however a pattern escapes the dot.
+ """
+ text = (OVERLAY / path).read_text()
+ spans = (
+ [span or fenced for span, fenced in A_CODE_SPAN.findall(text)] if _landing(OVERLAY / path).suffix == ".md" else [text]
+ )
+ unpinned = []
+ for span in spans:
+ for found in re.finditer(r"fastro", span):
+ before, after = span[: found.start()], span[found.end() :]
+ if after.removeprefix("\\").startswith((".toml", ".version")):
+ continue
+
+ if not (before.endswith("uvx ") and after.startswith("@{{ fastro.version }}")):
+ unpinned.append(span.strip()[:60])
+
+ assert unpinned == []
+
+
+WORKFLOW = ".github/workflows/ci.yml.j2"
+
+PRE_COMMIT = ".pre-commit-config.yaml.j2"
+
+BEFORE_FINISHING = ("ruff check .", "ruff format --check .", "mypy src scripts migrations tests", "pytest")
+"""What an agent is told to run before finishing, which is what CI runs: one list, two files."""
+
+
+@pytest.mark.parametrize("path", [WORKFLOW, PRE_COMMIT])
+def test_the_yaml_a_project_receives_parses(path: str):
+ """Rendered for the harshest selection, since a conditional that empties a list or leaves a
+ dangling key is only visible once it is parsed."""
+ assert yaml.safe_load(_rendered(path, ()))
+
+
+def test_the_workflow_runs_what_the_agent_file_tells_an_agent_to_run():
+ """An agent whose checks are looser than CI's finishes work that CI then rejects."""
+ agents = (OVERLAY / "AGENTS.md").read_text()
+ workflow = _rendered(WORKFLOW, ())
+
+ for command in BEFORE_FINISHING:
+ assert command in agents, command
+ assert command in workflow, command
+
+
+def test_the_workflow_installs_the_project_rather_than_this_workspace():
+ """A project has one `pyproject.toml`, under the python root: `--all-packages` and a root
+ lock are this repository's own shape, and neither is there."""
+ workflow = yaml.safe_load(_rendered(WORKFLOW, ()))
+ steps = workflow["jobs"]["check"]["steps"]
+ installing = next(step for step in steps if step.get("name") == "Install")
+
+ assert "--project backend" in installing["run"]
+ assert "--all-packages" not in installing["run"]
+ assert (
+ "backend/uv.lock" in next(step for step in steps if step.get("name") == "Install uv")["with"]["cache-dependency-glob"]
+ )
+
+
+def test_every_pre_commit_hook_watches_paths_a_project_has():
+ """A `files:` pattern naming `docs/` or `blueprint/` is a hook over nothing: those are the
+ blueprint's own, and no project receives them."""
+ hooks = yaml.safe_load(_rendered(PRE_COMMIT, ()))
+ watched = [hook["files"] for repo in hooks["repos"] for hook in repo["hooks"] if "files" in hook]
+
+ assert watched
+ for pattern in watched:
+ head = re.split(r"[(\[{|?*+\\]", pattern.removeprefix("^"))[0].rstrip("/")
+ assert head in {"backend", "fastro.toml", "fastro\\.toml", ""} or not _withheld(head), pattern
+
+
+def test_the_claude_file_points_at_the_agents_file():
+ """One file for both, so instructions never drift: Claude Code reads `@AGENTS.md` as an import."""
+ assert (OVERLAY / "CLAUDE.md").read_text().strip() == "@AGENTS.md"
+
+
+def test_the_agents_file_tells_an_agent_what_it_must_not_edit():
+ """The wiring is generated, and an agent editing it loses its work on the next sync."""
+ text = (OVERLAY / "AGENTS.md").read_text()
+
+ assert "src/wiring/" in text
+ assert "fastro sync" in text
+ assert "make module" not in text, "that generator does not exist yet"
diff --git a/blueprint/tests/test_pre_commit.py b/blueprint/tests/test_pre_commit.py
new file mode 100644
index 00000000..46200ce2
--- /dev/null
+++ b/blueprint/tests/test_pre_commit.py
@@ -0,0 +1,38 @@
+"""The pre-commit hooks the development guide describes, run the way a contributor runs them."""
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _unit_test_hook() -> tuple[str, list[str]]:
+ """The directory the unit test hook runs in, and the arguments it gives pytest."""
+ config = (REPO_ROOT / ".pre-commit-config.yaml").read_text()
+ entry = r" +entry: bash -c 'cd (\S+) && uv run --no-sync pytest(.*)'\n"
+ found = re.search(rf"- id: unit_test\n(?: +[\w-]+:.*\n)*?{entry}", config)
+ assert found, config
+
+ return found[1], found[2].split()
+
+
+def test_the_unit_test_hook_passes_without_docker(tmp_path: Path):
+ """Every unit test that starts a container skips when Docker can't be reached, and the rest pass."""
+ directory, arguments = _unit_test_hook()
+ unreachable = {name: value for name, value in os.environ.items() if not name.startswith("TESTCONTAINERS")}
+ unreachable |= {"HOME": str(tmp_path), "DOCKER_HOST": "tcp://127.0.0.1:1"}
+
+ run = subprocess.run(
+ [sys.executable, "-m", "pytest", *arguments, "-q", "-n", "auto", "-p", "no:cacheprovider"],
+ cwd=REPO_ROOT / directory,
+ env=unreachable,
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+
+ assert run.returncode == 0, run.stdout[-4000:]
+ assert re.search(r"\b[1-9]\d* skipped\b", run.stdout), run.stdout[-4000:]
diff --git a/blueprint/tests/test_retired_cli.py b/blueprint/tests/test_retired_cli.py
new file mode 100644
index 00000000..0a0ed761
--- /dev/null
+++ b/blueprint/tests/test_retired_cli.py
@@ -0,0 +1,165 @@
+"""Nothing outside the history names the developer tool's old package, the command it shipped,
+or the drill that built the repository without each feature."""
+
+import importlib.metadata
+import re
+from collections.abc import Iterator
+
+import click
+import pytest
+import typer.main
+from fastro import compat
+from fastro.cli import app
+from fastro.engine import blueprint
+from fastro.tools import installed_version
+from fastro.verify import verify_sets
+from retired import (
+ NAMES_OLD_COMMAND,
+ NAMES_OLD_DRILL,
+ NAMES_OLD_PACKAGE,
+ OLD_COMMAND,
+ OLD_DRILL,
+ OLD_PACKAGE,
+ REPO_ROOT,
+ SAYS_OLD_COMMAND_EXITS,
+ tracked_text,
+)
+
+NEEDLES = {"package": NAMES_OLD_PACKAGE, "command": NAMES_OLD_COMMAND, "drill": NAMES_OLD_DRILL}
+
+STILL_CARRYING = {
+ ("package", "docs/changelog.md"): "the history, for good",
+ ("command", "docs/changelog.md"): "the history, for good",
+ ("command", "docs/assets/build-cover.cjs"): "B5",
+ ("drill", "docs/changelog.md"): "the history, for good",
+ ("drill", "docs/index.md"): "B5",
+ ("drill", "docs/user-guide/testing.md"): "B5",
+ ("drill", "docs/user-guide/composable-features.md"): "B5",
+ ("drill", "docs/user-guide/project-structure.md"): "B5",
+ ("drill", "docs/assets/build-diagrams.cjs"): "B5",
+}
+"""Which needle each exempted file carries, and the item that lifts the exemption."""
+
+REDIRECTS = "[project.plugins.redirects.redirect_maps]"
+
+FASTRO_PAGE = "docs/user-guide/fastro.md"
+
+
+def _lines(name: str, text: str) -> Iterator[tuple[int, str]]:
+ """The numbered lines of a file, without the lines of `zensical.toml`'s redirect map."""
+ inside = False
+ for number, line in enumerate(text.splitlines(), 1):
+ if name == "zensical.toml" and line.startswith("["):
+ inside = line.strip() == REDIRECTS
+ if not inside:
+ yield number, line
+
+
+def _hits() -> dict[tuple[str, str], list[str]]:
+ hits: dict[tuple[str, str], list[str]] = {}
+ for name, text in tracked_text():
+ for number, line in _lines(name, text):
+ for needle, pattern in NEEDLES.items():
+ if pattern.search(line) and not (name == FASTRO_PAGE and SAYS_OLD_COMMAND_EXITS.match(line)):
+ hits.setdefault((needle, name), []).append(f"{name}:{number}: {line.strip()}")
+
+ return hits
+
+
+def test_no_file_names_the_old_package_its_command_or_the_drill():
+ found = [line for key, lines in _hits().items() if key not in STILL_CARRYING for line in lines]
+
+ assert found == []
+
+
+def test_every_exempted_file_still_carries_what_it_is_exempt_for():
+ assert set(STILL_CARRYING) <= set(_hits()), "drop the exemption of a file that no longer carries it"
+
+
+@pytest.mark.parametrize(
+ ("line", "named"),
+ [
+ (f"run: cd {OLD_PACKAGE} && uv run --no-sync pytest", True),
+ (f"COPY {OLD_PACKAGE}/pyproject.toml {OLD_PACKAGE}/pyproject.toml", True),
+ (f"uv run --no-sync mypy -p {OLD_PACKAGE}", True),
+ (f'members = ["backend", "{OLD_PACKAGE}"]', True),
+ (f"uv tool install --editable ./{OLD_PACKAGE}", True),
+ (f"from {OLD_PACKAGE}.commands import deploy", True),
+ (f"uv sync --reinstall-package fastapi-boilerplate-{OLD_PACKAGE}", True),
+ ("docker compose exec redis redis-cli ping", False),
+ ("from fastro.cli import app", False),
+ ("fastro is a CLI", False),
+ ("the clipboard and a clinic", False),
+ ],
+)
+def test_the_package_needle(line: str, named: bool):
+ assert bool(NAMES_OLD_PACKAGE.search(line)) is named
+
+
+@pytest.mark.parametrize(
+ ("line", "named"),
+ [
+ (f"uv run {OLD_COMMAND} deploy generate prod", True),
+ (f"{OLD_COMMAND} env validate", True),
+ (f"the `{OLD_COMMAND}` command", True),
+ (f"uv run {OLD_COMMAND} ...", True),
+ (f'plugin-ready {OLD_COMMAND} CLI', True),
+ (f"a plugin-aware {OLD_COMMAND} CLI", True),
+ (f"{OLD_COMMAND}-and-fastro", False),
+ ("fastro make deploy prod", False),
+ ],
+)
+def test_the_command_needle(line: str, named: bool):
+ assert bool(NAMES_OLD_COMMAND.search(line)) is named
+
+
+@pytest.mark.parametrize(
+ ("line", "named"),
+ [
+ (f"uv run --no-sync python tools/{OLD_DRILL}.py accounts-only", True),
+ (f"backend/tests/unit/test_{OLD_DRILL}.py", True),
+ (f' "{OLD_COMMAND}-and-fastro",', True),
+ ("uv run --no-sync fastro blueprint verify accounts-only", False),
+ ("a removal that leaves nothing behind", False),
+ ],
+)
+def test_the_drill_needle(line: str, named: bool):
+ assert bool(NAMES_OLD_DRILL.search(line)) is named
+
+
+def _removed() -> str:
+ """The changelog's Unreleased `#### Removed` section, on one line."""
+ changelog = (REPO_ROOT / "docs" / "changelog.md").read_text()
+ unreleased = changelog.split("\n## Unreleased\n", 1)[1].split("\n## ", 1)[0]
+
+ return " ".join(unreleased.split("#### Removed", 1)[1].split("\n#### ", 1)[0].split())
+
+
+def _old_and_new_commands() -> list[tuple[str, str]]:
+ """The pairs the changelog's entry for the package's removal gives, old command first."""
+ return re.findall(rf"`{OLD_COMMAND} ([^`]+)` is `fastro ([^`]+)`", _removed())
+
+
+def test_the_changelog_says_what_verify_builds_and_keeps():
+ entry = _removed().split("**The removal drill.**", 1)[1].split(" - **", 1)[0]
+ catalog = blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version())
+ root = typer.main.get_command(app)
+ assert isinstance(root, click.Group)
+ group = root.commands["blueprint"]
+ assert isinstance(group, click.Group)
+ options = {flag for param in group.commands["verify"].params for flag in param.opts}
+
+ assert "`uv run --no-sync fastro blueprint verify`" in entry
+ assert "`--keep`" in entry and "--keep" in options
+ assert "each set in `blueprint.toml`, each preset and `everything`" in entry
+ assert set(verify_sets(catalog)) == {*catalog.verify.sets, *catalog.presets, "everything"}
+
+
+def test_fastro_still_answers_to_the_old_commands_the_changelog_maps():
+ scripts = {point.name: point.value for point in importlib.metadata.entry_points(group="console_scripts")}
+ pairs = _old_and_new_commands()
+
+ assert scripts[OLD_COMMAND] == f"fastro.compat:{OLD_COMMAND}_main"
+ assert len(pairs) == 3, pairs
+ for old, new in pairs:
+ assert compat.translate(old.split()) == new.split(), (old, new)
diff --git a/blueprint/tests/test_verify_matrix.py b/blueprint/tests/test_verify_matrix.py
new file mode 100644
index 00000000..b925fd97
--- /dev/null
+++ b/blueprint/tests/test_verify_matrix.py
@@ -0,0 +1,51 @@
+"""CI verifies every set `fastro blueprint verify` builds, one job each."""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from fastro.engine import blueprint
+from fastro.tools import installed_version
+from fastro.verify import verify_sets
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+WORKFLOW = REPO_ROOT / ".github" / "workflows" / "tests.yml"
+TESTING = REPO_ROOT / "docs" / "user-guide" / "testing.md"
+
+VERIFY = "uv run --no-sync fastro blueprint verify ${{ matrix.preset }}"
+
+
+def _job() -> dict[str, Any]:
+ jobs: dict[str, dict[str, Any]] = yaml.safe_load(WORKFLOW.read_text())["jobs"]
+ (job,) = [job for job in jobs.values() if any(step.get("run") == VERIFY for step in job.get("steps", []))]
+
+ return job
+
+
+def _catalog() -> blueprint.Blueprint:
+ return blueprint.load("blueprint.toml", (REPO_ROOT / "blueprint.toml").read_text(), installed_version())
+
+
+def test_the_ci_matrix_is_every_set_verify_builds():
+ assert set(_job()["strategy"]["matrix"]) == {"preset"}
+ assert sorted(_job()["strategy"]["matrix"]["preset"]) == sorted(verify_sets(_catalog()))
+
+
+def test_one_sets_failure_leaves_the_others_running():
+ assert _job()["strategy"]["fail-fast"] is False
+
+
+def test_a_failed_verify_fails_the_job():
+ job = _job()
+ (step,) = [step for step in job["steps"] if step.get("run") == VERIFY]
+
+ assert not {"if", "continue-on-error"} & (set(job) | set(step))
+
+
+def test_the_testing_guide_says_ci_verifies_every_set():
+ section = " ".join(TESTING.read_text().split("## Continuous Integration", 1)[1].split("\n## ", 1)[0].split())
+
+ assert "`fastro blueprint verify`" in section
+ assert "`[verify.sets]`" in section
+ assert "`everything`" in section
+ assert ("presets" in section) is _catalog().verify.include_presets
diff --git a/cli/README.md b/cli/README.md
deleted file mode 100644
index e379b391..00000000
--- a/cli/README.md
+++ /dev/null
@@ -1,48 +0,0 @@
-# bp — FastAPI-boilerplate CLI
-
-`bp` is the developer/operator command-line tool for projects built on the
-FastAPI boilerplate. It generates deployment artifacts, helps prepare the
-runtime environment, and serves as the host for plugin commands and feature
-generators.
-
-## Install
-
-This package is part of the workspace. From the repo root:
-
-```bash
-uv sync --all-packages --all-extras # bp is then available via `uv run bp`
-uv run bp --help
-```
-
-To install `bp` machine-wide so it works outside this repo:
-
-```bash
-uv tool install --editable ./cli
-bp --help
-```
-
-## What's here
-
-```
-cli/src/cli/
-├── app.py root Typer app + plugin discovery
-├── plugins.py entry-point loaders for bp.commands and bp.features
-├── commands/ in-tree command sub-apps
-│ ├── deploy.py bp deploy generate
-│ └── env.py bp env gen-secret / bp env validate
-├── features/ feature framework (manifest, plan, installer)
-│ └── _builtins/ in-tree features
-│ └── deploy/ compose/Dockerfile templates for local/prod/nginx
-└── lib/ shared helpers (project discovery, prompts, render)
-```
-
-## Plugin extension points
-
-Two kinds of plugins, kept deliberately separate:
-
-- `bp.commands` entry-point group — third-party Typer sub-apps mounted under
- `bp ` (e.g. `bp aws deploy`).
-- `bp.features` entry-point group — code generators with a manifest that
- `bp feature` can list, install, and remove.
-
-See `cli/src/cli/plugins.py` for the discovery contracts.
diff --git a/cli/pyproject.toml b/cli/pyproject.toml
deleted file mode 100644
index d17c074d..00000000
--- a/cli/pyproject.toml
+++ /dev/null
@@ -1,60 +0,0 @@
-[build-system]
-requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "fastapi-boilerplate-cli"
-version = "0.1.0"
-description = "bp — developer/operator CLI for the FastAPI boilerplate. Hosts in-tree commands and discovers third-party plugins."
-authors = [{ name = "Benav Labs", email = "contact@benav.io" }]
-license = { text = "MIT" }
-readme = "README.md"
-requires-python = ">=3.11"
-dependencies = [
- "typer>=0.12",
- "jinja2>=3.1",
- "fastapi-boilerplate",
-]
-
-[project.optional-dependencies]
-dev = [
- "pytest>=8.3.5",
- "pyyaml>=6.0.2",
-]
-
-[project.scripts]
-bp = "cli.app:app"
-
-[tool.uv.sources]
-fastapi-boilerplate = { workspace = true }
-
-[tool.setuptools]
-include-package-data = true
-
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["*"]
-
-[tool.setuptools.package-data]
-"*" = ["*.j2", "*.toml", "*.conf", "py.typed"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-python_files = ["test_*.py"]
-
-[tool.ruff]
-line-length = 128
-
-[tool.ruff.lint]
-select = ["E", "F", "I", "UP"]
-extend-select = ["UP006", "UP007", "UP035", "UP039", "PLC0415"]
-
-[tool.ruff.lint.isort]
-known-first-party = ["cli"]
-
-[tool.mypy]
-python_version = "3.11"
-warn_return_any = true
-warn_unused_configs = true
-warn_unused_ignores = true
diff --git a/cli/src/cli/__init__.py b/cli/src/cli/__init__.py
deleted file mode 100644
index d32794ee..00000000
--- a/cli/src/cli/__init__.py
+++ /dev/null
@@ -1,12 +0,0 @@
-"""bp — the FastAPI-boilerplate command-line tool.
-
-The CLI is a Typer application with two extension points:
-
-- `bp.commands` entry-point group: third-party packages can register
- top-level Typer sub-apps that mount under `bp `.
-- `bp.features` entry-point group: third-party packages can register
- ``Feature`` instances that ``bp feature`` can list, install, and remove.
-
-In-tree commands and features live alongside this package and follow
-the same contracts as plugins.
-"""
diff --git a/cli/src/cli/app.py b/cli/src/cli/app.py
deleted file mode 100644
index fcae4ce1..00000000
--- a/cli/src/cli/app.py
+++ /dev/null
@@ -1,62 +0,0 @@
-"""bp — root Typer application and entry point.
-
-Mounts in-tree command sub-apps and discovers third-party plugins.
-The shipped console script (``[project.scripts] bp``) targets
-``app`` directly.
-"""
-
-from __future__ import annotations
-
-import typer
-
-from . import plugins as _plugins
-from .commands import deploy as _deploy_cmd
-from .commands import env as _env_cmd
-
-app = typer.Typer(
- name="bp",
- help="FastAPI-boilerplate command-line tool.",
- no_args_is_help=True,
- pretty_exceptions_show_locals=False,
-)
-
-# In-tree commands. Mounted before plugin discovery so a plugin can't
-# silently shadow a built-in by registering the same name.
-app.add_typer(_deploy_cmd.app, name="deploy", help="Generate deployment artifacts (Dockerfile, compose, nginx config).")
-app.add_typer(_env_cmd.app, name="env", help="Inspect and prepare the runtime environment.")
-
-
-def _mount_command_plugins() -> None:
- """Mount external Typer sub-apps registered under ``bp.commands``.
-
- A plugin that fails to load warns rather than stopping the CLI, so the warning
- is routed to stderr first: on stdout it would land in whatever the caller is
- piping command output into.
- """
- _plugins.emit_plugin_warnings_to_stderr()
-
- builtin_names = {"deploy", "env", "feature"}
- for name, sub_app in _plugins.discover_command_plugins().items():
- if name in builtin_names:
- typer.secho(
- f"warning: plugin command '{name}' shadows a built-in; ignoring.",
- fg=typer.colors.YELLOW,
- err=True,
- )
- continue
- app.add_typer(sub_app, name=name)
-
-
-_mount_command_plugins()
-
-
-@app.callback()
-def _root() -> None:
- """bp — FastAPI-boilerplate command-line tool."""
- # Typer uses this docstring as the root help text. The body is
- # intentionally empty: the callback exists so options like
- # ``--install-completion`` work without arguments.
-
-
-if __name__ == "__main__": # pragma: no cover
- app()
diff --git a/cli/src/cli/commands/__init__.py b/cli/src/cli/commands/__init__.py
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/src/cli/commands/deploy.py b/cli/src/cli/commands/deploy.py
deleted file mode 100644
index 84200f5b..00000000
--- a/cli/src/cli/commands/deploy.py
+++ /dev/null
@@ -1,107 +0,0 @@
-"""``bp deploy`` — generate deployment artifacts.
-
-Today this is just a wrapper around the in-tree ``deploy`` feature.
-Other deploy-adjacent commands (``bp deploy nginx-tls``, ``bp deploy
-github-actions``) can mount here as siblings.
-"""
-
-from __future__ import annotations
-
-from enum import StrEnum
-from pathlib import Path
-
-import typer
-
-from ..features._builtins.deploy.feature import DEFAULT_INTERNAL_SUBNET
-from ..features.installer import FeatureInstaller
-from ..features.registry import get_feature
-from ..lib.project import discover_project
-from ..lib.prompts import error, info
-
-app = typer.Typer(no_args_is_help=True, help="Generate deployment artifacts.")
-
-
-class DeployMode(StrEnum):
- local = "local"
- prod = "prod"
- nginx = "nginx"
-
-
-@app.command("generate")
-def generate(
- mode: DeployMode = typer.Argument(
- ...,
- help="Deployment mode to generate. Pick `local` for hot-reload dev, `prod` for "
- "single-host production, `nginx` for production behind a reverse proxy.",
- ),
- output_dir: Path = typer.Option(
- None,
- "--output-dir",
- "-o",
- help="Where to write the compose file. Defaults to the repo root.",
- ),
- api_port: int = typer.Option(8000, "--api-port", help="Host port to publish the API on."),
- workers: int = typer.Option(4, "--workers", help="Number of API workers (prod / nginx only)."),
- internal_subnet: str = typer.Option(
- DEFAULT_INTERNAL_SUBNET,
- "--internal-subnet",
- help="Subnet for the compose network, and the only peers uvicorn takes forwarded headers from (nginx only).",
- ),
- force: bool = typer.Option(False, "--force", "-f", help="Overwrite existing files without asking."),
- yes: bool = typer.Option(False, "--yes", "-y", help="Assume yes for all prompts."),
- dry_run: bool = typer.Option(False, "--dry-run", help="Show what would be written, don't touch disk."),
-) -> None:
- """Generate ``docker-compose.yml`` (and ``nginx/default.conf`` for nginx mode)."""
- project = discover_project(output_dir)
- feature = get_feature("deploy")
- if feature is None: # pragma: no cover — built-in feature, always present
- error("deploy feature is not registered.")
- raise typer.Exit(code=1)
-
- target_root = (output_dir or project.repo_root).resolve()
- if not dry_run:
- target_root.mkdir(parents=True, exist_ok=True)
-
- params: dict = {
- "mode": mode.value,
- "api_port": api_port,
- "workers": workers,
- "compose_target": target_root / "docker-compose.yml",
- }
- if mode == DeployMode.nginx:
- params["nginx_conf_target"] = target_root / "nginx" / "default.conf"
- params["internal_subnet"] = internal_subnet
-
- try:
- plan = feature.plan(params, project)
- except ValueError as failure:
- error(f"--internal-subnet: {failure}")
- raise typer.Exit(code=1) from failure
-
- installer = FeatureInstaller(dry_run=dry_run, assume_yes=force or yes)
- info(f"deploy: generating '{mode.value}' compose for {project.repo_root}")
- result = installer.apply(plan)
-
- if result.files_skipped:
- info("")
- info(f"{len(result.files_skipped)} file(s) skipped.")
- if dry_run:
- info("")
- info("dry-run complete — no files were written.")
- return
-
- info("")
- info("done. Next steps:")
- if mode == DeployMode.local:
- info(" docker compose up --build")
- return
-
- info(" cp backend/.env.example backend/.env # if you haven't already")
- info(" # with migrations/versions empty, generate and commit the baseline first,")
- info(" # against a database with nothing in it, or upgrade writes an empty revision:")
- info(" # docs/user-guide/database/migrations.md#alembic-migrations")
- info(" docker compose build")
- info(" docker compose --profile migrate run --rm migrate")
- info(" docker compose up -d")
- if mode == DeployMode.nginx:
- info(" curl -i http://localhost/health/ready")
diff --git a/cli/src/cli/commands/env.py b/cli/src/cli/commands/env.py
deleted file mode 100644
index cb889947..00000000
--- a/cli/src/cli/commands/env.py
+++ /dev/null
@@ -1,139 +0,0 @@
-"""``bp env`` — inspect and prepare the runtime environment.
-
-Two commands today:
-
-- ``bp env gen-secret`` prints a 64-char hex string suitable for
- ``SECRET_KEY``. No filesystem I/O — pipe it into your secrets manager.
-
-- ``bp env validate`` runs the production security validator against
- the current settings, regardless of the configured environment, and
- prints critical errors and warnings.
-"""
-
-from __future__ import annotations
-
-import importlib
-import importlib.util
-import secrets
-import sys
-from pathlib import Path
-from types import ModuleType
-
-import typer
-
-from ..lib.prompts import error, info, success, warn
-
-
-def _backend_root() -> Path | None:
- """The ``backend/`` of the project this command was run in, if there is one."""
- return next((p / "backend" for p in (Path.cwd(), *Path.cwd().parents) if (p / "backend" / "src").is_dir()), None)
-
-
-def _app_module(name: str) -> ModuleType:
- """Import a backend module by its ``src.`` path, putting ``backend/`` on the path first.
-
- The app is imported through a single root, ``src``, which the installed
- distribution does not expose: its packages are published from inside ``src/``.
- Resolving it here, when a command needs it, also keeps ``bp --help`` from
- paying for the app's settings and database imports.
- """
- backend = _backend_root()
- if backend is None:
- error("No `backend/src` in this directory or above it: run this from inside a project.")
- raise typer.Exit(code=1)
-
- if str(backend) not in sys.path:
- sys.path.insert(0, str(backend))
-
- return importlib.import_module(name)
-
-
-def _secret_key_rules() -> ModuleType | None:
- """The app's own secret-key rules, or ``None`` outside a project.
-
- Loaded from their file, which keeps the settings and logging imports of the
- package around them out of this command's output.
- """
- backend = _backend_root()
- if backend is None:
- return None
-
- spec = importlib.util.spec_from_file_location(
- "app_secret_key_rules", backend / "src" / "infrastructure" / "security" / "secret_key.py"
- )
- if spec is None or spec.loader is None:
- return None
-
- rules = importlib.util.module_from_spec(spec)
- try:
- spec.loader.exec_module(rules)
- except Exception:
- return None
-
- return rules
-
-
-SECRET_KEY_DRAWS = 8
-
-app = typer.Typer(no_args_is_help=True, help="Inspect and prepare the runtime environment.")
-
-
-@app.command("gen-secret")
-def gen_secret(
- bytes_: int = typer.Option(32, "--bytes", min=16, max=128, help="Number of random bytes (hex output is 2x)."),
-) -> None:
- """Generate a high-entropy hex secret suitable for ``SECRET_KEY``.
-
- Draws again while the app's own rules would refuse the key: about one hex key in
- twelve million runs through eight consecutive digits, which production refuses at
- startup. Outside a project, where those rules cannot be imported, the first draw
- is printed.
- """
- rules = _secret_key_rules()
- is_weak = getattr(rules, "is_weak_secret_key", None)
-
- candidate = secrets.token_hex(bytes_)
- for _ in range(SECRET_KEY_DRAWS - 1):
- if is_weak is None or not is_weak(candidate):
- break
- candidate = secrets.token_hex(bytes_)
-
- typer.echo(candidate)
-
-
-@app.command("validate")
-def validate() -> None:
- """Run the production security validator against the current settings.
-
- Reports what production would refuse whatever ``ENVIRONMENT`` says, so a dev
- or staging config can be audited the same way prod is gated. The settings are
- audited as a copy that says ``production``, so a finding that names the
- environment names the one being audited for.
- """
- settings_module = _app_module("src.infrastructure.config.settings")
- settings = settings_module.get_settings()
- validator_module = _app_module("src.infrastructure.security.production_validator")
- ProductionSecurityValidator = validator_module.ProductionSecurityValidator
-
- production = settings_module.EnvironmentOption.PRODUCTION
- as_production = settings.model_copy(update={"ENVIRONMENT": production})
- critical_errors, captured_warnings = ProductionSecurityValidator(as_production).audit()
-
- if not critical_errors and not captured_warnings:
- success("No issues found. Configuration would pass production validation.")
- return
-
- if critical_errors:
- error(f"Critical ({len(critical_errors)}):")
- for item in critical_errors:
- typer.secho(f" • {item}", fg=typer.colors.RED)
-
- if captured_warnings:
- if critical_errors:
- info("")
- warn(f"Warnings ({len(captured_warnings)}):")
- for item in captured_warnings:
- typer.secho(f" • {item}", fg=typer.colors.YELLOW)
-
- if critical_errors:
- raise typer.Exit(code=1)
diff --git a/cli/src/cli/features/__init__.py b/cli/src/cli/features/__init__.py
deleted file mode 100644
index 424beee4..00000000
--- a/cli/src/cli/features/__init__.py
+++ /dev/null
@@ -1,25 +0,0 @@
-"""Feature framework: typed manifests, plans, and the installer.
-
-A feature is a self-contained unit of work that mutates a user's
-project — generating files, editing existing files, running setup
-hooks. ``Feature`` subclasses describe themselves via a manifest and
-emit a ``FeaturePlan`` that the installer executes.
-
-For v1 only ``FileOp`` operations are supported. ``Codemod`` and ``Hook``
-slots in the plan exist for forward compatibility — installers raise
-``NotImplementedError`` if a plan asks for one.
-"""
-
-from .base import Codemod, Feature, FeatureManifest, FeaturePlan, FileOp, Hook
-from .installer import FeatureInstaller, InstallResult
-
-__all__ = [
- "Codemod",
- "Feature",
- "FeatureInstaller",
- "FeatureManifest",
- "FeaturePlan",
- "FileOp",
- "Hook",
- "InstallResult",
-]
diff --git a/cli/src/cli/features/_builtins/__init__.py b/cli/src/cli/features/_builtins/__init__.py
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/src/cli/features/_builtins/deploy/__init__.py b/cli/src/cli/features/_builtins/deploy/__init__.py
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/src/cli/features/_builtins/deploy/feature.py b/cli/src/cli/features/_builtins/deploy/feature.py
deleted file mode 100644
index 30817b2a..00000000
--- a/cli/src/cli/features/_builtins/deploy/feature.py
+++ /dev/null
@@ -1,108 +0,0 @@
-"""The deploy feature — generate Dockerfile-friendly compose files.
-
-Three modes are supported in v1:
-
-- ``local``: hot-reload dev stack (mounts source, exposes port 8000)
-- ``prod``: production stack with multiple workers, ports exposed directly
-- ``nginx``: ``prod`` plus an nginx reverse proxy on port 80
-
-All modes target the existing multi-stage ``backend/Dockerfile`` —
-no per-mode Dockerfile is generated. Modes only differ in the
-compose file (and an optional nginx config).
-"""
-
-from __future__ import annotations
-
-from ipaddress import ip_network
-from pathlib import Path
-from typing import Any
-
-from ....lib.project import ProjectContext
-from ...base import Feature, FeatureManifest, FeaturePlan, FileOp
-
-SUPPORTED_MODES: tuple[str, ...] = ("local", "prod", "nginx")
-DEFAULT_INTERNAL_SUBNET = "172.31.240.0/24"
-SMALLEST_TRUSTED_PREFIX = {4: 8, 6: 48}
-TASKIQ_PACKAGE = "src/infrastructure/taskiq"
-"""The feature whose worker and scheduler services the compose files carry."""
-
-_TEMPLATES_ROOT = Path(__file__).parent / "templates"
-
-
-def validated_subnet(value: str) -> str:
- """The subnet in the form ``ipaddress`` reads, refusing one that trusts too much.
-
- Takes a network of ``/8`` or smaller for IPv4, ``/48`` or smaller for IPv6.
-
- Raises:
- ValueError: ``value`` is not a network address, carries host bits, or covers
- more than the smallest prefix its family allows.
- """
- try:
- network = ip_network(value, strict=True)
- except ValueError as error:
- raise ValueError(f"{value!r} is not a network address, such as 172.31.240.0/24.") from error
-
- smallest = SMALLEST_TRUSTED_PREFIX[network.version]
- if network.prefixlen < smallest:
- raise ValueError(f"{value!r} covers {network.num_addresses} addresses; name a range of /{smallest} or smaller.")
-
- return str(network)
-
-
-class DeployFeature(Feature):
- def manifest(self) -> FeatureManifest:
- return FeatureManifest(
- name="deploy",
- version="1.0",
- summary="Generate a docker-compose.yml for local, prod, or nginx-fronted deployments.",
- )
-
- def plan(self, params: dict[str, Any], project: ProjectContext) -> FeaturePlan:
- mode = params.get("mode")
- if mode not in SUPPORTED_MODES:
- raise ValueError(f"Unsupported deploy mode: {mode!r}. Choose one of {SUPPORTED_MODES}.")
-
- project_name = params.get("project_name") or project.repo_root.name
- api_port = int(params.get("api_port", 8000))
- workers = int(params.get("workers", 4))
- postgres_image = params.get("postgres_image", "postgres:16-alpine")
- redis_image = params.get("redis_image", "redis:7-alpine")
- nginx_image = params.get("nginx_image", "nginx:1.27-alpine")
- backend_context = params.get("backend_context", "./backend")
- build_context = params.get("build_context", ".")
- backend_dockerfile = params.get("backend_dockerfile", "backend/Dockerfile")
- env_file = params.get("env_file", "./backend/.env")
- internal_subnet = validated_subnet(params.get("internal_subnet", DEFAULT_INTERNAL_SUBNET))
- taskiq = (project.backend_dir / TASKIQ_PACKAGE).is_dir()
-
- context = {
- "mode": mode,
- "project_name": project_name,
- "api_port": api_port,
- "workers": workers,
- "postgres_image": postgres_image,
- "redis_image": redis_image,
- "nginx_image": nginx_image,
- "backend_context": backend_context,
- "build_context": build_context,
- "backend_dockerfile": backend_dockerfile,
- "env_file": env_file,
- "internal_subnet": internal_subnet,
- "taskiq": taskiq,
- }
-
- compose_target = Path(params.get("compose_target") or (project.repo_root / "docker-compose.yml"))
- files: list[FileOp] = [
- FileOp(template=f"{mode}/docker-compose.yml.j2", target=compose_target),
- ]
- if mode == "nginx":
- nginx_target = Path(params.get("nginx_conf_target") or (project.repo_root / "nginx" / "default.conf"))
- files.append(FileOp(template="nginx/default.conf.j2", target=nginx_target))
-
- return FeaturePlan(
- manifest=self.manifest(),
- templates_root=_TEMPLATES_ROOT,
- template_context=context,
- files=tuple(files),
- )
diff --git a/cli/src/cli/features/base.py b/cli/src/cli/features/base.py
deleted file mode 100644
index 1bd8f019..00000000
--- a/cli/src/cli/features/base.py
+++ /dev/null
@@ -1,98 +0,0 @@
-"""Feature contracts: manifest, plan, base class, and operation types.
-
-The shapes here are designed so that today's "render templates to disk"
-features and tomorrow's "drop a module + edit settings + run a
-migration" features can both describe themselves with the same plan
-schema. Installers grow capabilities over time; manifests don't have
-to change.
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any
-
-from ..lib.project import ProjectContext
-
-
-@dataclass(frozen=True)
-class FeatureManifest:
- """Static metadata about a feature.
-
- The manifest is the part that's safe to read without executing
- anything — used by ``bp feature list`` / ``bp feature info`` to
- describe what's available.
- """
-
- name: str
- version: str
- summary: str
- requires_features: tuple[str, ...] = ()
- adds_dependencies: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class FileOp:
- """Render a Jinja template and write it to ``target``.
-
- ``template`` is interpreted relative to the feature's templates
- directory. ``target`` is an absolute path on the user's disk.
- """
-
- template: str
- target: Path
- overwrite: bool = False
- skip_if_exists: bool = False
- executable: bool = False
-
-
-@dataclass(frozen=True)
-class Codemod:
- """Reserved for AST-aware edits to existing source files.
-
- Not implemented in v1. Defining the type here means feature plans
- can reference codemods today without breaking the manifest schema
- when the installer learns to execute them.
- """
-
- target: Path
- operation: str
- params: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass(frozen=True)
-class Hook:
- """Reserved for post-install commands (alembic revisions, scripts, etc.)."""
-
- name: str
- command: tuple[str, ...]
- cwd: Path | None = None
-
-
-@dataclass(frozen=True)
-class FeaturePlan:
- """Concrete description of what a feature wants to do, given parameters."""
-
- manifest: FeatureManifest
- templates_root: Path | None
- template_context: dict[str, Any] = field(default_factory=dict)
- files: tuple[FileOp, ...] = ()
- codemods: tuple[Codemod, ...] = ()
- hooks: tuple[Hook, ...] = ()
-
-
-class Feature(ABC):
- """Base class for all features.
-
- Subclasses declare a static ``manifest()`` and an instance-method
- ``plan(params, project)`` that yields the concrete plan for the
- current invocation.
- """
-
- @abstractmethod
- def manifest(self) -> FeatureManifest: ...
-
- @abstractmethod
- def plan(self, params: dict[str, Any], project: ProjectContext) -> FeaturePlan: ...
diff --git a/cli/src/cli/features/installer.py b/cli/src/cli/features/installer.py
deleted file mode 100644
index e2692ae8..00000000
--- a/cli/src/cli/features/installer.py
+++ /dev/null
@@ -1,88 +0,0 @@
-"""Execute a ``FeaturePlan`` against the user's project.
-
-V1 supports file rendering only. Codemods and hooks raise
-``NotImplementedError`` so plans can declare them today and the
-installer will gain support over time without breaking the contract.
-"""
-
-from __future__ import annotations
-
-import stat
-from dataclasses import dataclass, field
-from pathlib import Path
-
-from ..lib.prompts import confirm_overwrite, info, success, warn
-from ..lib.render import Renderer
-from .base import FeaturePlan
-
-
-@dataclass
-class InstallResult:
- """Summary of what an installer pass actually did."""
-
- files_written: list[Path] = field(default_factory=list)
- files_skipped: list[Path] = field(default_factory=list)
-
-
-class FeatureInstaller:
- """Apply a ``FeaturePlan`` to disk.
-
- Construction options control the prompting / I/O behavior.
- """
-
- def __init__(self, *, dry_run: bool = False, assume_yes: bool = False, quiet: bool = False) -> None:
- self.dry_run = dry_run
- self.assume_yes = assume_yes
- self.quiet = quiet
-
- def apply(self, plan: FeaturePlan) -> InstallResult:
- result = InstallResult()
- if plan.codemods:
- raise NotImplementedError("Codemod operations are not yet supported by the installer.")
- if plan.hooks:
- raise NotImplementedError("Post-install hooks are not yet supported by the installer.")
-
- renderer: Renderer | None = None
- if plan.files and plan.templates_root is not None:
- renderer = Renderer(plan.templates_root)
-
- for op in plan.files:
- if op.target.exists():
- if op.skip_if_exists:
- if not self.quiet:
- warn(f"skip {op.target} (exists)")
- result.files_skipped.append(op.target)
- continue
- if not op.overwrite and not self.dry_run:
- if not confirm_overwrite(str(op.target), assume_yes=self.assume_yes):
- if not self.quiet:
- warn(f"skip {op.target} (kept existing)")
- result.files_skipped.append(op.target)
- continue
-
- if renderer is None:
- raise RuntimeError(f"Plan has files but no templates_root: cannot render {op.template!r}")
-
- content = renderer.render(op.template, plan.template_context)
-
- if self.dry_run:
- if not self.quiet:
- replacing = " (replacing what is there)" if op.target.exists() else ""
- info(f"would write {op.target} ({len(content)} bytes){replacing}")
- result.files_written.append(op.target)
- continue
-
- op.target.parent.mkdir(parents=True, exist_ok=True)
- op.target.write_text(content, encoding="utf-8")
- if op.executable:
- _make_executable(op.target)
- if not self.quiet:
- success(f"wrote {op.target}")
- result.files_written.append(op.target)
-
- return result
-
-
-def _make_executable(path: Path) -> None:
- current = path.stat().st_mode
- path.chmod(current | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
diff --git a/cli/src/cli/features/registry.py b/cli/src/cli/features/registry.py
deleted file mode 100644
index 85c3ae4a..00000000
--- a/cli/src/cli/features/registry.py
+++ /dev/null
@@ -1,44 +0,0 @@
-"""Look up features by name across in-tree and plugin sources.
-
-In-tree features are imported lazily so that adding new ones doesn't
-slow down every CLI invocation. Plugin features come from the
-``bp.features`` entry-point group.
-"""
-
-from __future__ import annotations
-
-import warnings
-
-from .. import plugins as _plugins
-from ._builtins.deploy.feature import DeployFeature
-from .base import Feature
-
-
-def _builtin_features() -> dict[str, Feature]:
- """Return in-tree features."""
- return {
- "deploy": DeployFeature(),
- }
-
-
-def all_features() -> dict[str, Feature]:
- """Return ``{name: feature}`` for every in-tree and plugin feature.
-
- In-tree features take precedence on name collisions; a warning is
- surfaced when a plugin tries to shadow a built-in.
- """
- found: dict[str, Feature] = dict(_builtin_features())
- for name, feature in _plugins.discover_feature_plugins().items():
- if name in found:
- warnings.warn(
- f"feature plugin {name!r} shadows a built-in; ignoring plugin.",
- RuntimeWarning,
- stacklevel=2,
- )
- continue
- found[name] = feature
- return found
-
-
-def get_feature(name: str) -> Feature | None:
- return all_features().get(name)
diff --git a/cli/src/cli/lib/__init__.py b/cli/src/cli/lib/__init__.py
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/src/cli/lib/project.py b/cli/src/cli/lib/project.py
deleted file mode 100644
index 5501a4e8..00000000
--- a/cli/src/cli/lib/project.py
+++ /dev/null
@@ -1,70 +0,0 @@
-"""Locate the user's project on disk and read context from it.
-
-The CLI is shipped inside ``backend/src/cli`` of the boilerplate, but
-when invoked it operates on whichever directory the user is in. These
-helpers resolve the repo root, the backend directory, and read values
-from the project's ``.env`` files without importing the application.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-from pathlib import Path
-
-
-@dataclass(frozen=True)
-class ProjectContext:
- """Resolved paths the CLI needs to operate on the user's repo."""
-
- repo_root: Path
- backend_dir: Path
-
- @property
- def env_file(self) -> Path:
- return self.backend_dir / ".env"
-
- @property
- def env_example(self) -> Path:
- return self.backend_dir / ".env.example"
-
- @property
- def compose_file(self) -> Path:
- return self.repo_root / "docker-compose.yml"
-
-
-def discover_project(start: Path | None = None) -> ProjectContext:
- """Walk up from ``start`` looking for a ``backend/pyproject.toml`` marker.
-
- Falls back to the current working directory if no marker is found —
- the caller is responsible for deciding whether that's acceptable.
- """
- current = (start or Path.cwd()).resolve()
- for candidate in [current, *current.parents]:
- if (candidate / "backend" / "pyproject.toml").is_file():
- return ProjectContext(repo_root=candidate, backend_dir=candidate / "backend")
- if (candidate / "pyproject.toml").is_file() and candidate.name == "backend":
- return ProjectContext(repo_root=candidate.parent, backend_dir=candidate)
- return ProjectContext(repo_root=current, backend_dir=current / "backend")
-
-
-def read_env_value(env_path: Path, key: str) -> str | None:
- """Read a single value from a ``.env``-style file.
-
- Returns ``None`` if the file is missing or the key isn't set. Quotes
- around the value (single or double) are stripped. Lines beginning
- with ``#`` are skipped.
- """
- if not env_path.is_file():
- return None
- for raw in env_path.read_text(encoding="utf-8").splitlines():
- line = raw.strip()
- if not line or line.startswith("#") or "=" not in line:
- continue
- name, _, value = line.partition("=")
- if name.strip() != key:
- continue
- value = value.strip()
- if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
- value = value[1:-1]
- return value
- return None
diff --git a/cli/src/cli/lib/prompts.py b/cli/src/cli/lib/prompts.py
deleted file mode 100644
index 49cf3b9c..00000000
--- a/cli/src/cli/lib/prompts.py
+++ /dev/null
@@ -1,32 +0,0 @@
-"""Consistent prompt helpers used across the CLI.
-
-Centralizes ``--yes`` (assume-yes) and ``--quiet`` handling so individual
-commands don't each invent their own.
-"""
-
-from __future__ import annotations
-
-import typer
-
-
-def confirm_overwrite(path: str, *, assume_yes: bool) -> bool:
- """Confirm overwriting an existing file. Returns True to proceed."""
- if assume_yes:
- return True
- return typer.confirm(f"{path} already exists. Overwrite?", default=False)
-
-
-def info(message: str) -> None:
- typer.echo(message)
-
-
-def success(message: str) -> None:
- typer.secho(message, fg=typer.colors.GREEN)
-
-
-def warn(message: str) -> None:
- typer.secho(message, fg=typer.colors.YELLOW)
-
-
-def error(message: str) -> None:
- typer.secho(message, fg=typer.colors.RED, err=True)
diff --git a/cli/src/cli/lib/render.py b/cli/src/cli/lib/render.py
deleted file mode 100644
index f43b0ac3..00000000
--- a/cli/src/cli/lib/render.py
+++ /dev/null
@@ -1,33 +0,0 @@
-"""Jinja-based template rendering for in-tree features and plugins.
-
-A feature points at a directory containing Jinja templates. ``Renderer``
-loads them with a sandboxed environment, applies the supplied context,
-and writes the result to disk.
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any
-
-from jinja2 import Environment, FileSystemLoader, StrictUndefined
-
-
-class Renderer:
- """Render Jinja templates from a feature's templates directory."""
-
- def __init__(self, templates_root: Path) -> None:
- if not templates_root.is_dir():
- raise FileNotFoundError(f"Templates directory does not exist: {templates_root}")
- self.templates_root = templates_root
- self.env = Environment(
- loader=FileSystemLoader(str(templates_root)),
- keep_trailing_newline=True,
- undefined=StrictUndefined,
- autoescape=False,
- )
-
- def render(self, template_path: str, context: dict[str, Any]) -> str:
- """Render ``template_path`` (relative to ``templates_root``) with ``context``."""
- template = self.env.get_template(template_path)
- return template.render(**context)
diff --git a/cli/src/cli/plugins.py b/cli/src/cli/plugins.py
deleted file mode 100644
index 7326b5f2..00000000
--- a/cli/src/cli/plugins.py
+++ /dev/null
@@ -1,109 +0,0 @@
-"""Plugin discovery for the bp CLI.
-
-Two extension points, kept deliberately separate:
-
-- ``bp.commands`` — a Typer sub-app mounted under the root, e.g.
- ``bp aws deploy``. Plugin packages declare entry points whose values
- resolve to a ``typer.Typer`` instance.
-
-- ``bp.features`` — a ``Feature`` instance that ``bp feature`` can list
- and apply. Plugin packages declare entry points whose values resolve
- to ``Feature`` instances (or callables that return one).
-
-A broken plugin must not break the CLI. Discovery wraps each load in a
-broad except and surfaces a warning so the user can still operate the
-working subset.
-"""
-
-from __future__ import annotations
-
-import sys
-import warnings
-from importlib.metadata import EntryPoint, entry_points
-
-import typer
-
-from .features.base import Feature
-
-COMMANDS_GROUP = "bp.commands"
-FEATURES_GROUP = "bp.features"
-
-
-def _safe_load(ep: EntryPoint) -> object | None:
- try:
- loaded: object = ep.load()
- except Exception as exc:
- warnings.warn(
- f"Failed to load plugin {ep.name!r} from {ep.value!r}: {exc!s}",
- RuntimeWarning,
- stacklevel=2,
- )
- return None
- return loaded
-
-
-def discover_command_plugins() -> dict[str, typer.Typer]:
- """Return ``{name: typer_app}`` for every healthy ``bp.commands`` entry point."""
- found: dict[str, typer.Typer] = {}
- for ep in entry_points(group=COMMANDS_GROUP):
- loaded = _safe_load(ep)
- if loaded is None:
- continue
- if isinstance(loaded, typer.Typer):
- found[ep.name] = loaded
- else:
- warnings.warn(
- f"Plugin {ep.name!r} resolved to {type(loaded).__name__}, expected typer.Typer; ignoring.",
- RuntimeWarning,
- stacklevel=2,
- )
- return found
-
-
-def discover_feature_plugins() -> dict[str, Feature]:
- """Return ``{name: feature}`` for every healthy ``bp.features`` entry point.
-
- Entry-point values may be either a ``Feature`` instance or a callable
- that returns one (helpful when constructing features needs the project
- context).
- """
- found: dict[str, Feature] = {}
- for ep in entry_points(group=FEATURES_GROUP):
- loaded = _safe_load(ep)
- if loaded is None:
- continue
- candidate = loaded() if callable(loaded) and not isinstance(loaded, Feature) else loaded
- if isinstance(candidate, Feature):
- found[ep.name] = candidate
- else:
- warnings.warn(
- f"Feature plugin {ep.name!r} resolved to {type(candidate).__name__}, expected Feature; ignoring.",
- RuntimeWarning,
- stacklevel=2,
- )
- return found
-
-
-def emit_plugin_warnings_to_stderr() -> None:
- """Route plugin-load warnings to stderr so CLI output stays clean."""
- warnings.filterwarnings("default", category=RuntimeWarning, module=__name__)
- if not any(isinstance(h, _StderrWarningHandler) for h in _installed_handlers()):
- warnings.showwarning = _StderrWarningHandler()
-
-
-class _StderrWarningHandler:
- def __call__(
- self,
- message: Warning | str,
- category: type[Warning],
- filename: str,
- lineno: int,
- file: object = None,
- line: str | None = None,
- ) -> None:
- print(f"warning: {message}", file=sys.stderr)
-
-
-def _installed_handlers() -> list[object]:
- handler = warnings.showwarning
- return [handler] if handler is not None else []
diff --git a/cli/src/cli/py.typed b/cli/src/cli/py.typed
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/tests/__init__.py b/cli/tests/__init__.py
deleted file mode 100644
index e69de29b..00000000
diff --git a/cli/tests/test_deploy_command.py b/cli/tests/test_deploy_command.py
deleted file mode 100644
index 4ef410c4..00000000
--- a/cli/tests/test_deploy_command.py
+++ /dev/null
@@ -1,121 +0,0 @@
-"""``bp deploy generate``: what it writes, and what a dry run leaves alone."""
-
-import pytest
-import yaml
-from typer.testing import CliRunner
-
-from cli.commands import deploy
-
-runner = CliRunner()
-
-
-@pytest.fixture
-def project(tmp_path):
- """A directory that looks enough like a project for the command to run in."""
- (tmp_path / "backend").mkdir()
- (tmp_path / "pyproject.toml").write_text("[project]\nname = 'example'\n")
-
- return tmp_path
-
-
-def test_a_dry_run_writes_nothing_and_creates_no_directory(project):
- target = project / "generated"
-
- result = runner.invoke(deploy.app, ["nginx", "-o", str(target), "--dry-run"])
-
- assert result.exit_code == 0, result.output
- assert "would write" in result.output
- assert not target.exists()
-
-
-def test_a_dry_run_over_an_existing_file_asks_nothing(project):
- compose = project / "docker-compose.yml"
- compose.write_text("keep me\n")
-
- result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--dry-run"], input="")
-
- assert result.exit_code == 0, result.output
- assert compose.read_text() == "keep me\n"
- assert "Overwrite" not in result.output
-
-
-def test_a_project_with_taskiq_gets_its_worker_and_scheduler(project):
- """The services are read off the project: this one carries the feature."""
- (project / "backend/src/infrastructure/taskiq").mkdir(parents=True)
-
- result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"])
-
- assert result.exit_code == 0, result.output
- compose = (project / "docker-compose.yml").read_text()
- assert "taskiq worker src.infrastructure.taskiq.worker:default_broker" in compose
- assert "taskiq scheduler src.infrastructure.taskiq.scheduler:scheduler" in compose
-
-
-def test_a_project_without_taskiq_gets_neither(project):
- result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"])
-
- assert result.exit_code == 0, result.output
- services = yaml.safe_load((project / "docker-compose.yml").read_text())["services"]
- assert "worker" not in services
- assert "scheduler" not in services
-
-
-def test_generating_writes_the_compose_file(project):
- result = runner.invoke(deploy.app, ["prod", "-o", str(project), "--yes"])
-
- assert result.exit_code == 0, result.output
- assert (project / "docker-compose.yml").read_text().startswith("# Generated by")
-
-
-@pytest.mark.parametrize(
- "subnet",
- [
- "*",
- "0.0.0.0/0",
- "10.0.0.0/7",
- "172.31.240.1/24",
- "not-a-subnet",
- "172.31.240.0/33",
- "::/0",
- "fd00::/8",
- "fd00::/47",
- "fd00::1/48",
- ],
-)
-def test_a_subnet_that_trusts_too_much_is_refused(project, subnet: str):
- """The range decides whose forwarded headers the app believes."""
- result = runner.invoke(deploy.app, ["nginx", "-o", str(project), "--internal-subnet", subnet, "--yes"])
-
- assert result.exit_code == 1
- assert "--internal-subnet" in result.output
- assert not (project / "docker-compose.yml").exists()
-
-
-@pytest.mark.parametrize("subnet", ["172.31.240.0/24", "10.1.2.0/28", "192.168.0.0/16", "fd00::/48", "fd00::/64"])
-def test_a_subnet_that_names_a_network_is_accepted(project, subnet: str):
- result = runner.invoke(deploy.app, ["nginx", "-o", str(project), "--internal-subnet", subnet, "--yes"])
-
- assert result.exit_code == 0, result.output
- assert f'- subnet: "{subnet}"' in (project / "docker-compose.yml").read_text()
-
-
-@pytest.mark.parametrize("mode", ["prod", "nginx"])
-def test_the_next_steps_migrate_before_starting_the_stack(project, mode: str):
- """The API doesn't create its own schema here, and nothing waits on the migrate service."""
- result = runner.invoke(deploy.app, [mode, "-o", str(project), "--yes"])
-
- assert result.exit_code == 0, result.output
- steps = [line.strip() for line in result.output.splitlines()]
- migrate = steps.index("docker compose --profile migrate run --rm migrate")
-
- assert "generate and commit the baseline first" in result.output
- assert "database/migrations.md" in result.output
- assert steps.index("docker compose build") < migrate < steps.index("docker compose up -d")
-
-
-def test_the_local_next_steps_just_start_the_stack(project):
- result = runner.invoke(deploy.app, ["local", "-o", str(project), "--yes"])
-
- assert result.exit_code == 0, result.output
- assert "docker compose up --build" in result.output
- assert "migrate" not in result.output
diff --git a/cli/tests/test_env_command.py b/cli/tests/test_env_command.py
deleted file mode 100644
index 0be6adbe..00000000
--- a/cli/tests/test_env_command.py
+++ /dev/null
@@ -1,216 +0,0 @@
-"""``bp env``: what it reports about a configuration, and what it refuses."""
-
-import secrets
-import warnings
-from types import SimpleNamespace
-
-import pytest
-from typer.testing import CliRunner
-
-import cli.app
-from cli import plugins
-from cli.commands import env
-
-runner = CliRunner()
-
-
-def _backend_settings(**overrides):
- """The app's own settings object, as the command builds it.
-
- ``CREATE_TABLES_ON_STARTUP``, ``EMAIL_BACKEND`` and ``FRONTEND_URL`` are passed in because
- their defaults describe a development environment, not the production one these stand for.
- """
- module = env._app_module("src.infrastructure.config.settings")
- fields = {
- "ENVIRONMENT": "production",
- "CREATE_TABLES_ON_STARTUP": False,
- "EMAIL_BACKEND": "smtp",
- "FRONTEND_URL": "https://app.example.com",
- }
-
- return module.Settings(**(fields | overrides))
-
-
-def _settings_module_answering(settings) -> SimpleNamespace:
- """The settings module as the command uses it: the settings it asks for, and the enum it reads."""
- module = env._app_module("src.infrastructure.config.settings")
-
- return SimpleNamespace(get_settings=lambda: settings, EnvironmentOption=module.EnvironmentOption)
-
-
-@pytest.fixture
-def audited(monkeypatch):
- """Answer the command with a validator whose audit we control, and collect what it was handed."""
-
- def audit_returning(errors: list[str], warnings: list[str]) -> list:
- handed: list = []
-
- class _Validator:
- def __init__(self, settings):
- handed.append(settings)
- self.settings = settings
-
- def audit(self):
- return errors, warnings
-
- def _is_production(self):
- return True
-
- module = SimpleNamespace(ProductionSecurityValidator=_Validator)
- settings = SimpleNamespace(ENVIRONMENT="development")
- settings.model_copy = lambda update: SimpleNamespace(**(vars(settings) | update))
- answered = _settings_module_answering(settings)
- monkeypatch.setattr(env, "_app_module", lambda name: module if "production_validator" in name else answered)
-
- return handed
-
- return audit_returning
-
-
-def test_warnings_are_reported_even_when_something_is_critical(audited):
- """The warnings used to be computed only when nothing critical was found."""
- audited(["SECRET_KEY is using a default value"], ["Redis has no password"])
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 1
- assert "SECRET_KEY" in result.output
- assert "Redis has no password" in result.output
-
-
-def test_warnings_alone_do_not_fail_the_command(audited):
- audited([], ["Redis has no password"])
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 0
- assert "Redis has no password" in result.output
-
-
-def test_a_clean_configuration_says_so(audited):
- audited([], [])
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 0
- assert "No issues found" in result.output
-
-
-def test_the_audited_settings_carry_the_environment_as_the_app_reads_it(audited):
- """The app factory and the logger read ``ENVIRONMENT.value``, which a plain string has not."""
- handed = audited([], [])
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 0
- assert handed[0].ENVIRONMENT.value == "production"
-
-
-def test_gen_secret_produces_a_key_the_validator_accepts():
- """The command is what operators run to satisfy the validator, so ask the validator."""
- result = runner.invoke(env.app, ["gen-secret"])
- key = result.output.strip()
-
- settings = _backend_settings(SECRET_KEY=key)
- validator_module = env._app_module("src.infrastructure.security.production_validator")
-
- assert result.exit_code == 0
- assert len(key) == 64
- assert not validator_module.ProductionSecurityValidator(settings)._is_insecure_secret_key()
-
-
-REFUSED_BY_THE_APP = "e48102bfe6ac2eac3aa8623456789a6030e4fa7dee3cd173bfb7941f2f819678"
-
-
-def test_a_key_the_app_would_refuse_is_drawn_again(monkeypatch):
- """One hex key in twelve million runs through eight digits, which production refuses."""
- accepted = secrets.token_hex(32)
- draws = iter([REFUSED_BY_THE_APP, accepted])
- monkeypatch.setattr(env.secrets, "token_hex", lambda size: next(draws))
-
- result = runner.invoke(env.app, ["gen-secret"])
-
- assert result.exit_code == 0
- assert result.output.strip() == accepted
-
-
-def test_the_first_draw_is_printed_outside_a_project(monkeypatch, tmp_path):
- """Nothing to ask: the rules live in the project, and the command still answers."""
- monkeypatch.chdir(tmp_path)
-
- result = runner.invoke(env.app, ["gen-secret"])
-
- assert result.exit_code == 0
- assert len(result.output.strip()) == 64
-
-
-def test_a_plugin_warning_is_written_to_stderr(capsys):
- """On stdout it would corrupt whatever the caller is piping command output into."""
- plugins.emit_plugin_warnings_to_stderr()
-
- warnings.showwarning("entry point 'acme' failed to load", RuntimeWarning, "plugins.py", 1)
- captured = capsys.readouterr()
-
- assert "acme" in captured.err
- assert captured.out == ""
-
-
-def test_mounting_the_plugins_routes_their_warnings(monkeypatch):
- routed: list[bool] = []
- monkeypatch.setattr(plugins, "emit_plugin_warnings_to_stderr", lambda: routed.append(True))
-
- cli.app._mount_command_plugins()
-
- assert routed == [True]
-
-
-@pytest.fixture
-def real_validator(monkeypatch):
- """The command with the app's own validator, against settings the test picks."""
- validator_module = env._app_module("src.infrastructure.security.production_validator")
-
- def with_settings(**overrides):
- answered = _settings_module_answering(_backend_settings(**overrides))
- monkeypatch.setattr(env, "_app_module", lambda name: validator_module if "production_validator" in name else answered)
-
- return with_settings
-
-
-def test_validate_runs_the_real_validator_against_a_weak_configuration(real_validator):
- """The stubs above pin the report's shape; this pins that the command really audits."""
- real_validator(SECRET_KEY="insecure-secret-key-change-this", POSTGRES_PASSWORD="postgres")
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 1
- assert "SECRET_KEY" in result.output
- assert "Database is using default credentials" in result.output
-
-
-def test_every_finding_names_the_environment_being_audited_for(real_validator):
- """The command audits as production, so a finding that names a development one is a lie."""
- real_validator(ENVIRONMENT="development", EMAIL_BACKEND="console", CREATE_TABLES_ON_STARTUP=True)
-
- result = runner.invoke(env.app, ["validate"])
-
- assert "in production" in result.output
- assert "in development" not in result.output
-
-
-def test_validate_reports_a_strong_configuration_as_clean(real_validator):
- """The real validator, with nothing to complain about."""
- real_validator(
- SECRET_KEY=secrets.token_hex(32),
- POSTGRES_PASSWORD="a-strong-database-password",
- CORS_ORIGINS="https://app.example.com",
- ADMIN_ENABLED=False,
- DEBUG=False,
- OPENAPI_URL="",
- CACHE_REDIS_PASSWORD="redis-password",
- RATE_LIMITER_REDIS_PASSWORD="redis-password",
- SESSION_SECURE_COOKIES=True,
- )
-
- result = runner.invoke(env.app, ["validate"])
-
- assert result.exit_code == 0, result.output
diff --git a/docs/assets/build-diagrams.cjs b/docs/assets/build-diagrams.cjs
index 5a26d110..15731d62 100644
--- a/docs/assets/build-diagrams.cjs
+++ b/docs/assets/build-diagrams.cjs
@@ -23,7 +23,7 @@ const marker = (line) => ``;
-const compositionRoot = ({ primary, body, muted, line, panel }) => `