tempest-fastapi-sdk 0.46.0__tar.gz → 0.48.0__tar.gz

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.48.0] — 2026-06-11
+
+### Changed
+
+- **Scaffolded services read their API `title` / `version` /
+  `description` from `.env`.** `tempest new` previously hardcoded
+  `FastAPI(title="<project>", version="0.1.0")` and the health-router
+  version in `src/api/app.py`. The scaffolded `Settings` now carries
+  `TITLE`, `DESCRIPTION` and `VERSION` fields (each with `title` /
+  `description` / `examples`), `app.py` reads them
+  (`FastAPI(title=settings.TITLE, version=settings.VERSION, ...)`,
+  `make_health_router(version=settings.VERSION)`,
+  `AdminSite(title=f"{settings.TITLE} admin")`), and `.env.example`
+  ships a documented `TITLE` / `VERSION` / `DESCRIPTION` block — so the
+  OpenAPI docs and admin header are configurable without editing code.
+
+## [0.47.0] — 2026-06-11
+
+### Added
+
+- **`tempest db seed`** — runs a project seed callable
+  (default `src.db.seeds:seed`, dotted `module:callable`, sync or async,
+  taking one `AsyncSession`) inside a managed session: commit on
+  success, rollback on error. The SDK only wires the session lifecycle;
+  the callable owns what gets inserted. Prints the row count when the
+  callable returns an `int`.
+- **`tempest secrets rotate`** — generates fresh URL-safe secrets for
+  the keys a service signs/authenticates with (`JWT_SECRET` /
+  `TOKEN_SECRET` by default; override with `--keys`) and rewrites the
+  matching `.env` lines **in place** (existing keys replaced, missing
+  keys appended) after a `.env.bak` backup. `--print` writes nothing and
+  emits the values to stdout; `--length` sets the entropy; `--no-backup`
+  skips the backup.
+
+### Docs
+
+- CLI recipe (bilingual) gains **`db seed`** and **`secrets rotate`**
+  sections; README CLI section and recipes index updated.
+
 ## [0.46.0] — 2026-06-11
 
 ### Added

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.46.0
+Version: 0.48.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
@@ -3345,7 +3345,7 @@ The skeleton matches the layered architecture documented in this README:
 my_service/
 ├── main.py                  # one-liner → src.server.run()
 ├── pyproject.toml           # pins tempest-fastapi-sdk + ruff/mypy/pytest
-├── .env.example             # HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
+├── .env.example             # TITLE/VERSION/HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
 ├── .gitignore
 ├── README.md
 ├── src/
@@ -3366,7 +3366,7 @@ my_service/
     └── test_smoke.py        # asserts /api/ and /health/liveness boot
 ```
 
-The generated `pyproject.toml` pins the current SDK version (`tempest-fastapi-sdk[auth]>=<version>` by default — change with `--extras`). The scaffolded `.env.example` uses the v0.8.0 settings naming (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), and `src/server.py` delegates to `tempest_fastapi_sdk.run_server` so uvicorn is imported lazily and tests can import the app without it. Validation rules: the project name must match `^[a-z][a-z0-9_]*$` and cannot collide with a Python keyword, so `tempest new Bad-Name` and `tempest new class` exit with code 2 before any file is written.
+The generated `pyproject.toml` pins the current SDK version (`tempest-fastapi-sdk[auth]>=<version>` by default — change with `--extras`). The scaffolded `.env.example` uses the v0.8.0 settings naming (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), and `src/server.py` delegates to `tempest_fastapi_sdk.run_server` so uvicorn is imported lazily and tests can import the app without it. The API `title`, `version` and `description` shown in the OpenAPI docs (and the `/admin` header) come from the `TITLE` / `VERSION` / `DESCRIPTION` settings — set them in `.env`, no code edits. Validation rules: the project name must match `^[a-z][a-z0-9_]*$` and cannot collide with a Python keyword, so `tempest new Bad-Name` and `tempest new class` exit with code 2 before any file is written.
 
 After scaffolding:
 
@@ -3411,6 +3411,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### 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.
+
+```bash
+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
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/README.md

@@ -3243,7 +3243,7 @@ The skeleton matches the layered architecture documented in this README:
 my_service/
 ├── main.py                  # one-liner → src.server.run()
 ├── pyproject.toml           # pins tempest-fastapi-sdk + ruff/mypy/pytest
-├── .env.example             # HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
+├── .env.example             # TITLE/VERSION/HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
 ├── .gitignore
 ├── README.md
 ├── src/
