terp-cli 0.36.0__tar.gz → 0.37.0__tar.gz

{terp_cli-0.36.0 → terp_cli-0.37.0}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.36.0
+Version: 0.37.0
 Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
 Project-URL: Repository, https://github.com/AITT-NL/terp-framework
 Project-URL: Changelog, https://github.com/AITT-NL/terp-framework/blob/main/CHANGELOG.md
 License-Expression: Apache-2.0
 Requires-Python: >=3.13
 Requires-Dist: pyyaml>=6.0
-Requires-Dist: terp-arch==0.36.0
-Requires-Dist: terp-core==0.36.0
-Requires-Dist: terp-migrations==0.36.0
+Requires-Dist: terp-arch==0.37.0
+Requires-Dist: terp-core==0.37.0
+Requires-Dist: terp-migrations==0.37.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.36.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.36.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.37.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.37.0; extra == 'jobs'
 Provides-Extra: release
 Requires-Dist: cryptography>=46; extra == 'release'
 Requires-Dist: packaging>=24; extra == 'release'
-Requires-Dist: terp-cap-egress==0.36.0; extra == 'release'
+Requires-Dist: terp-cap-egress==0.37.0; extra == 'release'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.36.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.37.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.36.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.37.0; extra == 'worker'

{terp_cli-0.36.0 → terp_cli-0.37.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.36.0"
+version = "0.37.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.36.0",
+    "terp-core==0.37.0",
     # `terp migrate` delegates to terp-migrations (lazily imported), keeping Alembic
     # off the path for `terp inspect` / `terp guide` while making migrations work.
-    "terp-migrations==0.36.0",
+    "terp-migrations==0.37.0",
     # `terp guide rules` projects the live rule registry; terp-arch is imported lazily
     # (only when that topic is rendered), so it stays off the common `terp guide` path.
-    "terp-arch==0.36.0",
+    "terp-arch==0.37.0",
     # `terp verify --only env-seams` and `terp smoke` read the compose profiles as data
     # (anchors and `<<:` merge keys resolved), so both answer without a Docker daemon or
     # even the `docker` binary. Declared explicitly rather than leant on: every app
@@ -29,11 +29,11 @@ dependencies = [
 # or a scheduler engine into apps that only use inspect/check/migrate. Deployments can select
 # one process role, while `jobs` is the convenient complete jobs-process bundle.
 [project.optional-dependencies]
-worker = ["terp-cap-outbox==0.36.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.36.0"]
+worker = ["terp-cap-outbox==0.37.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.37.0"]
 jobs = [
-    "terp-cap-outbox==0.36.0",
-    "terp-cap-scheduler-apscheduler==0.36.0",
+    "terp-cap-outbox==0.37.0",
+    "terp-cap-scheduler-apscheduler==0.37.0",
 ]
 # `terp release` and `terp promote` (ADR 0187): the DSSE signature (cryptography), the lock's
 # markers (packaging), and the one declared way to a registry, an index and the vulnerability
@@ -42,7 +42,7 @@ jobs = [
 release = [
     "cryptography>=46",
     "packaging>=24",
-    "terp-cap-egress==0.36.0",
+    "terp-cap-egress==0.37.0",
 ]
 
 [project.scripts]

{terp_cli-0.36.0 → terp_cli-0.37.0}/src/terp/cli/__init__.py

@@ -41,7 +41,7 @@ from terp.cli.jobs import (
     run_scheduler_command,
     run_worker_command,
 )
-from terp.cli.openapi import _load_app, export_openapi
+from terp.cli.openapi import _load_app, export_openapi, run_openapi_command
 from terp.cli.routes import run_routes_command
 from terp.cli.profiles import DEFAULT_PROFILE, profile_names
 from terp.cli.scaffold import new_module, new_module_message
@@ -82,21 +82,24 @@ _GUIDE_TOPICS: dict[str, str] = {
 Add a module (the "10-minute module")
 
 1) models.py   table model (inherit BaseTable; never redeclare id/created_at/version)
-     from terp.core import BaseTable
+     from datetime import datetime
+     from terp.core import BaseTable, UtcDateTime
      from sqlmodel import Field
      class Invoice(BaseTable, table=True):
          number: str = Field(max_length=50, index=True, unique=True)
          amount_cents: int
+         issued_at: datetime = Field(sa_type=UtcDateTime())   # an instant, stored as UTC
 
 2) schemas.py  DTOs (cap every input string; the Read DTO is what the API returns)
      from terp.core import BaseSchema, BaseUpdateSchema
      class InvoiceCreate(BaseSchema):
          number: str = Field(max_length=50)
          amount_cents: int
+         issued_at: datetime
      class InvoiceUpdate(BaseUpdateSchema):   # `version` is required (optimistic concurrency)
          amount_cents: int | None = None
      class InvoiceRead(BaseSchema):           # NOT the table model
-         id: uuid.UUID; number: str; amount_cents: int; version: int
+         id: uuid.UUID; number: str; amount_cents: int; issued_at: datetime; version: int
 
 3) service.py  business logic (CRUD is inherited and audited)
      from terp.core import BaseService
@@ -133,6 +136,9 @@ Then the codegen chain, in this order — each step reads what the one before it
 
 `terp verify` runs the drift halves of that chain and names the command to re-run when
 something is stale, so it is the one to reach for if you are unsure what is out of date.
+An API-only app (rendered with the template's `frontend: false`, ADR 0202) has no
+frontend: its chain is `terp migrate make`, `terp openapi` and `terp check`, and
+`terp new module` writes no frontend slot where there is none.
 Policy.default() = authenticated; read VIEWER, write EDITOR.
 
 FORMATTING: `terp fmt`, NOT `ruff format .`
@@ -339,11 +345,15 @@ Both are comma-separated. The procedure, in this order:
   1. Put the old key in BOTH lists and the new one in SECRET_KEY. Deploy.
   2. Run `terp secrets reseal` where the app runs (its own container, its own
      environment). It rewrites every value sealed under a fallback under SECRET_KEY,
+     one nested in a JSON column included (a queued mail in the outbox, ADR 0199),
      one transaction per table, refuses while a migration is pending, is safe to run
      twice, and exits 0 only when nothing is left. `--check` counts and writes nothing.
   3. Drop SECRET_KEY_DECRYPT_FALLBACKS once reseal reports nothing left. Keep the old
      key itself while a backup sealed under it may still be restored: restoring one
-     means listing it again and running reseal.
+     means listing it again and running reseal. A self-service link already mailed is
+     sealed under the key it was sent under, where reseal cannot reach it, so dropping
+     the fallback sooner than its lifetime (a day for a sign-up link by default) only
+     makes such a link stop working, and its owner asks for a new one.
   4. Drop SECRET_KEY_FALLBACKS once the longest signature lifetime has passed since
      step 1: REFRESH_TOKEN_TTL_SECONDS if the app issues refresh sessions, 15 minutes
      if not. Dropping it sooner loses nothing; it signs out sessions still on the old key.
@@ -991,6 +1001,58 @@ Object-level (per-row) authorization (OwnedMixin)
   apply_object_authz does not restrict a row with no ownership trait, so the job body
   itself would run fine. The clause is a judgement about the DESIGN, enforced before the
   app serves anything -- not a description of what the write boundary would do.
+""",
+    "aggregates": """\
+Aggregates: counts and sums declared on the service, like filters (ADR 0204)
+
+- The problem: a statistics screen counts and sums the rows its lists read. A hand-built
+  select(func.count(...)).group_by(...) over a soft-delete or tenant model is what
+  reads_use_base_query refuses, and the workaround (an aggregate over a subquery of
+  base_query()) makes every module solve calendar days, bounds and grouping on its own.
+- Declare what may be counted and summed, and by what, beside filterable and sortable:
+      from terp.core import Dimension, FilterField, Measure, TimeBucket
+      class InvoiceService(BaseService[Invoice, InvoiceCreate, InvoiceUpdate]):
+          model = Invoice
+          filterable = (FilterField("customer_id", Invoice.customer_id),)
+          measures = (Measure("invoices"), Measure("revenue", Invoice.amount, op="sum"))
+          dimensions = (Dimension("status", Invoice.status),)
+          time_buckets = (TimeBucket("issued", Invoice.issued_at, steps=("day", "month")),)
+  op is one of count, count_distinct, sum, avg, min, max. A dimension groups by a
+  column's own values; an expression is a column the model declares, or a database view.
+- The route takes the capped query and returns a page typed by the declarations:
+      from terp.core import Page, SessionDep, StatisticsQueryDep
+      @router.get("/statistics", response_model=Page[InvoiceService.statistics_model()])
+      def invoice_statistics(query: StatisticsQueryDep, session: SessionDep, customer_id: uuid.UUID | None = None):
+          return InvoiceService().aggregate_page(session, query, filters={"customer_id": customer_id})
+  The caller asks ?measures=invoices&measures=revenue&by=status&sort=-revenue, and for a
+  series &bucket=issued&start=2026-01-01&end=2026-12-31&zone=Europe/Amsterdam&step=month.
+- Each group carries its dimensions, its measures and, with a step, its series: one point
+  per calendar step of the zone, empty steps counting zero, each with its local date (label
+  a step by date, not by re-zoning start). total counts the groups, so "the top eight" is
+  limit=8 and the rest are still counted. A Numeric sum arrives as a decimal string.
+- A day is the zone's own, so a day that daylight saving shortens keeps its real length. A
+  week starts on Monday; a series may start or end part way through a week or month.
+- Everything undeclared is refused with a 400 that lists what is declared: a measure, a
+  dimension, a time bucket, a step, a sort key, a filter. A page holds at most max_groups
+  (100); a series at most the bucket's max_buckets (366); a page at most max_points (10,000)
+  groups times steps. Each cap refuses, never clamps, and names what would fit.
+- Personal data stays personal. A Dimension or a TimeBucket over a field declared
+  Personal(...), and a sum, avg, min or max over one, is refused when the class is defined:
+  over a group of one each is that person's value. count and count_distinct may run over
+  personal data. A statistic is never narrowed by a filter over a personal field (counts
+  under a contains filter would spell out an address); the list keeps its filter.
+- A read that is not a service's (a capability's own table) uses the same seam directly:
+      from terp.core import Statistics, aggregate, group_model
+      STATS = Statistics(measures=(Measure("events"),), dimensions=(...,), time_buckets=(...,))
+      groups, total = aggregate(session, select(AuditEvent), STATS, measures=["events"], ...)
+- The runtime half: the request session scopes every ORM read, aggregates included, and
+  refuses with UnscopedReadError (a 500) a SELECT that reads a row-scoped table through Core
+  - Model.__table__.c.x, a Core join or subquery over it, a Core alias, table("name"),
+  literal SQL in a FROM - because there is no mapped entity in that SELECT to attach the
+  scope to. A many-to-many whose link table is row-scoped is refused the same way: map the
+  link as an association object.
+- On SQLite a timestamp is stored as its wall time without its offset: write instants in UTC
+  (every timestamp the framework stamps already is) and the steps are exact on both dialects.
 """,
     "leases": """\
 Leases: expiring, fenced custody of work (leases capability)
@@ -1100,9 +1162,27 @@ The security declaration (SecurityConfig, refused at production boot)
   /openapi.json are hidden there because a production API's full schema is not public
   information. Development always serves them, and `terp openapi` exports the document
   either way - so turning this on is a choice to publish, not a way to get the file.
+  Commit that file instead: `openapi.json` is the app's API contract, the one a mobile
+  app or a site in another repository pins, and `terp verify --only api-contract` holds
+  it to the API the app serves, naming every change to its shape, the ones that break a
+  client first (ADR 0194). Who may call a route is not in it: authz-surface pins that.
 - headers ships a safe SecurityHeaders set; max_request_bytes (1 MiB) is the body cap and
   is per-mount overridable (ADR 0067); request_id_header names the correlation header
   ("X-Request-ID") echoed on every response.
+- A NATIVE MOBILE CLIENT stays signed in through its own routes, opt-in with a reason
+  (ADR 0195): build_login_module(..., native_clients=NativeClients(reason="...")) mounts
+  POST /api/v1/auth/native/login, /native/refresh and /native/logout. The first two answer
+  the refresh token in the JSON body and run the same rotation, reuse detection and
+  revocation as the cookie, its rotation grace window included; /native/logout takes the
+  token and revokes its whole family without minting a successor. The client keeps that
+  token in the OS keychain or keystore and nowhere else, and treats a 401 from
+  /native/refresh as signed out. All three refuse any request with browser provenance
+  (Origin, any Sec-Fetch-* header, the refresh cookie) with 403 native_client_only before
+  the body is validated, so a browser stays on /login, /refresh and /logout. A HYBRID app
+  (a page inside a native shell) calls them from its native layer and hands its page only
+  access tokens: a page that holds the refresh token has given up what the cookie
+  protects. No route that mints a credential (/login, /token, /refresh, /native/login,
+  /native/refresh) accepts an Idempotency-Key; retry without one.
 - No terp.arch check applies - there is no module code shape to police. Enforcement is
   the create_app production fail-fast plus the production-readiness verify lane.
 """,
@@ -1213,6 +1293,21 @@ Password strength (PasswordPolicy, Tier-B)
   The reason is the opt-out: it is stored as `relaxed_reason` and named back to you in the
   BootError, so "why is this off" always has an answer that travels with the declaration.
       PasswordPolicy.relaxed(reason="legacy bulk import")
+- SELF-SERVICE accounts (ADR 0196) hold sign-up and reset to the same policy. They are
+  opt-in and never discovered: after configure_mail(...), build the module and mount it
+      build_accounts_module(SelfService(reason="members open their own accounts",
+          users=users_service, throttle_store=shared_store,
+          link_base="https://app.example.com"))
+  for POST /api/v1/accounts/sign-up, /verify, /password-reset, /password-reset/confirm
+  and /me/close. Sign-up takes only the address: the account opens when the mailed token
+  is redeemed at /verify with the password, so whoever asked cannot choose it. Every
+  request about an address answers 202 the same way and sends that address exactly one
+  message, whether or not it has an account, and addresses compare case-insensitively.
+  Tokens are sealed, expire, work once, and ride the URL fragment, so your account pages
+  read them from location.hash and post them. Closing needs the password again and ends
+  every session (AccountDeletion.SCRUB by default, or REMOVE: building the module refuses
+  it while a reference to the user table would refuse the delete, so declare CASCADE or
+  SET NULL on that reference; one the build cannot see is scrubbed instead, with a warning).
 - No terp.arch check applies (no module code shape to police) — enforcement is the
   service chokepoint plus the create_app production fail-fast.
 """,
@@ -1716,11 +1811,35 @@ File objects (files capability, ADR 0056/0057)
   objects) in a NAMED-PROFILE registry;
   metadata (name, type, size, sha256, storage_key, storage_profile) lives in the platform
   DB. storage_key/storage_profile never leave the boundary (FileRead omits both).
