cdt-kit 0.1.0__tar.gz

cdt_kit-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+# python
+__pycache__/
+*.pyc
+.venv/
+venv/
+# runtime
+data/
+logs/
+*.log
+*.tmp
+*.bak
+node_modules/
+.DS_Store
+.toolkit/
+# build and test output
+dist/
+build/
+*.egg-info/
+.pytest_cache/

cdt_kit-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0 — 2026-10-28
+- First release of the kit (claude-deploy-toolkit #422, sequenced in claude-deploy-toolkit #432 section 4): distribution
+  `cdt-kit`, import name `cdtkit`; framework-agnostic core plus the FastAPI adapter.
+- `cdtkit.config`: `*_FILE` secrets (an empty file counts as unset), the database from `DATABASE_*` and
+  `DATABASE_PASSWORD_FILE`, `ENV_CLASS`, `CDT_LANGUAGE`, `TOOLKIT_JOB_TYPES`.
+- `cdtkit.migrations`: forward-only SQL files under an advisory lock with `schema_migrations` (compatible with
+  magic-minutes' table), the queue schema when missing, and the expand-only lint (`python -m cdtkit.migrations lint`).
+- `cdtkit.jobs`: procrastinate with one queue per job type, `Backoff` (total attempts, exponential with jitter, capped),
+  `NoRow` ending a job as `skipped=no-row`, the final-failure hook; the worker process with heartbeat health; dead-worker
+  and stuck-job recovery; `prune_finished` after `failed_retention`.
+- `cdtkit.http`: logfmt logging and health checks; `cdtkit.fastapi.health_router` for `/healthz`.
+- `cdtkit.testing`: the Postgres fixtures (`cdt_postgres`, `cdt_database`) and the in-memory queue.
+- The self-test stack (selftest and its testdb sidecar) and publishing to PyPI with Trusted Publishing (RUNBOOK.md).

cdt_kit-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: cdt-kit
+Version: 0.1.0
+Summary: Server-side app kit of the Controlled Delivery Toolkit: config, migrations, jobs and HTTP basics
+Project-URL: Source, https://github.com/fromerobr-ai/cdt-kit
+Project-URL: Changelog, https://github.com/fromerobr-ai/cdt-kit/blob/main/CHANGELOG.md
+Author: fromerobr-ai
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: psycopg<4,>=3.2
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.115; extra == 'fastapi'
+Provides-Extra: jobs
+Requires-Dist: procrastinate<4,>=3.10; extra == 'jobs'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# cdt-kit
+
+The server-side app kit of the Controlled Delivery Toolkit (CDT): a Python library every app pins for what the toolkit's
+standard asks of its request path, so projects stop rebuilding it (claude-deploy-toolkit #422). Distribution `cdt-kit`
+on PyPI, import name `cdtkit` (PyPI's `cdt` is another project's module).
+
+0.1.0 holds what the pilot, magic-minutes, needs first:
+
+| Module | What it does |
+|---|---|
+| `cdtkit.config` | `*_FILE` secrets, the database from `DATABASE_*`, `ENV_CLASS`, `CDT_LANGUAGE`, `TOOLKIT_JOB_TYPES` |
+| `cdtkit.migrations` | forward-only SQL files at start (advisory lock, `schema_migrations`), the expand-only lint |
+| `cdtkit.jobs` | procrastinate on the app's Postgres: one queue per job type, backoff with jitter, `NoRow` (`skipped=no-row`), the final-failure hook |
+| `cdtkit.jobs.worker` | the worker process: one worker per queue, heartbeat health check, graceful stop |
+| `cdtkit.jobs.recovery` | dead-worker and stuck-job recovery |
+| `cdtkit.jobs.prune` | finished jobs removed after `failed_retention` (run from a declared schedule) |
+| `cdtkit.http` | logfmt logging on stdout, the `/healthz` checks |
+| `cdtkit.fastapi` | the FastAPI adapter: `health_router` |
+| `cdtkit.testing` | test stand-ins: a Postgres (`cdt_postgres`, `cdt_database` fixtures) and the in-memory queue |
+
+Identity, the account contract, legal, i18n and consent come in 0.2.0; `/metrics`, RFC 9457 problems, rate classes and
+Idempotency-Key later (see #422).
+
+## Install and pin
+
+```
+cdt-kit[jobs,fastapi]==0.1.0      # requirements.txt of an app; [test] for its test environment
+```
+
+The core depends only on `psycopg` 3 (choose its C build in the app: `psycopg[binary]`); `jobs` adds procrastinate
+3.x, `fastapi` the adapter, `test` pytest and the fixtures. Python 3.11 or newer.
+
+**Production pins only stable kit versions.** Every deployed kit candidate is published to PyPI at once, so its pilot
+can test it before promotion; a version is stable once promoted (`RELEASES.md` of this repository, the GitHub Release
+marked latest). An app may pin a candidate on staging; its production deployments pin a stable version. The toolkit's
+rule `kit-version` (planned, claude-deploy-toolkit #423) will check it; until then it is a rule each app keeps.
+
+Versions are semantic: a minor adds, a major breaks; anything deprecated keeps working for two minors with a warning.
+At most one kit release per toolkit minor.
+
+## Use
+
+Configuration, read once at start:
+
+```python
+from cdtkit import config
+
+db = config.database()                      # DATABASE_HOST/_PORT/_NAME/_USER + DATABASE_PASSWORD_FILE
+conninfo = db.conninfo("web")               # libpq string; repr(db) never shows the password
+key = config.read_secret("KEYS_ENCRYPTION_KEY")          # KEYS_ENCRYPTION_KEY_FILE, else the variable (local runs)
+optional = config.read_secret("SMTP_PASSWORD", required=False)   # "" when unset or an empty file
+env_class, language = config.env_class(), config.language()     # "staging"/"production", CDT_LANGUAGE
+job_types = config.job_types(service="worker")            # this worker's TOOLKIT_JOB_TYPES entry: {id: params}
+```
+
+Missing or invalid configuration raises `config.ConfigError` (a `SystemExit`: the process stops with one line).
+
+Migrations at start, in every process (web and workers may start together; one migrates, the others wait):
+
+```python
+from cdtkit import migrations
+migrations.migrate(conninfo, "app/migrations", queue_app=queue_app)   # *.sql in name order, each once
+```
+
+Each file runs in its own transaction and is recorded in `schema_migrations (name, applied_at)`; with a procrastinate
+app, its schema is applied when missing. The lint reports contracting statements (drops, renames, type changes, new
+`NOT NULL`, `UNIQUE` or `CHECK` on existing data):
+
+```
+python -m cdtkit.migrations lint app/migrations [--after 0007_accounts_ui.sql]    # exit 1 on findings
+```
+
+A contract belongs in a cleanup release that declares it in `deploy/package.json` `"contracts"`; mark its line
+`-- cdt: contract <reason>` and the lint accepts it.
+
+Jobs (one queue per job type; parameters from `deploy/workers.json` through `TOOLKIT_JOB_TYPES`):
+
+```python
+from cdtkit import jobs
+from cdtkit.jobs import worker
+
+DEFAULTS = {"convert": {"concurrency": 1, "max_attempts": 3, "backoff": "60s", "timeout_item": "3h"}}
+
+async def convert(meeting_id):
+    meeting = load(meeting_id)
+    if meeting is None:
+        raise jobs.NoRow("meeting gone")    # deleted while queued: the job ends, logged skipped=no-row, no retry
+    ...
+
+app = jobs.make_app(conninfo, job_types, {"convert": convert}, DEFAULTS, pool_max=2, on_final_failure=mark_failed)
+await jobs.defer_async(app, "convert", meeting_id=7)          # web processes defer; payloads carry IDs only
+await worker.run(app, ["convert"], job_types, DEFAULTS, ping=db_ping, on_given_up=mark_failed,
+                 never_give_up=("account-delete",))
+```
+
+- `max_attempts` counts runs in total (at most 25); the wait after the n-th failure is `backoff * 2^(n-1)`, capped at 6
+  hours, shortened by up to half at random (jitter).
+- `on_final_failure(job_id, payload)` runs when the last attempt raises; `on_given_up` when the recovery gives a job up
+  (its worker died with no attempt left, or it ran past `timeout_item` plus 5 minutes). Both mark what the user sees.
+- The worker's container health check: `python -m cdtkit.jobs.worker --health` (exit 0 while the heartbeat in
+  `/tmp/worker-heartbeat` is younger than 80 seconds; the heartbeat runs `ping` first).
+- Finished jobs: successful ones are deleted at once; failed, cancelled and aborted ones after the entry's
+  `failed_retention` by `python -m cdtkit.jobs.prune --service worker`, which the app declares as a schedule
+  (`deploy/schedules.json`), never a loop in its code.
+
+HTTP basics:
+
+```python
+from cdtkit.http import Health
+from cdtkit.http.logging import setup
+from cdtkit.fastapi import health_router
+
+setup()                                                        # logfmt on stdout, one line per event
+app.include_router(health_router(Health(database=db.ping)))    # GET /healthz: 200 "ok" or 503 "unavailable: database"
+```
+
+Tests: with `cdt-kit[test]` installed the fixtures are there without imports:
+
+```python
+def test_store(cdt_database):                 # a fresh empty database (a cdtkit.config.Database)
+    migrations.migrate(cdt_database.conninfo(), "app/migrations")
+```
+
+They use the server named by `CDT_TEST_DATABASE_HOST` (`_PORT`, `_USER`, `_PASSWORD`, `_NAME`), else start a
+throwaway cluster with the local `initdb`/`pg_ctl` (not as root), else skip. `cdtkit.testing.queue.memory_app`,
+`drain` and `statuses` run job handlers on procrastinate's in-memory connector.
+
+## Layout
+
+```
+src/cdtkit/            the library (docs/PROJECT_NOTES.md has the module map)
+tests/                 the test suite (pytest; Postgres tests use the fixtures above)
+selftest/              the self-test stack's run script and the testdb sidecar's script
+compose.yaml           the self-test stack (below); Dockerfile its image
+requirements-selftest.txt   pinned dependencies of the self-test image (arm64 wheels checked)
+.github/workflows/publish.yml   publishing to PyPI
+```
+
+## The self-test stack
+
+The toolkit deploys Compose stacks, and a library has no service, so cdt-kit's stack proves the kit on each server that
+deploys it: `selftest` builds the wheel from the tree, installs it with the pinned dependencies and runs the test suite
+once per build against `testdb`, a throwaway Postgres 18 on an internal network that stops (exit 0) after the run.
+`selftest` then idles, healthy only when the tests passed, so a failing suite fails the deploy. The result is kept in
+`data/selftest/` per build: a restart does not rerun the tests. It is a workaround until the toolkit offers a
+check-only kind (claude-project-common#176); its two conformance exceptions point there.
+
+Run it by hand on the primary: `cd /opt/stacks/cdt-kit && docker compose logs selftest`.
+
+## Publishing
+
+`.github/workflows/publish.yml` publishes the wheel and the sdist to PyPI when the servers create the version's GitHub
+Release, that is when the candidate is deployed on the primary; PyPI Trusted Publishing, no stored token. The one-time
+setup on pypi.org is in `RUNBOOK.md`. The workflow's result shows on the release issue. A version that failed to
+publish is published again with the workflow's "Run workflow" button and its tag.
+
+Running the tests locally: `pip install -e .[jobs,fastapi,test]` then `pytest` (Postgres binaries on PATH or
+`CDT_TEST_DATABASE_HOST`).

cdt_kit-0.1.0/README.md

@@ -0,0 +1,158 @@
+# cdt-kit
+
+The server-side app kit of the Controlled Delivery Toolkit (CDT): a Python library every app pins for what the toolkit's
+standard asks of its request path, so projects stop rebuilding it (claude-deploy-toolkit #422). Distribution `cdt-kit`
+on PyPI, import name `cdtkit` (PyPI's `cdt` is another project's module).
+
+0.1.0 holds what the pilot, magic-minutes, needs first:
+
+| Module | What it does |
+|---|---|
+| `cdtkit.config` | `*_FILE` secrets, the database from `DATABASE_*`, `ENV_CLASS`, `CDT_LANGUAGE`, `TOOLKIT_JOB_TYPES` |
+| `cdtkit.migrations` | forward-only SQL files at start (advisory lock, `schema_migrations`), the expand-only lint |
+| `cdtkit.jobs` | procrastinate on the app's Postgres: one queue per job type, backoff with jitter, `NoRow` (`skipped=no-row`), the final-failure hook |
+| `cdtkit.jobs.worker` | the worker process: one worker per queue, heartbeat health check, graceful stop |
+| `cdtkit.jobs.recovery` | dead-worker and stuck-job recovery |
+| `cdtkit.jobs.prune` | finished jobs removed after `failed_retention` (run from a declared schedule) |
+| `cdtkit.http` | logfmt logging on stdout, the `/healthz` checks |
+| `cdtkit.fastapi` | the FastAPI adapter: `health_router` |
+| `cdtkit.testing` | test stand-ins: a Postgres (`cdt_postgres`, `cdt_database` fixtures) and the in-memory queue |
+
+Identity, the account contract, legal, i18n and consent come in 0.2.0; `/metrics`, RFC 9457 problems, rate classes and
+Idempotency-Key later (see #422).
+
+## Install and pin
+
+```
+cdt-kit[jobs,fastapi]==0.1.0      # requirements.txt of an app; [test] for its test environment
+```
+
+The core depends only on `psycopg` 3 (choose its C build in the app: `psycopg[binary]`); `jobs` adds procrastinate
+3.x, `fastapi` the adapter, `test` pytest and the fixtures. Python 3.11 or newer.
+
+**Production pins only stable kit versions.** Every deployed kit candidate is published to PyPI at once, so its pilot
+can test it before promotion; a version is stable once promoted (`RELEASES.md` of this repository, the GitHub Release
+marked latest). An app may pin a candidate on staging; its production deployments pin a stable version. The toolkit's
+rule `kit-version` (planned, claude-deploy-toolkit #423) will check it; until then it is a rule each app keeps.
+
+Versions are semantic: a minor adds, a major breaks; anything deprecated keeps working for two minors with a warning.
+At most one kit release per toolkit minor.
+
+## Use
+
+Configuration, read once at start:
+
+```python
+from cdtkit import config
+
+db = config.database()                      # DATABASE_HOST/_PORT/_NAME/_USER + DATABASE_PASSWORD_FILE
+conninfo = db.conninfo("web")               # libpq string; repr(db) never shows the password
+key = config.read_secret("KEYS_ENCRYPTION_KEY")          # KEYS_ENCRYPTION_KEY_FILE, else the variable (local runs)
+optional = config.read_secret("SMTP_PASSWORD", required=False)   # "" when unset or an empty file
+env_class, language = config.env_class(), config.language()     # "staging"/"production", CDT_LANGUAGE
+job_types = config.job_types(service="worker")            # this worker's TOOLKIT_JOB_TYPES entry: {id: params}
+```
+
+Missing or invalid configuration raises `config.ConfigError` (a `SystemExit`: the process stops with one line).
+
+Migrations at start, in every process (web and workers may start together; one migrates, the others wait):
+
+```python
+from cdtkit import migrations
+migrations.migrate(conninfo, "app/migrations", queue_app=queue_app)   # *.sql in name order, each once
+```
+
+Each file runs in its own transaction and is recorded in `schema_migrations (name, applied_at)`; with a procrastinate
+app, its schema is applied when missing. The lint reports contracting statements (drops, renames, type changes, new
+`NOT NULL`, `UNIQUE` or `CHECK` on existing data):
+
+```
+python -m cdtkit.migrations lint app/migrations [--after 0007_accounts_ui.sql]    # exit 1 on findings
+```
+
+A contract belongs in a cleanup release that declares it in `deploy/package.json` `"contracts"`; mark its line
+`-- cdt: contract <reason>` and the lint accepts it.
+
+Jobs (one queue per job type; parameters from `deploy/workers.json` through `TOOLKIT_JOB_TYPES`):
+
+```python
+from cdtkit import jobs
+from cdtkit.jobs import worker
+
+DEFAULTS = {"convert": {"concurrency": 1, "max_attempts": 3, "backoff": "60s", "timeout_item": "3h"}}
+
+async def convert(meeting_id):
+    meeting = load(meeting_id)
+    if meeting is None:
+        raise jobs.NoRow("meeting gone")    # deleted while queued: the job ends, logged skipped=no-row, no retry
+    ...
+
+app = jobs.make_app(conninfo, job_types, {"convert": convert}, DEFAULTS, pool_max=2, on_final_failure=mark_failed)
+await jobs.defer_async(app, "convert", meeting_id=7)          # web processes defer; payloads carry IDs only
+await worker.run(app, ["convert"], job_types, DEFAULTS, ping=db_ping, on_given_up=mark_failed,
+                 never_give_up=("account-delete",))
+```
+
+- `max_attempts` counts runs in total (at most 25); the wait after the n-th failure is `backoff * 2^(n-1)`, capped at 6
+  hours, shortened by up to half at random (jitter).
+- `on_final_failure(job_id, payload)` runs when the last attempt raises; `on_given_up` when the recovery gives a job up
+  (its worker died with no attempt left, or it ran past `timeout_item` plus 5 minutes). Both mark what the user sees.
+- The worker's container health check: `python -m cdtkit.jobs.worker --health` (exit 0 while the heartbeat in
+  `/tmp/worker-heartbeat` is younger than 80 seconds; the heartbeat runs `ping` first).
+- Finished jobs: successful ones are deleted at once; failed, cancelled and aborted ones after the entry's
+  `failed_retention` by `python -m cdtkit.jobs.prune --service worker`, which the app declares as a schedule
+  (`deploy/schedules.json`), never a loop in its code.
+
+HTTP basics:
+
+```python
+from cdtkit.http import Health
+from cdtkit.http.logging import setup
+from cdtkit.fastapi import health_router
+
+setup()                                                        # logfmt on stdout, one line per event
+app.include_router(health_router(Health(database=db.ping)))    # GET /healthz: 200 "ok" or 503 "unavailable: database"
+```
+
+Tests: with `cdt-kit[test]` installed the fixtures are there without imports:
+
+```python
+def test_store(cdt_database):                 # a fresh empty database (a cdtkit.config.Database)
+    migrations.migrate(cdt_database.conninfo(), "app/migrations")
+```
+
+They use the server named by `CDT_TEST_DATABASE_HOST` (`_PORT`, `_USER`, `_PASSWORD`, `_NAME`), else start a
+throwaway cluster with the local `initdb`/`pg_ctl` (not as root), else skip. `cdtkit.testing.queue.memory_app`,
+`drain` and `statuses` run job handlers on procrastinate's in-memory connector.
+
+## Layout
+
+```
+src/cdtkit/            the library (docs/PROJECT_NOTES.md has the module map)
+tests/                 the test suite (pytest; Postgres tests use the fixtures above)
+selftest/              the self-test stack's run script and the testdb sidecar's script
+compose.yaml           the self-test stack (below); Dockerfile its image
+requirements-selftest.txt   pinned dependencies of the self-test image (arm64 wheels checked)
+.github/workflows/publish.yml   publishing to PyPI
+```
+
+## The self-test stack
+
+The toolkit deploys Compose stacks, and a library has no service, so cdt-kit's stack proves the kit on each server that
+deploys it: `selftest` builds the wheel from the tree, installs it with the pinned dependencies and runs the test suite
+once per build against `testdb`, a throwaway Postgres 18 on an internal network that stops (exit 0) after the run.
+`selftest` then idles, healthy only when the tests passed, so a failing suite fails the deploy. The result is kept in
+`data/selftest/` per build: a restart does not rerun the tests. It is a workaround until the toolkit offers a
+check-only kind (claude-project-common#176); its two conformance exceptions point there.
+
+Run it by hand on the primary: `cd /opt/stacks/cdt-kit && docker compose logs selftest`.
+
+## Publishing
+
+`.github/workflows/publish.yml` publishes the wheel and the sdist to PyPI when the servers create the version's GitHub
+Release, that is when the candidate is deployed on the primary; PyPI Trusted Publishing, no stored token. The one-time
+setup on pypi.org is in `RUNBOOK.md`. The workflow's result shows on the release issue. A version that failed to
+publish is published again with the workflow's "Run workflow" button and its tag.
+
+Running the tests locally: `pip install -e .[jobs,fastapi,test]` then `pytest` (Postgres binaries on PATH or
+`CDT_TEST_DATABASE_HOST`).

cdt_kit-0.1.0/VERSION

@@ -0,0 +1 @@
+0.1.0

cdt_kit-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling==1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cdt-kit"
+dynamic = ["version"]
+description = "Server-side app kit of the Controlled Delivery Toolkit: config, migrations, jobs and HTTP basics"
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "fromerobr-ai" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Framework :: FastAPI",
+  "Topic :: Database",
+  "Operating System :: POSIX :: Linux",
+]
+# The core needs only psycopg 3; the driver's C build is the app's choice (psycopg[binary] or [c]).
+dependencies = ["psycopg>=3.2,<4"]
+
+[project.optional-dependencies]
+jobs = ["procrastinate>=3.10,<4"]
+fastapi = ["fastapi>=0.115"]
+test = ["pytest>=8", "pytest-asyncio>=0.24"]
+
+[project.urls]
+Source = "https://github.com/fromerobr-ai/cdt-kit"
+Changelog = "https://github.com/fromerobr-ai/cdt-kit/blob/main/CHANGELOG.md"
+
+[project.entry-points.pytest11]
+cdtkit = "cdtkit.testing.plugin"
+
+[tool.hatch.version]
+path = "src/cdtkit/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cdtkit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/cdtkit", "tests", "README.md", "CHANGELOG.md", "VERSION"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

cdt_kit-0.1.0/src/cdtkit/__init__.py

@@ -0,0 +1,7 @@
+"""cdt-kit: the server-side app kit of the Controlled Delivery Toolkit (CDT).
+
+Modules (0.1.0): `cdtkit.config` (environment and `*_FILE` secrets), `cdtkit.migrations` (forward-only SQL files),
+`cdtkit.jobs` (procrastinate on the app's Postgres), `cdtkit.http` (logfmt logging and the health check) and the
+FastAPI adapter `cdtkit.fastapi`; `cdtkit.testing` holds the test stand-ins. The core imports no web framework.
+"""
+__version__ = "0.1.0"

cdt_kit-0.1.0/src/cdtkit/config.py

@@ -0,0 +1,118 @@
+"""Configuration the toolkit gives every app: read once at start from the environment and the secret files.
+
+Values come from `config/defaults.env`, `.toolkit/vars.env` (rendered by the toolkit) and `.env`, through Compose's
+`env_file`; every secret from the file named by `<NAME>_FILE` (the toolkit mounts `.toolkit/secrets/<NAME>`). The
+database is given in parts (`DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, the password in
+`DATABASE_PASSWORD_FILE`), never as a URL (standard, chapter "database").
+"""
+import json
+import os
+from dataclasses import dataclass
+
+ENV_CLASSES = ("staging", "production")
+
+
+class ConfigError(SystemExit):
+    """A configuration the app cannot start with: the process stops with this message (no traceback)."""
+
+
+def _env(env):
+    return os.environ if env is None else env
+
+
+def read_secret(name, env=None, required=True):
+    """The value of secret NAME: the file named by NAME_FILE (toolkit secrets), else NAME itself (local runs, tests).
+
+    Surrounding whitespace is removed. An empty value counts as unset: an optional secret with no value on a server
+    arrives as an empty file (toolkit 2.111.0). Returns "" for an unset optional secret; raises ConfigError for an
+    unset required one or an unreadable file.
+    """
+    env = _env(env)
+    path = env.get(name + "_FILE")
+    if path:
+        try:
+            with open(path, encoding="utf-8") as f:
+                value = f.read().strip()
+        except OSError as e:
+            raise ConfigError("%s: cannot read %s (%s)" % (name, path, e.strerror))
+    else:
+        value = (env.get(name) or "").strip()
+    if not value and required:
+        raise ConfigError("%s: missing or empty (written by the toolkit into .toolkit/secrets/)" % name)
+    return value
+
+
+@dataclass(frozen=True)
+class Database:
+    host: str
+    port: int
+    name: str
+    user: str
+    password: str
+
+    def conninfo(self, application_name=""):
+        """A libpq connection string; values are quoted, so a password with spaces or quotes stays one value."""
+        parts = [("host", self.host), ("port", str(self.port)), ("dbname", self.name), ("user", self.user),
+                 ("password", self.password)]
+        if application_name:
+            parts.append(("application_name", application_name))
+        return " ".join("%s=%s" % (k, _quote(v)) for k, v in parts)
+
+    def __repr__(self):   # never the password in a log line or a traceback
+        return "Database(host=%r, port=%d, name=%r, user=%r)" % (self.host, self.port, self.name, self.user)
+
+
+def _quote(value):
+    if value and not any(c in value for c in " '\\"):
+        return value
+    return "'" + value.replace("\\", "\\\\").replace("'", "\\'") + "'"
+
+
+def database(env=None):
+    """The app's database from DATABASE_* and the password file; ConfigError names every missing variable."""
+    env = _env(env)
+    missing = [n for n in ("DATABASE_HOST", "DATABASE_NAME", "DATABASE_USER") if not (env.get(n) or "").strip()]
+    if missing:
+        raise ConfigError("missing configuration: %s" % ", ".join(missing))
+    raw_port = (env.get("DATABASE_PORT") or "").strip() or "5432"
+    if not raw_port.isdigit():
+        raise ConfigError("DATABASE_PORT must be a port number")
+    return Database(env["DATABASE_HOST"].strip(), int(raw_port), env["DATABASE_NAME"].strip(),
+                    env["DATABASE_USER"].strip(), read_secret("DATABASE_PASSWORD", env))
+
+
+def env_class(env=None, default="staging"):
+    """ENV_CLASS: "staging" or "production" (the toolkit writes it); `default` when unset (local runs, tests)."""
+    value = (_env(env).get("ENV_CLASS") or "").strip() or default
+    if value not in ENV_CLASSES and value != default:
+        raise ConfigError("ENV_CLASS must be one of %s" % ", ".join(ENV_CLASSES))
+    return value
+
+
+def is_production(env=None):
+    return env_class(env) == "production"
+
+
+def language(env=None):
+    """CDT_LANGUAGE, the deployment's default language (a BCP 47 tag); "" means the app's own default."""
+    return (_env(env).get("CDT_LANGUAGE") or "").strip()
+
+
+def worker_entry(env=None, service="worker"):
+    """This worker service's entry of TOOLKIT_JOB_TYPES (deploy/workers.json, rendered by the toolkit):
+    {"queue", "failed_retention", "job_types": {id: params}}; {} when the variable is unset or names no such service."""
+    raw = (_env(env).get("TOOLKIT_JOB_TYPES") or "").strip()
+    if not raw:
+        return {}
+    try:
+        entry = json.loads(raw).get(service) or {}
+    except (ValueError, AttributeError):
+        raise ConfigError("TOOLKIT_JOB_TYPES is not valid JSON")
+    if not isinstance(entry, dict) or not isinstance(entry.get("job_types", {}), (dict, type(None))):
+        raise ConfigError("TOOLKIT_JOB_TYPES: the entry of %s is not an object" % service)
+    return entry
+
+
+def job_types(env=None, service="worker"):
+    """The worker service's job types from TOOLKIT_JOB_TYPES: {id: params}; {} when unset."""
+    return worker_entry(env, service).get("job_types", {}) or {}

cdt_kit-0.1.0/src/cdtkit/fastapi.py

@@ -0,0 +1,35 @@
+"""The FastAPI adapter (the starter's framework): the health route of `cdtkit.http`.
+
+    from cdtkit.fastapi import health_router
+    app.include_router(health_router(Health(database=db.ping)))
+
+GET /healthz answers 200 "ok" or 503 "unavailable: <checks>", plain text, never cached, outside the OpenAPI schema.
+Sync checks run in the thread pool, so a slow database never blocks the event loop.
+"""
+from fastapi import APIRouter
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import PlainTextResponse
+import inspect
+
+from cdtkit.http import HEALTH_PATH, Health
+
+NO_STORE = {"Cache-Control": "no-store"}
+
+
+def _threaded(check):
+    if inspect.iscoroutinefunction(check):
+        return check
+    return lambda: run_in_threadpool(check)
+
+
+def health_router(health=None, path=HEALTH_PATH):
+    """An APIRouter with the health route; `health` is a `cdtkit.http.Health` (none: always "ok")."""
+    checks = Health(**{name: _threaded(c) for name, c in (health.checks if health else {}).items()})
+    router = APIRouter()
+
+    @router.get(path, include_in_schema=False)
+    async def healthz():
+        ok, body = await checks.run()
+        return PlainTextResponse(body, status_code=200 if ok else 503, headers=NO_STORE)
+
+    return router

cdt_kit-0.1.0/src/cdtkit/http/__init__.py

@@ -0,0 +1,39 @@
+"""The HTTP rules every app shares, framework-agnostic; `cdtkit.fastapi` adapts them to FastAPI.
+
+0.1.0: logfmt logging (`cdtkit.http.logging`) and the health check (`Health`, answered on `/healthz`, the path
+deploy/web.json's `"health"` names). Later releases add `/metrics`, RFC 9457 problem details, rate-limit classes and the
+Idempotency-Key store (claude-deploy-toolkit #422).
+"""
+import inspect
+import logging
+
+log = logging.getLogger("cdtkit.http")
+HEALTH_PATH = "/healthz"
+
+
+class Health:
+    """Named checks (sync or async callables; a check passes when it returns without raising), e.g. the database's
+    `SELECT 1`. With no checks the process answers "ok" as soon as it serves requests."""
+
+    def __init__(self, **checks):
+        self.checks = dict(checks)
+
+    def add(self, name, check):
+        self.checks[name] = check
+        return self
+
+    async def run(self):
+        """(ok, body): body is "ok\\n", or "unavailable: <names>\\n" naming the failed checks (never their errors,
+        which can hold internals; those go to the log)."""
+        failed = []
+        for name, check in self.checks.items():
+            try:
+                result = check()
+                if inspect.isawaitable(result):
+                    await result
+            except Exception as e:
+                failed.append(name)
+                log.warning("health check failed check=%s: %s", name, type(e).__name__)
+        if failed:
+            return False, "unavailable: %s\n" % ",".join(failed)
+        return True, "ok\n"