@@ -3264,7 +3264,7 @@ my_service/
     └── test_smoke.py        # asserts /api/ and /health/liveness boot
 ```
 
-The generated `pyproject.toml` pins the current SDK version (`tempest-fastapi-sdk[auth]>=<version>` by default — change with `--extras`). The scaffolded `.env.example` uses the v0.8.0 settings naming (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), and `src/server.py` delegates to `tempest_fastapi_sdk.run_server` so uvicorn is imported lazily and tests can import the app without it. Validation rules: the project name must match `^[a-z][a-z0-9_]*$` and cannot collide with a Python keyword, so `tempest new Bad-Name` and `tempest new class` exit with code 2 before any file is written.
+The generated `pyproject.toml` pins the current SDK version (`tempest-fastapi-sdk[auth]>=<version>` by default — change with `--extras`). The scaffolded `.env.example` uses the v0.8.0 settings naming (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), and `src/server.py` delegates to `tempest_fastapi_sdk.run_server` so uvicorn is imported lazily and tests can import the app without it. The API `title`, `version` and `description` shown in the OpenAPI docs (and the `/admin` header) come from the `TITLE` / `VERSION` / `DESCRIPTION` settings — set them in `.env`, no code edits. Validation rules: the project name must match `^[a-z][a-z0-9_]*$` and cannot collide with a Python keyword, so `tempest new Bad-Name` and `tempest new class` exit with code 2 before any file is written.
 
 After scaffolding:
 
@@ -3309,6 +3309,21 @@ tempest db upgrade <rev>                         # upgrade to a specific revisio
 tempest db downgrade                             # roll back one step
 tempest db current                               # print the applied revision
 tempest db history -v                            # revisions newest → oldest, verbose
+tempest db seed                                  # run src.db.seeds:seed in one session
+tempest db seed --seed src.db.fixtures:demo      # custom seed callable
+```
+
+`tempest db seed` runs a project seed callable (default `src.db.seeds:seed`, sync or async, taking one `AsyncSession`) inside a managed session — commit on success, rollback on error.
+
+#### 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.
+
+```bash
+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
 ```
 
 #### Users — `tempest user`

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/docs/recipes/cli.en.md

@@ -39,7 +39,7 @@ The skeleton matches the layered architecture documented in this README:
 my_service/
 ├── main.py                  # one-liner → src.server.run()
 ├── pyproject.toml           # pins tempest-fastapi-sdk + ruff/mypy/pytest
-├── .env.example             # HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
+├── .env.example             # TITLE/VERSION/HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
 ├── docker-compose.yaml      # services keyed to the chosen extras
 ├── .gitignore
 ├── README.md
@@ -63,6 +63,21 @@ my_service/
 
 The generated `pyproject.toml` pins the current SDK version (`tempest-fastapi-sdk[auth,admin]>=<version>` by default — change with `--extras`). The scaffolded `.env.example` uses the v0.8.0 settings naming (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), and `src/server.py` delegates to `tempest_fastapi_sdk.run_server` so uvicorn is imported lazily and tests can import the app without it. Validation rules: the project name must match `^[a-z][a-z0-9_]*$` and cannot collide with a Python keyword, so `tempest new Bad-Name` and `tempest new class` exit with code 2 before any file is written.
 
+!!! tip "API title / version come from `.env`"
+    Since v0.48.0 the scaffolded `Settings` carries `TITLE`, `VERSION`
+    and `DESCRIPTION`, and `src/api/app.py` consumes them
+    (`FastAPI(title=settings.TITLE, version=settings.VERSION,
+    description=settings.DESCRIPTION)`, `make_health_router(version=
+    settings.VERSION)` and `AdminSite(title=f"{settings.TITLE} admin")`).
+    Tune the title shown in Swagger/ReDoc and the `/admin` header from
+    `.env`, no code edits:
+
+    ```bash
+    TITLE=My API
+    VERSION=1.2.0
+    DESCRIPTION=Payments API for product X.
+    ```
+
 ### Extras-driven `docker-compose.yaml`
 
 Since v0.25.0 the scaffold generates a `docker-compose.yaml` carrying **only** the supporting services the chosen extras actually need — no ZooKeeper, no Kafka, nothing you won't use.
@@ -140,8 +155,29 @@ tempest db downgrade <rev>                       # roll back to a specific revis
 tempest db current                               # print the applied revision
 tempest db history                               # revisions newest → oldest
 tempest db history -v                            # with full message body
