tempest-fastapi-sdk 0.294.0__tar.gz → 0.296.0__tar.gz

{tempest_fastapi_sdk-0.294.0 → tempest_fastapi_sdk-0.296.0}/CHANGELOG.md

@@ -5,6 +5,189 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.296.0] — 2026-09-22
+
+O `500` de uma exceção não tratada saía **fora** do `CORSMiddleware`. O
+navegador descartava a resposta, e o front via só `TypeError: Failed to
+fetch` — sem status, sem `code`, sem `X-Request-ID`. O scaffold do
+`tempest new` gerava exatamente essa pilha (#287).
+
+### Fixed
+
+- **O envelope de 500 passa pela pilha de middleware.** O Starlette
+  executa o handler de `Exception` no `ServerErrorMiddleware`, a camada
+  mais externa, então o envelope nunca voltava por `CORSMiddleware` nem
+  por `RequestIDMiddleware`. Medido antes da correção, com `RequestID` +
+  `apply_cors` + `register_exception_handlers` na ordem do template: `500`
+  sem `Access-Control-Allow-Origin`, sem `X-Request-ID` e com `details: {}`.
+  Agora `register_exception_handlers` instala também o
+  `ErrorEnvelopeMiddleware` como o middleware de usuário **mais interno**
+  (`append` em `user_middleware`, enquanto `add_middleware` sempre insere
+  no índice 0), e o mesmo `500` sai com o header de CORS, com o
+  `X-Request-ID` e com `details.request_id` igual ao header — **em
+  qualquer ordem** das três chamadas, e por isso o template não precisou
+  mudar. A camada não decide CORS: origem fora da allowlist continua sem
+  header no 500. O handler de `Exception` continua registrado para a
+  exceção levantada por um middleware, que a camada interna não vê.
+  Medido no Starlette 0.46.0 (o piso que `fastapi>=0.141.1` aceita) e no
+  1.6.0.
+
+### Added
+
+- **`ErrorEnvelopeMiddleware`** (e o alias `ErrorEnvelopeHandler`, em
+  `tempest_fastapi_sdk.api.middlewares`), para quem monta a pilha à mão
+  com um handler próprio.
+
+### Changed
+
+- **`register_exception_handlers` levanta `RuntimeError` numa aplicação
+  que já montou a pilha** (já serviu requisição ou subiu). Antes a
+  chamada tardia registrava handlers que o Starlette nunca lia; agora
+  falha em vez de parecer funcionar, e falha antes de registrar qualquer
+  handler, então a aplicação recusada fica intocada. Chamar duas vezes
+  instala a camada
+  uma vez só, com o handler da segunda chamada.
+- A exceção **continua sendo re-levantada** depois do envelope, como o
+  `ServerErrorMiddleware` já fazia: o servidor ASGI segue logando, e um
+  `TestClient` com o default `raise_server_exceptions=True` segue
+  levantando no teste do consumidor. Falha depois de a resposta começar
+  (stream quebrado no meio) é re-levantada sem segunda resposta.
+- **Stream quebrado no meio passa a chegar ao `on_server_error`.** O
+  callback vai como `BackgroundTask` da resposta de erro, e uma resposta
+  que nunca é enviada nunca roda a background: medido antes, a falha era
+  logada e o `on_server_error` não disparava nenhuma vez. Agora a camada
+  interna roda a background da resposta que o handler construiu, e o
+  callback dispara uma vez, com o log também uma vez.
+
+## [0.295.0] — 2026-09-19
+
+A CLI sabia **criar** serviço e rodar os gates. Não sabia **operar** o
+serviço que já existe: nada listava as rotas servidas, nada exportava o
+contrato, nada conectava nas dependências, e mexer em flag, cache, fila,
+sessão ou bucket era `redis-cli`, script descartável ou SQL na mão.
+
+### Added
+
+- **`tempest secrets generate|init|vapid`.** O grupo só sabia
+  `rotate`. `generate` imprime N segredos (crus, `KEY=value` com
+  `--keys`, ou JSON) e **não escreve arquivo nenhum** — é o que se pipa
+  num secret manager; `--count` junto de `--keys` é erro de uso, porque
+  os dois dizem a mesma coisa. `init` preenche só as chaves ausentes,
+  vazias ou ainda com o placeholder `change-me-change-me-change-me-32`
+  que o `tempest new` escreve (os valores que o `check_secrets` reporta
+  como `security.W001`/`W004`), mantém toda chave já configurada e
+  portanto é idempotente; `--force` substitui valor real e faz backup
+  antes. `vapid` gera o par P-256 do Web Push no formato que o
+  `WebPushSettings` e o `pywebpush` leem — escalar de 32 bytes e ponto
+  não-comprimido de 65, base64url sem padding — e **recusa sobrescrever
+  um par existente sem `--force`**, porque trocar o par invalida toda
+  subscrição ativa de browser. O formato não foi deduzido: a chave
+  privada é lida de volta por `py_vapid.Vapid02` e assina um header no
+  teste.
+
+- **`tempest routes`.** Lista toda rota efetiva, com router montado
+  expandido. Lê `fastapi.routing.iter_route_contexts` — a mesma
+  expansão que o gerador de OpenAPI percorre — porque desde o FastAPI
+  0.141.1 o `include_router` guarda uma entrada `_IncludedRouter` e uma
+  compreensão sobre `app.routes` não lista **nenhum** path do router
+  incluído. Rota fora do schema aparece com `SCHEMA=no`, e a coluna
+  `GUARDS` nomeia as dependências herdadas do `include_router`, não só
+  as declaradas na rota.
+
+- **`tempest openapi-export [--check]`.** Escreve o documento OpenAPI do
+  próprio serviço (JSON, ou YAML com o extra `[openapi]`) sem subir
+  nada. `--check` compara com o arquivo commitado e **nomeia** o que
+  mudou (`+ DELETE /x`, `- GET /y`, `~ /z changed`), saindo 1 — "a spec
+  mudou" não é mensagem revisável.
+
+- **`tempest db check`.** Roda a comparação de autogenerate do Alembic e
+  sai 1 listando as operações que uma revision conteria. O
+  `revision --autogenerate` grava o diff quando alguém pede; nada
+  percebia quando ninguém pediu.
+
+- **`tempest serve` e `tempest shell`.** O `serve` entrega ao uvicorn a
+  **string** de import, nunca o objeto — o reloader reimporta no
+  processo filho, e passar a instância transforma `--reload` em nada, em
+  silêncio. `--reload` tem três estados, então `--no-reload` desliga de
+  verdade um `SERVER_RELOAD=true`; junto de `--workers` sai 2. O `shell`
+  abre um REPL com `settings`, cada model mapeado **que o projeto
+  define** (a `BaseModel` do SDK fica de fora), `select`, `text` e uma
+  `session` aberta; compila com `ast.PyCF_ALLOW_TOP_LEVEL_AWAIT` e roda
+  a corrotina **no loop em que a sessão foi aberta** — um helper
+  `run(coro)` pareceria equivalente e levantaria `MissingGreenlet` no
+  primeiro lazy load.
+
+- **`tempest doctor`.** O `check-config` lê as settings e não abre
+  socket; este conecta de verdade em banco, Redis, RabbitMQ, SMTP e
+  MinIO, dobra o registry de checagens estáticas e sai 1 em qualquer
+  falha, servindo de smoke test de deploy. Capacidade não configurada
+  aparece como `skip`, **nunca** `ok` — e default de mixin conta como
+  não configurado (`SMTP_HOST=localhost`, `MINIO_ENDPOINT=localhost:9000`),
+  comparado contra `model_fields[campo].default`, a régua do
+  `check_secrets`.
+
+- **`tempest user show|activate|deactivate|sessions|delete`.** O `show`
+  imprime toda coluna mapeada com o `hashed_password` redigido.
+  `deactivate` revoga os refresh tokens **na mesma transação** que o
+  flag, porque `is_active=False` sozinho não encerra nada. `sessions`
+  lista (ou revoga com `--revoke`, contando só o que aquela execução
+  matou); usuário sem sessão sai 0. `delete` apaga os refresh tokens
+  antes da linha do usuário — a FK scaffoldada não tem
+  `ON DELETE CASCADE`, então a ordem óbvia falharia citando uma
+  constraint em vez da causa — e exige `--yes` fora de um TTY.
+
+- **`tempest flags` e `tempest cache`.** `flags list/get/enable/disable`
+  falam pelo `RedisFeatureFlagBackend`; `get` separa `unset` (código 1,
+  o serviço cai no default do chamador) de um `off` guardado (código 0).
+  `cache ping/stats/flush` usa o `CacheInvalidator` nas opções
+  direcionadas; `--all` é `FLUSHDB` e exige `--yes`, porque o banco
+  costuma guardar também sessão, contador de rate limit e as flags
+  acima.
+
+- **`tempest email test` e `tempest storage`.** O `email test` manda uma
+  mensagem por `EmailUtils(**settings.email_kwargs())` e, na recusa, sai
+  1 com a resposta do servidor mais a linha que lembra o par que mais
+  custa tempo: 587 quer STARTTLS (`SMTP_USE_TLS`), 465 quer TLS
+  implícito (`SMTP_USE_SSL`). O `storage check/ls/put/get/presign/rm`
+  dirige o `AsyncMinIOClient(**settings.minio_kwargs())`, endpoint
+  público incluído — o `presign` diz no `stderr` para qual host assinou,
+  porque URL assinada contra `minio:9000` é válida e inútil no browser.
+
+- **`tempest queue` e `tempest tasks`.** `queue publish` conecta,
+  publica e **fecha**, nessa ordem, num processo só; `queue handlers`
+  lista os canais consumidos, importando os módulos de handler antes,
+  porque subscriber só existe no broker depois do import. `tasks list`
+  imprime o nome que o TaskIQ registra (`<módulo>:<função>`), que não é
+  o nome no arquivo e é o que o `run` recebe; `tasks run` **enfileira**,
+  e diz isso — quem executa é o worker.
+
+- **`tempest integrations list|verify`.** `list` mostra os clientes que
+  o SDK ships e se este projeto tem a credencial; `verify` faz a leitura
+  autenticada mais barata de cada provedor (OpenPix `GET /company`,
+  Mercado Pago `GET /users/me`), que não move dinheiro nem cria
+  registro. Como isso é tabela mantida à mão sobre cliente gerado, um
+  guard assere que cada método nomeado ainda existe e não exige
+  argumento — ele já pagou por si: o campo é `MERCADOPAGO_ACCESS_TOKEN`,
+  não `MERCADO_PAGO_ACCESS_TOKEN`.
+
+- **`tempest agents tools|run`.** `tools` lista as ferramentas sem
+  chamar modelo nenhum (zero token, funciona sem credencial de backend).
+  `run` segue `AgentRun.succeeded` no código de saída, não "não levantou
+  exceção": run cortado pelo orçamento ainda devolve texto, e tratar
+  esse texto como resposta é o erro que o comando se recusa a cometer
+  pelo chamador.
+
+### Changed
+
+- `tempest secrets rotate` passou a usar o mesmo helper de backup dos
+  comandos novos; comportamento inalterado (backup antes de reescrever,
+  `0600` no arquivo e no `.bak`).
+- `tempest_fastapi_sdk/cli/project.py` centraliza a resolução de
+  projeto usada pelos comandos novos: app FastAPI (por spec ou pelos
+  lugares scaffoldados, reportando **cada** tentativa com a causa),
+  instância de settings por tipo sob `src`/`app`, e URL de Redis
+  (`--redis-url` > `REDIS_URL` > settings).
+
 ## [0.294.0] — 2026-09-19
 
 Um assistente local que roda dentro do WSL precisa agir na máquina que o

{tempest_fastapi_sdk-0.294.0 → tempest_fastapi_sdk-0.296.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.294.0
+Version: 0.296.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -4082,6 +4082,28 @@ tempest check                                   # lint + fmt-check + type + test
 
 Every command returns the underlying tool's exit code, so `tempest check` is safe to wire into CI (`tempest check || exit 1`) or pre-commit hooks. When neither the executable nor `uv` is on `PATH`, the wrapper prints `error: '<tool>' is not on PATH and 'uv' is unavailable` and exits with `127` instead of failing silently.
 
+#### Diagnostics — `tempest doctor`
+
+```bash
+tempest doctor                                        # one line per dependency, real connections
+tempest doctor --json                                 # for deployment health checks
+tempest doctor --timeout 2                            # tighten each network probe
+```
+
+`check-config` reads the settings; `doctor` connects. It probes the database, Redis, RabbitMQ, SMTP and MinIO, folds in the static check registry, and exits `1` when anything failed. A capability the project never configured reads `skip`, never `ok` — and a mixin default (`SMTP_HOST=localhost`, `MINIO_ENDPOINT=localhost:9000`) counts as unconfigured, compared against `model_fields[field].default` the way `check_secrets` does it.
+
+#### Run and inspect — `tempest serve` / `tempest shell`
+
+```bash
+tempest serve                                         # host/port/reload from the project's settings
+tempest serve --reload --port 9000                    # override for this run
+tempest serve --workers 4                             # several processes (refused with --reload)
+tempest shell                                         # async REPL: settings, models, open session
+tempest shell --no-db                                 # skip the database connection
+```
+
+`tempest serve` hands uvicorn the import *string* (`src.server:app`), which is what keeps `--reload` working, and resolves host/port/reload the way `run_server` does: flag > project settings > SDK default. `tempest shell` opens a console with `settings`, every mapped model the project defines, `select`, `text` and an already-open `session`; it compiles with `ast.PyCF_ALLOW_TOP_LEVEL_AWAIT` and runs coroutines on the loop that session belongs to, so `await session.execute(...)` works at the prompt instead of raising `MissingGreenlet`.
+
 #### Database — `tempest db`
 
 Alembic wrapper backed by `AlembicHelper`. Reads `DATABASE_URL` from `--database-url` > env var > `src.core.settings.settings.DATABASE_URL` > `alembic.ini`.
@@ -4094,6 +4116,7 @@ tempest db upgrade                               # alembic upgrade head
 tempest db upgrade <rev>                         # upgrade to a specific revision
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
+tempest db check                                 # exit 1 when models drifted from the tree
 tempest db history -v                            # revisions newest → oldest, verbose
 tempest db stamp head                            # mark the DB without running migrations
 tempest db squash -m "init" --yes                # collapse history into 1 migration
@@ -4111,15 +4134,71 @@ tempest db seed --seed src.db.fixtures:demo      # custom seed callable
 
 #### Secrets — `tempest secrets`
 
-Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+Four commands, ordered by how much they touch your `.env`: `generate` never writes, `init` fills only what is unset, `rotate` always replaces, and `vapid` mints the Web Push key pair.
 
 ```bash
+tempest secrets generate                              # one value on stdout, nothing written
+tempest secrets generate --count 3                    # three of them
+tempest secrets generate --keys JWT_SECRET --json     # JSON, for a secret manager
+tempest secrets init                                  # fill the keys `tempest new` left unset
+tempest secrets init --force                          # replace real values too (backs up first)
 tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
 tempest secrets rotate --print                        # just print, write nothing
 tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
 tempest secrets rotate --length 64 --no-backup
+tempest secrets vapid --subject mailto:ops@example.com  # Web Push key pair
 ```
 
+`tempest secrets init` treats a key as unset when it is missing, empty, or still carries the `change-me` placeholder `tempest new` writes — the values `tempest check-config` reports as `security.W001` / `security.W004` — and keeps every configured key, so it is safe to re-run. `tempest secrets vapid` writes `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` in the shape `WebPushSettings` and `pywebpush` read (32-byte scalar, 65-byte uncompressed point, base64url), and refuses to overwrite an existing pair without `--force`, because replacing it invalidates every active browser subscription.
+
+#### Integrations and agents — `tempest integrations` / `tempest agents`
+
+```bash
+tempest integrations list                             # bundled clients + credential state
+tempest integrations verify openpix                   # one real authenticated read
+tempest agents tools --agent src.agents:agent         # tools, with no model call
+tempest agents run "summarise the report" --agent src.agents:agent --trace
+```
+
+`integrations verify` builds the client from `settings.<provider>_kwargs()` and calls the cheapest authenticated read each API offers (OpenPix `GET /company`, Mercado Pago `GET /users/me`) — a guard asserts those methods still exist on the generated clients and take no argument, so an upstream rename fails a test rather than an operator's terminal. `agents tools` spends no token; `agents run` exits `1` when the run was cut short by its budget, because a truncated run still returns text and treating it as an answer is the mistake worth refusing.
+
+#### Queue and tasks — `tempest queue` / `tempest tasks`
+
+```bash
+tempest queue publish orders.paid '{"order_id": 7}' --json
+tempest queue handlers                                # channels this service consumes
+tempest tasks list                                    # registered task names
+tempest tasks run src.tasks:send_welcome --arg ana@example.com --kwarg retries=2
+```
+
+`queue publish` connects, publishes and closes in one process, so the message is flushed before the command returns. `tasks list` imports the job modules first — a task exists on the broker only once its module has been imported — and prints the name TaskIQ registers (`<module>:<function>`), which is the name `run` takes. `run` enqueues; the worker executes, so success means the message was accepted, not that the job passed. Both default to the scaffolded `<root>.queue:broker` and `<root>.tasks:tq`.
+
+#### Email and object store — `tempest email` / `tempest storage`
+
+```bash
+tempest email test --to you@example.com               # send through the project's SMTP settings
+tempest storage check                                 # endpoint reachable, bucket present
+tempest storage ls reports/                           # keys under a prefix
+tempest storage put ./note.pdf --key notes/2026-09.pdf
+tempest storage presign notes/2026-09.pdf --expires 900
+```
+
+`email test` builds `EmailUtils(**settings.email_kwargs())`, so a message that arrives came through the same path the app uses; a refusal exits `1` with the server's reply and a reminder that port 587 wants `SMTP_USE_TLS` (STARTTLS) while 465 wants `SMTP_USE_SSL`. `storage` uses `AsyncMinIOClient(**settings.minio_kwargs())`, including the public endpoint — `presign` reports on stderr which host it signed for, because a URL signed against `minio:9000` is valid and unusable from a browser.
+
+#### Feature flags and cache — `tempest flags` / `tempest cache`
+
+```bash
+tempest flags list                                    # everything the Redis backend holds
+tempest flags enable new-checkout                     # on, for every process reading it
+tempest flags get new-checkout                        # exit 1 when unset, 0 when stored
+tempest cache ping                                    # PONG, or exit 1
+tempest cache stats                                   # version, keys, memory, hit ratio
+tempest cache flush --namespace orders                # invalidate what @cached registered
+tempest cache flush --all --yes                       # FLUSHDB (deletes non-cache keys too)
+```
+
+Both resolve the URL from `--redis-url` > `REDIS_URL` > the project's settings, and both speak through the SDK's own classes — `RedisFeatureFlagBackend` and `CacheInvalidator` — so the CLI writes what the service reads. `flags get` separates `unset` (exit 1, the service falls back to the caller's default) from a stored `off` (exit 0). `cache flush --all` is `FLUSHDB` and needs `--yes`, because sessions, rate-limit counters and flags usually share that database.
+
 #### Users — `tempest user`
 
 Seeds or lists users via the project's concrete `UserModel` (default `src.db.models:UserModel`). Bootstraps the first admin row so `/admin` login works without manual SQL.
@@ -4135,14 +4214,34 @@ tempest user set-password --email ana@example.com     # prompt, hash, revoke ses
 tempest user set-password --email ana@example.com --keep-sessions
 tempest user list                                     # everyone
 tempest user list --admin                             # admins only
+tempest user show --email ana@example.com             # the whole row (hash redacted)
+tempest user deactivate --email ana@example.com       # is_active=False + revoke sessions
+tempest user activate --email ana@example.com         # back on
+tempest user sessions --email ana@example.com         # list refresh tokens
+tempest user sessions --email ana@example.com --revoke
+tempest user delete --email ana@example.com --yes     # irreversible, removes the tokens too
 ```
 
+`show` redacts `hashed_password` — no question it answers needs the hash, and printing one puts a credential in terminal scrollback and CI logs. `deactivate` revokes the user's refresh tokens in the same transaction as the flag, because `is_active=False` on its own leaves an issued token exchangeable. `sessions` lists one line per token and exits `0` on a user with none; `--revoke` reports how many *that run* killed. `delete` deletes the refresh-token rows first (the scaffolded FK has no `ON DELETE CASCADE`) and requires `--yes` outside a TTY.
+
 When `tempest user create` runs in an interactive terminal **without** `--admin`/`--no-admin`, it asks `Should this user be an administrator? [y/N]`. Non-interactive runs (CI, pipes) skip the prompt and create a regular user. `promote` / `revoke` look the user up by email (case-insensitive) and exit `1` with `no user found` when nothing matches.
 
 `tempest user set-password` replaces an existing user's password, hashing with the model's own `set_password`. Because changing the hash does not end a session on its own, it also revokes the user's DB-backed refresh tokens **in the same transaction** — resolving `src.db.models:UserRefreshTokenModel` by default, `--refresh-token-model` for a table elsewhere, `--keep-sessions` to opt out. Every path reports which of the two happened. From code, the same revocation is `await service.revoke_user_sessions(session, user_id=user.id)`.
 
 Both `create` and `set-password` validate the plaintext with `check_password_policy` against the project's `AUTH_PASSWORD_*` settings (or the `PasswordPolicy` defaults: 12 characters minimum, 72 **bytes** maximum — the unit bcrypt counts), so the CLI accepts exactly the passwords `signup` and the admin panel accept.
 
+#### Routes and contract — `tempest routes` / `tempest openapi-export`
+
+```bash
+tempest routes                                        # every route, mounted routers included
+tempest routes --match /api/orders --method post      # filtered
+tempest routes --json                                 # machine-readable
+tempest openapi-export --out contracts/openapi.json   # write this service's own spec
+tempest openapi-export --out contracts/openapi.json --check   # exit 1 when it drifted
+```
+
+`tempest routes` reads the effective paths from FastAPI's own route expansion, so a router mounted with `include_router` is listed (a comprehension over `app.routes` lists none of its paths since FastAPI 0.141.1), and routes kept out of the schema — HTML pages, internal endpoints — are listed with `SCHEMA=no` next to the dependencies guarding them. `tempest openapi-export` writes the document `openapi-client` (or any other generator) consumes without booting the service; `--check` compares it against the committed file and names the operations that moved, which is the CI guard against an undeclared contract change. Both take `--app module:attr` when the app does not sit at one of the scaffolded locations.
+
 #### Generate artifacts in an existing project — `tempest generate`
 
 ```bash

{tempest_fastapi_sdk-0.294.0 → tempest_fastapi_sdk-0.296.0}/README.md

@@ -3879,6 +3879,28 @@ tempest check                                   # lint + fmt-check + type + test
 
 Every command returns the underlying tool's exit code, so `tempest check` is safe to wire into CI (`tempest check || exit 1`) or pre-commit hooks. When neither the executable nor `uv` is on `PATH`, the wrapper prints `error: '<tool>' is not on PATH and 'uv' is unavailable` and exits with `127` instead of failing silently.
 
+#### Diagnostics — `tempest doctor`
+
+```bash
+tempest doctor                                        # one line per dependency, real connections
+tempest doctor --json                                 # for deployment health checks
+tempest doctor --timeout 2                            # tighten each network probe
+```
+
+`check-config` reads the settings; `doctor` connects. It probes the database, Redis, RabbitMQ, SMTP and MinIO, folds in the static check registry, and exits `1` when anything failed. A capability the project never configured reads `skip`, never `ok` — and a mixin default (`SMTP_HOST=localhost`, `MINIO_ENDPOINT=localhost:9000`) counts as unconfigured, compared against `model_fields[field].default` the way `check_secrets` does it.
+
+#### Run and inspect — `tempest serve` / `tempest shell`
+
+```bash
+tempest serve                                         # host/port/reload from the project's settings
+tempest serve --reload --port 9000                    # override for this run
+tempest serve --workers 4                             # several processes (refused with --reload)
+tempest shell                                         # async REPL: settings, models, open session
+tempest shell --no-db                                 # skip the database connection
+```
+
+`tempest serve` hands uvicorn the import *string* (`src.server:app`), which is what keeps `--reload` working, and resolves host/port/reload the way `run_server` does: flag > project settings > SDK default. `tempest shell` opens a console with `settings`, every mapped model the project defines, `select`, `text` and an already-open `session`; it compiles with `ast.PyCF_ALLOW_TOP_LEVEL_AWAIT` and runs coroutines on the loop that session belongs to, so `await session.execute(...)` works at the prompt instead of raising `MissingGreenlet`.
+
 #### Database — `tempest db`
 
 Alembic wrapper backed by `AlembicHelper`. Reads `DATABASE_URL` from `--database-url` > env var > `src.core.settings.settings.DATABASE_URL` > `alembic.ini`.
@@ -3891,6 +3913,7 @@ tempest db upgrade                               # alembic upgrade head
 tempest db upgrade <rev>                         # upgrade to a specific revision
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
+tempest db check                                 # exit 1 when models drifted from the tree
 tempest db history -v                            # revisions newest → oldest, verbose
 tempest db stamp head                            # mark the DB without running migrations
 tempest db squash -m "init" --yes                # collapse history into 1 migration
@@ -3908,15 +3931,71 @@ tempest db seed --seed src.db.fixtures:demo      # custom seed callable
 
 #### Secrets — `tempest secrets`
 
-Generates and rotates application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines in place after a `.env.bak` backup; `--print` writes nothing and emits the values to stdout.
+Four commands, ordered by how much they touch your `.env`: `generate` never writes, `init` fills only what is unset, `rotate` always replaces, and `vapid` mints the Web Push key pair.
 
 ```bash
+tempest secrets generate                              # one value on stdout, nothing written
+tempest secrets generate --count 3                    # three of them
+tempest secrets generate --keys JWT_SECRET --json     # JSON, for a secret manager
+tempest secrets init                                  # fill the keys `tempest new` left unset
+tempest secrets init --force                          # replace real values too (backs up first)
 tempest secrets rotate                                # rotate JWT_SECRET + TOKEN_SECRET in .env
 tempest secrets rotate --print                        # just print, write nothing
 tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
 tempest secrets rotate --length 64 --no-backup
+tempest secrets vapid --subject mailto:ops@example.com  # Web Push key pair
 ```
 
+`tempest secrets init` treats a key as unset when it is missing, empty, or still carries the `change-me` placeholder `tempest new` writes — the values `tempest check-config` reports as `security.W001` / `security.W004` — and keeps every configured key, so it is safe to re-run. `tempest secrets vapid` writes `VAPID_PUBLIC_KEY` / `VAPID_PRIVATE_KEY` in the shape `WebPushSettings` and `pywebpush` read (32-byte scalar, 65-byte uncompressed point, base64url), and refuses to overwrite an existing pair without `--force`, because replacing it invalidates every active browser subscription.
+
+#### Integrations and agents — `tempest integrations` / `tempest agents`
+
+```bash
+tempest integrations list                             # bundled clients + credential state
+tempest integrations verify openpix                   # one real authenticated read
+tempest agents tools --agent src.agents:agent         # tools, with no model call
+tempest agents run "summarise the report" --agent src.agents:agent --trace
+```
+
+`integrations verify` builds the client from `settings.<provider>_kwargs()` and calls the cheapest authenticated read each API offers (OpenPix `GET /company`, Mercado Pago `GET /users/me`) — a guard asserts those methods still exist on the generated clients and take no argument, so an upstream rename fails a test rather than an operator's terminal. `agents tools` spends no token; `agents run` exits `1` when the run was cut short by its budget, because a truncated run still returns text and treating it as an answer is the mistake worth refusing.
+
+#### Queue and tasks — `tempest queue` / `tempest tasks`
+
+```bash
+tempest queue publish orders.paid '{"order_id": 7}' --json
+tempest queue handlers                                # channels this service consumes
+tempest tasks list                                    # registered task names
+tempest tasks run src.tasks:send_welcome --arg ana@example.com --kwarg retries=2
+```
+
+`queue publish` connects, publishes and closes in one process, so the message is flushed before the command returns. `tasks list` imports the job modules first — a task exists on the broker only once its module has been imported — and prints the name TaskIQ registers (`<module>:<function>`), which is the name `run` takes. `run` enqueues; the worker executes, so success means the message was accepted, not that the job passed. Both default to the scaffolded `<root>.queue:broker` and `<root>.tasks:tq`.
+
+#### Email and object store — `tempest email` / `tempest storage`
+
+```bash
+tempest email test --to you@example.com               # send through the project's SMTP settings
+tempest storage check                                 # endpoint reachable, bucket present
+tempest storage ls reports/                           # keys under a prefix
+tempest storage put ./note.pdf --key notes/2026-09.pdf
+tempest storage presign notes/2026-09.pdf --expires 900
+```
+
+`email test` builds `EmailUtils(**settings.email_kwargs())`, so a message that arrives came through the same path the app uses; a refusal exits `1` with the server's reply and a reminder that port 587 wants `SMTP_USE_TLS` (STARTTLS) while 465 wants `SMTP_USE_SSL`. `storage` uses `AsyncMinIOClient(**settings.minio_kwargs())`, including the public endpoint — `presign` reports on stderr which host it signed for, because a URL signed against `minio:9000` is valid and unusable from a browser.
+
+#### Feature flags and cache — `tempest flags` / `tempest cache`
+
+```bash
+tempest flags list                                    # everything the Redis backend holds
+tempest flags enable new-checkout                     # on, for every process reading it
+tempest flags get new-checkout                        # exit 1 when unset, 0 when stored
+tempest cache ping                                    # PONG, or exit 1
+tempest cache stats                                   # version, keys, memory, hit ratio
+tempest cache flush --namespace orders                # invalidate what @cached registered
+tempest cache flush --all --yes                       # FLUSHDB (deletes non-cache keys too)
+```
+
+Both resolve the URL from `--redis-url` > `REDIS_URL` > the project's settings, and both speak through the SDK's own classes — `RedisFeatureFlagBackend` and `CacheInvalidator` — so the CLI writes what the service reads. `flags get` separates `unset` (exit 1, the service falls back to the caller's default) from a stored `off` (exit 0). `cache flush --all` is `FLUSHDB` and needs `--yes`, because sessions, rate-limit counters and flags usually share that database.
+
 #### Users — `tempest user`
 
 Seeds or lists users via the project's concrete `UserModel` (default `src.db.models:UserModel`). Bootstraps the first admin row so `/admin` login works without manual SQL.
@@ -3932,14 +4011,34 @@ tempest user set-password --email ana@example.com     # prompt, hash, revoke ses
 tempest user set-password --email ana@example.com --keep-sessions
 tempest user list                                     # everyone
 tempest user list --admin                             # admins only
+tempest user show --email ana@example.com             # the whole row (hash redacted)
+tempest user deactivate --email ana@example.com       # is_active=False + revoke sessions
+tempest user activate --email ana@example.com         # back on
+tempest user sessions --email ana@example.com         # list refresh tokens
+tempest user sessions --email ana@example.com --revoke
+tempest user delete --email ana@example.com --yes     # irreversible, removes the tokens too
 ```
 
+`show` redacts `hashed_password` — no question it answers needs the hash, and printing one puts a credential in terminal scrollback and CI logs. `deactivate` revokes the user's refresh tokens in the same transaction as the flag, because `is_active=False` on its own leaves an issued token exchangeable. `sessions` lists one line per token and exits `0` on a user with none; `--revoke` reports how many *that run* killed. `delete` deletes the refresh-token rows first (the scaffolded FK has no `ON DELETE CASCADE`) and requires `--yes` outside a TTY.
+
 When `tempest user create` runs in an interactive terminal **without** `--admin`/`--no-admin`, it asks `Should this user be an administrator? [y/N]`. Non-interactive runs (CI, pipes) skip the prompt and create a regular user. `promote` / `revoke` look the user up by email (case-insensitive) and exit `1` with `no user found` when nothing matches.
 
 `tempest user set-password` replaces an existing user's password, hashing with the model's own `set_password`. Because changing the hash does not end a session on its own, it also revokes the user's DB-backed refresh tokens **in the same transaction** — resolving `src.db.models:UserRefreshTokenModel` by default, `--refresh-token-model` for a table elsewhere, `--keep-sessions` to opt out. Every path reports which of the two happened. From code, the same revocation is `await service.revoke_user_sessions(session, user_id=user.id)`.
 
 Both `create` and `set-password` validate the plaintext with `check_password_policy` against the project's `AUTH_PASSWORD_*` settings (or the `PasswordPolicy` defaults: 12 characters minimum, 72 **bytes** maximum — the unit bcrypt counts), so the CLI accepts exactly the passwords `signup` and the admin panel accept.
 
+#### Routes and contract — `tempest routes` / `tempest openapi-export`
+
+```bash
+tempest routes                                        # every route, mounted routers included
+tempest routes --match /api/orders --method post      # filtered
+tempest routes --json                                 # machine-readable
+tempest openapi-export --out contracts/openapi.json   # write this service's own spec
+tempest openapi-export --out contracts/openapi.json --check   # exit 1 when it drifted
+```
+
+`tempest routes` reads the effective paths from FastAPI's own route expansion, so a router mounted with `include_router` is listed (a comprehension over `app.routes` lists none of its paths since FastAPI 0.141.1), and routes kept out of the schema — HTML pages, internal endpoints — are listed with `SCHEMA=no` next to the dependencies guarding them. `tempest openapi-export` writes the document `openapi-client` (or any other generator) consumes without booting the service; `--check` compares it against the committed file and names the operations that moved, which is the CI guard against an undeclared contract change. Both take `--app module:attr` when the app does not sit at one of the scaffolded locations.
+
 #### Generate artifacts in an existing project — `tempest generate`
 
 ```bash

{tempest_fastapi_sdk-0.294.0 → tempest_fastapi_sdk-0.296.0}/SHIPPED.md

@@ -1700,10 +1700,35 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   default, and both it and `create` validate the plaintext with
   `check_password_policy` against the project's own `AUTH_PASSWORD_*`
   settings),
-  `tempest secrets rotate`,
+  `tempest secrets generate/init/rotate/vapid` (**v0.294.0**: `generate`
+  prints without writing, `init` fills only missing/empty/`change-me`
+  keys and is idempotent, `vapid` mints the Web Push P-256 pair and
+  refuses to replace one without `--force`),
   `tempest model analyze/bench/optimize/quantize/export-ort/hardware/
   pull/cache-list/cache-rm`,
   `tempest pdf list/schema/render`,
+  **Operating an existing service (v0.294.0)** — `tempest routes` (every
+  effective route, mounted routers expanded via
+  `fastapi.routing.iter_route_contexts`, schema-excluded routes listed
+  with their guards), `tempest openapi-export [--check]` (this service's
+  own document; `--check` names the operations added/removed/changed),
+  `tempest db check` (Alembic autogenerate drift, exit 1),
+  `tempest serve` / `tempest shell` (uvicorn with the project's
+  resolution; async REPL with settings, the project's own models and an
+  open session, top-level `await` on that session's loop),
+  `tempest doctor` (real connections to database/Redis/RabbitMQ/SMTP/
+  MinIO plus the check registry; unconfigured reads `skip`, and a mixin
+  default counts as unconfigured),
+  `tempest user show/activate/deactivate/sessions/delete` (hash
+  redacted; deactivate and delete take the refresh tokens with them),
+  `tempest flags list/get/enable/disable` (`unset` is exit 1, distinct
+  from a stored `off`), `tempest cache ping/stats/flush`
+  (`--all` is FLUSHDB and demands `--yes`), `tempest email test`,
+  `tempest storage check/ls/put/get/presign/rm` (presign reports which
+  host it signed for), `tempest queue publish/handlers`,
+  `tempest tasks list/run`, `tempest integrations list/verify`
+  (cheapest authenticated read per provider, with a guard on the table),
+  `tempest agents tools/run` (exit follows `AgentRun.succeeded`),
   plus quality gates (`lint`, `fix`, `format`, `fmt-check`, `type`,
   `test`, `check`), `openapi-errors`, `openapi-client`, `permissions`.
   **`tempest pr-prompt` (v0.210.0)** — builds the prompt that makes an AI
@@ -2162,3 +2187,19 @@ coluna e tabela que o `[pdf-read]` entrega intercaladas, e o caminho com
 senha distingue documento cifrado de arquivo corrompido — o que só ficou
 verdade depois de descobrir que o `pdfplumber` embrulha `PDFPasswordIncorrect`
 num `PdfminerException`, fazendo o `except` específico nunca disparar.
+
+## O 500 volta a passar pelo CORS, v0.296.0 (2026-09-22)
+
+`register_exception_handlers` instala o `ErrorEnvelopeMiddleware` como o
+middleware de usuário mais interno (#287). O handler de `Exception` do
+Starlette mora no `ServerErrorMiddleware`, fora de toda a pilha, e o
+envelope de 500 saía sem `Access-Control-Allow-Origin`: o navegador
+descartava, e o front via `Failed to fetch` num login que já estava em
+produção — escondendo a causa real por horas, porque todo `curl` mostrava
+as camadas funcionando.
+
+A lição é a mesma do OAuth: o issue propunha documentar a ordem certa de
+registro e corrigir o template. Ordem que o consumidor precisa acertar é
+ordem que um dia ele inverte sem teste falhando. `append` em
+`user_middleware` deixa a camada no fundo **qualquer que seja a ordem**,
+então a regra deixou de existir em vez de ganhar um aviso.

{tempest_fastapi_sdk-0.294.0 → tempest_fastapi_sdk-0.296.0}/docs/architecture.en.md

@@ -123,6 +123,15 @@ Details in [UI layer](recipes/ui.md),
 [Forms from Pydantic schemas](recipes/ui-forms.md) and
 [Typed CSS](recipes/ui-css.md).
 
+!!! tip "And when the frontend is an app, not a page"
+    The `ui` layer renders HTML **on the server**. When the screen needs
+    client-side state — a SPA — the path is still Python:
+    **[tempestweb](recipes/tempestweb-frontend.md)** writes the interface
+    and compiles it to WASM (or runs it in server-mode), and the SDK serves
+    the build through `make_web_app_router` / `build_web_app`, on the same
+    origin as the API. The two live together:
+    [Fullstack web](fullstack-web.md) compares when to use which.
+
 ## Request lifecycle
 
 ```mermaid
@@ -171,6 +180,50 @@ The SDK ships [`AppException`][tempest_fastapi_sdk.AppException] + [`register_ex
 
 The frontend branches on `code` (stable, machine-readable), never on the (potentially translated) `detail`.
 
+### The 500 goes through CORS too
+
+An exception no handler catches becomes a `500` with `code: "INTERNAL_SERVER_ERROR"`. Starlette runs the `Exception` handler inside `ServerErrorMiddleware`, the **outermost** layer of the stack, so on its own that envelope would leave without passing through `CORSMiddleware`: with no `Access-Control-Allow-Origin` the browser discards the response and `fetch` rejects with `TypeError: Failed to fetch` — no status, no `code`, no `X-Request-ID`.
+
+That is why `register_exception_handlers` also installs [`ErrorEnvelopeMiddleware`][tempest_fastapi_sdk.ErrorEnvelopeMiddleware] as the **innermost** middleware. From there the 500 passes through every middleware you added, and the order of the calls stops mattering:
+
+```python
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from tempest_fastapi_sdk import (
+    RequestIDMiddleware,
+    apply_cors,
+    register_exception_handlers,
+)
+
+app: FastAPI = FastAPI()
+app.add_middleware(RequestIDMiddleware)
+apply_cors(app, origins=["https://front.example"])
+register_exception_handlers(app)
+
+
+@app.get("/boom")
+async def boom() -> None:
+    raise RuntimeError("unhandled failure")
+
+
+client: TestClient = TestClient(app, raise_server_exceptions=False)
+response = client.get("/boom", headers={"Origin": "https://front.example"})
+print(response.status_code, response.headers["access-control-allow-origin"])
+print(response.json()["details"]["request_id"] == response.headers["x-request-id"])
+```
+
+```text
+500 https://front.example
+True
+```
+
+!!! note "What stays the same"
+    - The layer **does not decide CORS**. An origin outside the allow-list still gets no header, on the 500 too.
+    - After sending the envelope the exception is **re-raised**, as Starlette already did: the ASGI server still logs it, and a `TestClient` with the default `raise_server_exceptions=True` still raises it in your test.
+    - A failure after the response started (a stream that breaks mid-body) is re-raised with no second response, because the status is already on the wire. It is logged and reaches `on_server_error` once, like a plain 500.
+    - `register_exception_handlers` must run **before** the application starts; after that the stack is built and it raises `RuntimeError`.
+
 ## Where to go next
 
 | You want to… | Read |