-- Any provider is an adapter subclass (local ships; S3/Azure/NAS are each a
-  StorageBackend). Register each store once at the composition root:
-      register_storage_backend("azure-invoices", AzureBlobStorage(container="invoices"))
-      register_storage_backend("azure-hr", AzureBlobStorage(container="hr"))
-  Keep credentials in settings / sealed config — never in module code.
+- Any provider is an adapter subclass (local ships; a NAS mount is the local adapter on
+  another root). Two object-store adapters ship behind extras (ADR 0201): S3Storage
+  (terp-cap-files[s3]) takes the SDK's own client and a bucket; AzureBlobStorage
+  (terp-cap-files[azure]) takes the SDK's ContainerClient and, for user-delegation SAS
+  links, a BlobServiceClient under an Entra credential. Register each store once at the
+  composition root:
+      register_storage_backend("s3-media", S3Storage(boto3.client("s3"), bucket="app-media"))
+      register_storage_backend("azure-invoices", AzureBlobStorage(invoices_container))
+      register_storage_backend("azure-hr", AzureBlobStorage(hr_container, delegation=service))
+  Keep credentials in settings / sealed config — never in module code. Building the Azure
+  adapter without its extra fails at boot with the install line (StorageSdkMissingError);
+  the S3 adapter takes the SDK's client, so a missing extra fails where that is built.
+- A client that cannot send a bearer (an <audio>/<video> element, a PDF viewer, a native
+  client's media stack) gets a short-lived LINK to one file's bytes instead (ADR 0201):
+      GET /api/v1/files/{id}/link?ttl_seconds=600&inline=true   ->  {url, expires_at}
+  The link is minted where a download is authorized (row scope, then quarantine), by the
+  store the ROW names: an S3 presigned GET or an Azure SAS where the store can sign, else
+  an app-signed token the capability serves itself at GET /api/v1/files/link/{token} —
+  its one public route, rate-limited, answering 404 to an expired, altered or foreign
+  token. The default lifetime is an hour, the longest 24 hours; a link is not single-use
+  (a player makes many range requests), its expiry is the control. inline is honoured only
+  for a type a browser renders without running it (image, audio, video, PDF — not an XML
+  image such as SVG, which is a document with script in it). From a module, mint through
+  your own authorized row and a declared FileRef:
+      link = FileService().link_for(session, invoice, "attachment_file_id", ttl=timedelta(minutes=10))
+  Both content routes honour one bytes= Range (206 / 416); the local adapter seeks, an
+  object store's stream is read forward. A link from a store that signs never streams
+  through the API; the authenticated content route still serves any store's bytes to a
+  caller who asks it to.
 - Pick the store per module (subclass default) or per call — never from a client:
       class InvoiceFileService(FileService):
           storage_profile = "azure-invoices"
@@ -1924,6 +2043,11 @@ Sending e-mail (terp-cap-mail)
   dead-letters` lists it. With the
   in-process default queue (no worker) the mail is sent inline, and a failing relay
   fails the request that asked for it.
+- The queued message is SEALED at rest (ADR 0199): the outbox row's payload holds the
+  Message-ID and one value sealed under SECRET_KEY, never an address or the text. After a
+  key rotation keep SECRET_KEY_DECRYPT_FALLBACKS until `terp secrets reseal` reports
+  nothing left: a queued mail no configured key opens is never sent, and fails with
+  MailSealError, which names that remedy, until it dead-letters.
 - Test without a relay:
       from terp.capabilities.mail import (
           CapturingMailTransport, MailSettings, configure_mail, reset_mail)
@@ -2757,7 +2881,12 @@ FOUR STATES, EXACTLY ONE AT A TIME
   "build": "generated"            the framework renders Dockerfile.prod,
                                   frontend/Dockerfile.prod and docker-compose.prod.yml
                                   from this file (`terp deployment render`), and a
-                                  committed copy that is not the render is refused
+                                  committed copy that is not the render is refused.
+                                  frontend/Dockerfile.prod only beside a web unit: an api
+                                  unit with no web unit in front of it is the deployment's
+                                  only way in and publishes ${API_PORT:-23200}:8000 (ADR
+                                  0202) -- the shape an app rendered API-only (the
+                                  template's `frontend: false`) has from the start
   {"unmanaged": true, "reason"}   no tool can drive this deploy; the checks are off and
                                   a tool shows the reason. Nothing may stand beside it.
 
@@ -2854,7 +2983,8 @@ or an override; externalDatabase beside a database unit; a database or store wit
 or two of a kind; a one-shot that declares `terp migrate upgrade` (drop the command: the
 one-shot without one is the migration step) or a second step; a role with no command of
 its own and none declared; a web unit with a command, with no single api to proxy to, or
-without frontend/package-lock.json; an api without both health paths; a start-order cycle
+without frontend/package-lock.json; two or more api units with no web unit in front of
+them (which one callers reach would be a guess); an api without both health paths; a start-order cycle
 or a unit it names that is not declared; a volume without its mount, mounted anywhere but
 var/files, on a unit not on the backend image, or on a unit that already mounts another
 volume there (Compose would mount only the last of them, without a word); any system
@@ -3000,14 +3130,20 @@ build container holds a credential or writes into what is built. Each takes the
     <registry>/<image>:<tag> with the credential your docker configuration holds for this
     release. It writes terp-release-build.json: BuildKit's own digests.
   uv run terp release gate --sha <sha> --build terp-release-build.json
-    runs in a clean checkout of the commit: `terp verify --profile release --format
-    assurance` with npm's scripts off, then the schedule catalog, read by running the pushed
-    image sealed (no network, read-only, its own non-root user). It holds no push credential
-    and no key. It writes terp-release-gate.json.
+    runs in a clean checkout of the commit: `terp verify --profile release` once, with npm's
+    scripts off, recording every check's verdict and the release-assurance claim those same
+    results compose (no check's output), then the schedule catalog, read by running the
+    pushed image sealed (no network, read-only, its own non-root user). It holds no push
+    credential and no key. It writes terp-release-gate.json, and exits 1 unless every check
+    passed and the claim holds, naming each red check. Run it from the commit's own
+    environment: sign reads the document only in the version the commit's pinned terp-cli
+    writes (ADR 0200).
   terp release sign --sha <sha> --tag <tag> --registry ... --build ... --gate ... \\
       --hosts separated --signer '["your-kms-signer", "--key", "release"]' --public-key k.pub
     runs from the signer image, never the commit's own toolchain, and runs nothing of the
-    app: it repeats the refusals, renders a generated app's files with the terp-arch the
+    app: it repeats the refusals, refuses a gate with a red check or a claim that does not
+    hold (ADR 0200; a commit pinning terp-cli below 0.36.1 has a gate that records the claim
+    alone, and is held to it), renders a generated app's files with the terp-arch the
     commit pins (fetched by hash, run in a process of its own), reads the backend image from
     the registry as data and holds it to the tree and the lock, scans for known
     vulnerabilities and for secrets in the history, and signs the manifest as a DSSE envelope
@@ -5182,7 +5318,7 @@ def main(argv: Sequence[str] | None = None) -> None:
             emit(f"wrote {path}")
         return
     if args.command == "openapi":
-        emit(f"wrote {export_openapi(args.app, out=args.out, app_root=args.app_root)}")
+        emit(run_openapi_command(args.app, out=args.out, app_root=args.app_root))
         return
     if args.command == "routes":
         emit(