+tempest db seed                                  # runs src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # custom callable
+```
+
+#### Seed the database — `tempest db seed`
+
+Runs a project seed callable inside a managed session (commit on success, rollback on error). The callable takes a positional `AsyncSession` and may be sync or async; what it inserts is up to you — the SDK only wires the session lifecycle. Defaults to importing `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Seed initial categories. Return the count (optional)."""
+    session.add_all([CategoryModel(name="Books"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
 ```
 
+When the callable returns an `int`, the CLI prints the count: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Users — `tempest user`
 
 Seed and list users using the project's concrete ``UserModel`` (default ``src.db.models:UserModel``). Bootstraps the first admin without manual SQL.
@@ -180,6 +216,27 @@ tempest user list --admin                        # admins only
 
 ``DATABASE_URL`` resolves the same way as ``tempest db`` (env var > settings > alembic.ini).
 
+### Secrets — `tempest secrets`
+
+Generate and rotate application secrets (`JWT_SECRET` / `TOKEN_SECRET` by default), rewriting the matching `.env` lines **in place** — backing up the old file first — and leaving every other line untouched.
+
+```bash
+# Rotate JWT_SECRET and TOKEN_SECRET in .env (writes .env.bak)
+tempest secrets rotate
+
+# Just print the new values (writes nothing) — pipe into a secret manager
+tempest secrets rotate --print
+
+# Custom keys and file
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# More entropy, no backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotating `JWT_SECRET` invalidates every token signed with the old value: users are logged out and pending reset/activation links stop working. Rotate during a maintenance window and restart the service to load the new values.
+
 ### Regenerating `docker-compose.yaml` in an existing project
 
 When you change installed extras (`uv add "tempest-fastapi-sdk[minio]"`) or the SDK bumps image versions, regenerate with:

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/docs/recipes/cli.md

@@ -39,7 +39,7 @@ O esqueleto casa com a arquitetura em camadas documentada neste README:
 my_service/
 ├── main.py                  # one-liner → src.server.run()
 ├── pyproject.toml           # fixa tempest-fastapi-sdk + ruff/mypy/pytest
-├── .env.example             # HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
+├── .env.example             # TITLE/VERSION/HOST/PORT/DATABASE_URL/JWT_SECRET/CORS_ORIGINS
 ├── docker-compose.yaml      # serviços baseados nos extras escolhidos
 ├── .gitignore
 ├── README.md
@@ -63,6 +63,21 @@ my_service/
 
 O `pyproject.toml` gerado fixa a versão atual do SDK (`tempest-fastapi-sdk[auth,admin]>=<versão>` por padrão — mude com `--extras`). O `.env.example` criado usa a nomenclatura de settings da v0.8.0 (`SERVER_HOST`/`SERVER_PORT`/`SERVER_DEBUG`/`SERVER_RELOAD`/`LOG_LEVEL`/…), e `src/server.py` delega a `tempest_fastapi_sdk.run_server` para que o uvicorn seja importado de forma preguiçosa e os testes possam importar o app sem ele. Regras de validação: o nome do projeto deve casar com `^[a-z][a-z0-9_]*$` e não pode colidir com uma palavra-chave do Python, então `tempest new Bad-Name` e `tempest new class` saem com código 2 antes de qualquer arquivo ser escrito.
 
+!!! tip "Título / versão da API vêm do `.env`"
+    A partir da v0.48.0 o `Settings` scaffoldado carrega `TITLE`,
+    `VERSION` e `DESCRIPTION`, e `src/api/app.py` os consome
+    (`FastAPI(title=settings.TITLE, version=settings.VERSION,
+    description=settings.DESCRIPTION)`, `make_health_router(version=
+    settings.VERSION)` e `AdminSite(title=f"{settings.TITLE} admin")`).
+    Ajuste o título mostrado no Swagger/ReDoc e no header do `/admin`
+    direto no `.env`, sem editar código:
+
+    ```bash
+    TITLE=Minha API
+    VERSION=1.2.0
+    DESCRIPTION=API de pagamentos do produto X.
+    ```
+
 ### `docker-compose.yaml` baseado nos extras
 
 Desde a v0.25.0 o scaffold gera um `docker-compose.yaml` com **apenas** os serviços que os extras escolhidos precisam — sem ZooKeeper, Kafka ou qualquer outra coisa que você não vai usar.
@@ -188,8 +203,29 @@ tempest db downgrade <rev>                       # rollback até rev específico
 tempest db current                               # imprime revision aplicado
 tempest db history                               # histórico de revisions
 tempest db history -v                            # com message body completo
+tempest db seed                                  # roda src.db.seeds:seed
+tempest db seed --seed src.db.fixtures:demo      # callable customizado
+```
+
+#### Popular o banco — `tempest db seed`
+
+Roda um callable de seed do projeto dentro de uma sessão gerenciada (commit no sucesso, rollback no erro). O callable recebe uma `AsyncSession` posicional e pode ser sync ou async; o que ele insere é decisão sua — o SDK só cuida do ciclo de vida da sessão. Por padrão importa `src.db.seeds:seed`.
+
+```python
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.db.models import CategoryModel
+
+
+async def seed(session: AsyncSession) -> int:
+    """Popula categorias iniciais. Retorna a contagem (opcional)."""
+    session.add_all([CategoryModel(name="Livros"), CategoryModel(name="Games")])
+    await session.flush()
+    return 2
 ```
 
+Quando o callable devolve um `int`, a CLI mostra a contagem: `Seeded via src.db.seeds:seed (2 rows).`
+
 ### Usuários — `tempest user`
 
 Insere/lista usuários direto no banco usando o `UserModel` concreto do projeto (default `src.db.models:UserModel`). Útil pra bootstrapear o primeiro admin sem rodar SQL manual.
@@ -228,6 +264,27 @@ tempest user list --admin                        # só admins
 
 Resolução do `DATABASE_URL` igual ao `tempest db` (env var > settings > alembic.ini).
 
+### Segredos — `tempest secrets`
+
+Gera e rotaciona os segredos da aplicação (`JWT_SECRET` / `TOKEN_SECRET` por padrão), reescrevendo as linhas correspondentes no `.env` **no lugar** — fazendo backup do arquivo antigo antes — e deixando as outras linhas intactas.
+
+```bash
+# Rotaciona JWT_SECRET e TOKEN_SECRET no .env (gera .env.bak)
+tempest secrets rotate
+
+# Só imprime os novos valores (não escreve nada) — pra pipar num secret manager
+tempest secrets rotate --print
+
+# Chaves e arquivo customizados
+tempest secrets rotate --keys JWT_SECRET,SESSION_SECRET --env .env.prod
+
+# Mais entropia, sem backup
+tempest secrets rotate --length 64 --no-backup
+```
+
+!!! warning
+    Rotacionar `JWT_SECRET` invalida todo token assinado com o valor antigo: usuários são deslogados e links de reset/ativação pendentes param de funcionar. Rotacione numa janela de manutenção e reinicie o serviço pra carregar os novos valores.
+
 #### Gates de qualidade
 
 Os comandos de lint chamam a ferramenta do projeto. Eles procuram o executável no `PATH` primeiro e, caso contrário, caem para `uv run <tool>` para que um virtualenv local do projeto funcione sem ativação manual.

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/docs/recipes/index.en.md

@@ -27,7 +27,7 @@ Bite-sized "I want to wire X" walkthroughs. Each page starts with **what problem
 | **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |
 | **[Testing »](testing.md)** | `test_session`, `test_database`, in-memory SQLite, pytest fixtures |
 | **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
 | **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |
 

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/docs/recipes/index.md

@@ -27,7 +27,7 @@ Passo a passo curtos no estilo "quero conectar X". Cada página começa com **qu
 | **[Utilitários »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, tokens opacos (`generate_opaque_token`) |
 | **[Testes »](testing.md)** | `test_session`, `test_database`, SQLite em memória, fixtures pytest |
 | **[Deploy seguro »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (barra DROPs), `GracefulShutdownMiddleware` |
-| **[CLI »](cli.md)** | `tempest new` / `lint` / `fix` / `format` / `type` / `test` / `check` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Segurança »](security.md)** | `AttemptThrottle`, helpers de token opaco, `HardenedStaticFiles`, headers de segurança |
 | **[Helpers brasileiros »](br-helpers.md)** | validação + normalização de CPF / CNPJ / CEP / telefone |
 

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.46.0"
+version = "0.48.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.11"

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/tempest_fastapi_sdk/__init__.py

@@ -250,7 +250,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router,
 )
 
-__version__: str = "0.46.0"
+__version__: str = "0.48.0"
 
 __all__: list[str] = [
     "BASE_COLUMN_ORDER",

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/tempest_fastapi_sdk/cli/_templates/env.example.tmpl

@@ -1,3 +1,8 @@
+# API metadata (shown in the OpenAPI docs + admin panel header)
+TITLE=__PROJECT_NAME__
+VERSION=0.1.0
+# DESCRIPTION=Backend API for __PROJECT_NAME__.
+
 # Server
 SERVER_HOST=__HOST__
 SERVER_PORT=__PORT__

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/tempest_fastapi_sdk/cli/_templates/src/api/app.py.tmpl

@@ -48,8 +48,9 @@ def create_app() -> FastAPI:
         FastAPI: A fully wired application ready for uvicorn.
     """
     app = FastAPI(
-        title="__PROJECT_NAME__",
-        version="0.1.0",
+        title=settings.TITLE,
+        description=settings.DESCRIPTION,
+        version=settings.VERSION,
         lifespan=lifespan,
     )
 
@@ -58,7 +59,7 @@ def create_app() -> FastAPI:
     register_exception_handlers(app)
 
     app.include_router(
-        make_health_router(db=db, version="0.1.0"),
+        make_health_router(db=db, version=settings.VERSION),
     )
     app.include_router(
         make_logs_router(
@@ -72,7 +73,7 @@ def create_app() -> FastAPI:
     # Alembic migration:
     #   uv run alembic upgrade head
     #   uv run python -c "..."  # set hashed_password + is_admin=True
-    admin_site = AdminSite(title="__PROJECT_NAME__ admin")
+    admin_site = AdminSite(title=f"{settings.TITLE} admin")
     admin_site.register(AdminModel(model=UserModel))
     app.include_router(
         make_admin_router(

tempest_fastapi_sdk-0.48.0/tempest_fastapi_sdk/cli/_templates/src/core/settings.py.tmpl

@@ -0,0 +1,61 @@
+"""Application settings — composed from SDK mixins + service overrides."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from tempest_fastapi_sdk import (
+    BaseAppSettings,
+    CORSSettings,
+    DatabaseSettings,
+    JWTSettings,
+    LogSettings,
+    ServerSettings,
+    TokenSettings,
+)
+
+
+class Settings(
+    ServerSettings,
+    LogSettings,
+    DatabaseSettings,
+    JWTSettings,
+    TokenSettings,
+    CORSSettings,
+    BaseAppSettings,
+):
+    """Service-wide settings backed by the ``.env`` file.
+
+    Attributes:
+        TITLE (str): API title shown in the OpenAPI docs and the admin
+            panel header. Override via the ``TITLE`` env var.
+        DESCRIPTION (str): Optional API description shown in the OpenAPI
+            docs. Override via the ``DESCRIPTION`` env var.
+        VERSION (str): Version surfaced in the OpenAPI docs and on the
+            health router. Override via the ``VERSION`` env var.
+    """
+
+    TITLE: str = Field(
+        default="__PROJECT_NAME__",
+        title="API title",
+        description="Shown in the OpenAPI docs and the admin panel header.",
+        examples=["__PROJECT_NAME__"],
+    )
+    DESCRIPTION: str = Field(
+        default="",
+        title="API description",
+        description="Optional summary shown in the OpenAPI docs.",
+        examples=["Backend API for __PROJECT_NAME__."],
+    )
+    VERSION: str = Field(
+        default="0.1.0",
+        title="API version",
+        description="Surfaced in the OpenAPI docs and the health router.",
+        examples=["0.1.0"],
+    )
+
+
+settings = Settings()
+
+
+__all__: list[str] = ["Settings", "settings"]

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/tempest_fastapi_sdk/cli/db.py

@@ -20,12 +20,21 @@ stripped automatically before Alembic runs.
 
 from __future__ import annotations
 
+import asyncio
+import importlib
+import inspect
 import os
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
 
 import typer
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from sqlalchemy.ext.asyncio import AsyncSession
+
 
 def _resolve_database_url(explicit: str | None) -> str | None:
     """Pick the DB URL using the documented priority order.
@@ -95,6 +104,70 @@ def _helper(
     return AlembicHelper(str(ini), db_url=database_url)
 
 
+def _load_seed_callable(spec: str) -> Callable[[AsyncSession], Any]:
+    """Import a ``module.path:callable`` seed entry point.
+
+    Args:
+        spec (str): Dotted spec ``"module.path:callable"``.
+
+    Returns:
+        Callable[[AsyncSession], Any]: The seed callable (sync or async).
+
+    Raises:
+        typer.Exit: When the spec is malformed, the import fails, or the
+            attribute is not callable.
+    """
+    module_path, _, attr = spec.partition(":")
+    if not module_path or not attr:
+        typer.echo(
+            f"error: --seed must be 'module.path:callable', got {spec!r}",
+            err=True,
+        )
+        raise typer.Exit(2)
+    cwd = str(Path.cwd())
+    if cwd not in sys.path:
+        sys.path.insert(0, cwd)
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        typer.echo(f"error: cannot import {module_path!r}: {exc}", err=True)
+        raise typer.Exit(2) from exc
+    seed: object = getattr(module, attr, None)
+    if not callable(seed):
+        typer.echo(
+            f"error: {spec} is not callable (got {type(seed).__name__}).",
+            err=True,
+        )
+        raise typer.Exit(2)
+    return cast("Callable[[AsyncSession], Any]", seed)
+
+
+async def _run_seed(database_url: str, seed: Callable[[AsyncSession], Any]) -> Any:
+    """Open one managed session and run the seed callable in it.
+
+    Args:
+        database_url (str): The resolved database URL.
+        seed (Callable[[AsyncSession], Any]): The seed callable; awaited
+            when it returns a coroutine.
+
+    Returns:
+        Any: Whatever the seed callable returns (e.g. a row count), or
+        ``None``.
+    """
+    from tempest_fastapi_sdk import AsyncDatabaseManager
+
+    manager = AsyncDatabaseManager(database_url)
+    await manager.connect()
+    try:
+        async with manager.get_session_context() as session:
+            result = seed(session)
+            if inspect.isawaitable(result):
+                result = await result
+            return result
+    finally:
+        await manager.disconnect()
+
+
 db_app: typer.Typer = typer.Typer(
     name="db",
     help="Alembic migration helpers (create / apply / inspect).",
@@ -242,6 +315,46 @@ def db_current(
     typer.echo(current or "(no revision applied)")
 
 
+@db_app.command("seed")
+def db_seed(
+    seed_spec: str = typer.Option(
+        "src.db.seeds:seed",
+        "--seed",
+        "-s",
+        help=(
+            "Dotted 'module.path:callable' to run. The callable receives "
+            "one positional AsyncSession and may be sync or async. Defaults "
+            "to the scaffolded 'src.db.seeds:seed'."
+        ),
+    ),
+    database_url: str | None = typer.Option(
+        None,
+        "--database-url",
+        help="Override DATABASE_URL for this run.",
+    ),
+) -> None:
+    """Run a project seed callable inside one managed session.
+
+    Builds an :class:`AsyncDatabaseManager` from the resolved URL, opens
+    a session (committed on success, rolled back on error), and invokes
+    the dotted callable with it. The callable owns what gets inserted —
+    the SDK only wires the session lifecycle so seeding looks the same
+    across every service.
+    """
+    url = _resolve_database_url(database_url)
+    if url is None:
+        typer.echo(
+            "error: no database URL. Pass --database-url, set DATABASE_URL, "
+            "or run inside a project with src/core/settings.py.",
+            err=True,
+        )
+        raise typer.Exit(2)
+    seed_callable = _load_seed_callable(seed_spec)
+    result = asyncio.run(_run_seed(url, seed_callable))
+    suffix = f" ({result} rows)" if isinstance(result, int) else ""
+    typer.echo(f"Seeded via {seed_spec}{suffix}.")
+
+
 @db_app.command("history")
 def db_history(
     verbose: bool = typer.Option(

{tempest_fastapi_sdk-0.46.0 → tempest_fastapi_sdk-0.48.0}/tempest_fastapi_sdk/cli/main.py

@@ -14,6 +14,7 @@ from tempest_fastapi_sdk.cli import generate as generate_module
 from tempest_fastapi_sdk.cli import lint as lint_module
 from tempest_fastapi_sdk.cli import new as new_module
 from tempest_fastapi_sdk.cli.db import db_app
+from tempest_fastapi_sdk.cli.secrets import secrets_app
 from tempest_fastapi_sdk.cli.user import user_app
 
 # Typer >= 0.13 vendors its own copy of Click under ``typer._click``, so a
@@ -136,6 +137,7 @@ app: typer.Typer = typer.Typer(
 )
 app.add_typer(db_app, name="db")
 app.add_typer(user_app, name="user")
+app.add_typer(secrets_app, name="secrets")
 
 
 def _print_version(value: bool) -> None: