terp-cli 0.28.0__tar.gz → 0.30.0__tar.gz

{terp_cli-0.28.0 → terp_cli-0.30.0}/PKG-INFO

@@ -1,19 +1,19 @@
 Metadata-Version: 2.5
 Name: terp-cli
-Version: 0.28.0
+Version: 0.30.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.28.0
-Requires-Dist: terp-core==0.28.0
-Requires-Dist: terp-migrations==0.28.0
+Requires-Dist: terp-arch==0.30.0
+Requires-Dist: terp-core==0.30.0
+Requires-Dist: terp-migrations==0.30.0
 Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.28.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.28.0; extra == 'jobs'
+Requires-Dist: terp-cap-outbox==0.30.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.30.0; extra == 'jobs'
 Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.28.0; extra == 'scheduler'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.30.0; extra == 'scheduler'
 Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.28.0; extra == 'worker'
+Requires-Dist: terp-cap-outbox==0.30.0; extra == 'worker'

{terp_cli-0.28.0 → terp_cli-0.30.0}/pyproject.toml

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.28.0"
+version = "0.30.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.28.0",
+    "terp-core==0.30.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.28.0",
+    "terp-migrations==0.30.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.28.0",
+    "terp-arch==0.30.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.28.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.28.0"]
+worker = ["terp-cap-outbox==0.30.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.30.0"]
 jobs = [
-    "terp-cap-outbox==0.28.0",
-    "terp-cap-scheduler-apscheduler==0.28.0",
+    "terp-cap-outbox==0.30.0",
+    "terp-cap-scheduler-apscheduler==0.30.0",
 ]
 
 [project.scripts]

{terp_cli-0.28.0 → terp_cli-0.30.0}/src/terp/cli/__init__.py

@@ -106,6 +106,10 @@ Add a module (the "10-minute module")
      @router.post("/", response_model=InvoiceRead, status_code=201)
      def create_invoice(payload: InvoiceCreate, session: SessionDep) -> InvoiceRead:
          return InvoiceRead.model_validate(_service.create(session, payload))
+   Register every route with a route decorator or add_api_route. A plain Starlette route
+   (router.add_route), a Starlette WebSocket route or a Mount is served without the
+   router's dependencies, so the deny-by-default guard never runs for it, and the boot
+   refuses one. A route anyone may call declares route_policy(Policy.public(reason=...)).
 
 5) module.py   the manifest
      module = ModuleSpec(name="invoices", router=router, policy=Policy.default())
@@ -434,6 +438,12 @@ Authorization (Policy)
   or boot fails closed. Grant via the access capability; the caller must clear the
   min_role floor AND hold the grant.
 - Route-level extra check: dependencies=[Depends(require_permission(APPROVE))].
+- A module that only READS says so, and the boot holds every route to it:
+      ModuleSpec(name="reports", router=router, policy=Policy.default(), read_only=True)
+  A route that answers POST / PUT / PATCH / DELETE, or a WebSocket, then refuses the
+  boot, on an included sub-router too, unless it is declared @read_only (it computes an
+  answer and persists nothing). Undeclared, the module is read-only only until someone
+  adds a write route. It is not a Policy: route_policy(...) cannot reopen it.
 - Authority is always a typed object (Role / Permission), never a bare string — pass the
   declared constant, not its name. no_adhoc_permission_literals refuses the literal.
 - Choosing between a role and a permission, and the grant lifecycle: `terp guide permissions`.
@@ -748,6 +758,7 @@ Rows that cannot change, and rows that cannot go (append_only)
 - The neighbouring guarantees, so you pick the right one:
       append_only          the ROW cannot change after insert
       @read_only           the ROUTE writes nothing, though its verb is unsafe
+      ModuleSpec(read_only=True)  no ROUTE in the module writes (see: policy)
       SoftDeleteMixin      the row survives its own delete (see: soft-delete)
       OnDelete.RESTRICT    another row cannot be deleted while this one points at it
       BaseUpdateSchema     a concurrent writer cannot lose your edit (OCC, 409)
@@ -1216,6 +1227,13 @@ RESTORES it after. No conftest.py line, no opt-in. Without it a suite goes
 order-dependent: green together, red alone - the sharpest failure mode there is,
 because the green is the wrong answer.
 
+SIGNING TOKENS NEEDS NO KEY OF YOUR OWN. The same plugin's `terp_signing_key` fixture
+(autouse, once per session) replaces the development SECRET_KEY with a random 64-character
+one while the default is in place, and puts the default back afterwards. So a test that
+calls create_access_token signs with a strong key and pyjwt does not warn. Never write a
+key into a test file: it is a credential-shaped literal the secret scan flags. A key the
+environment sets, or one a test sets with monkeypatch, is left as it is.
+
 THE SIX SEAMS. create_app installs six process globals per app; in a test process they
 outlive the app that installed them. Restored automatically -- but installed by you:
 
@@ -1513,6 +1531,14 @@ Using capabilities
   BASE PROFILE — auth, identity, users, groups, access, audit — so authentication,
   accounts, group membership, permission checks and the audit trail are wired before you
   write anything. Install the others you need.
+- WHO IS CALLING, in words a person reads: take `caller: CallerDep` on the route.
+      from terp.capabilities.identity import CallerDep
+      def pause(name: str, caller: CallerDep, session: SessionDep) -> None:
+          service.pause(session, name, decided_by=caller.name)
+  `caller.name` is a user's email or a service account's name, read from the live row;
+  `caller.id` is the key to store when a record must point at who did it. Never take a
+  "decided by" from the request body (it is whatever the client says), and never build
+  an IdentityService inside a module to look the caller up.
 - SEE WHAT EXISTS BEFORE YOU BUILD IT:
       terp inspect capabilities
   lists every maintained capability, whether this app already has it, the exact
@@ -1535,7 +1561,7 @@ Using capabilities
                  permission_enforcer=enforce_permission, discover_capabilities=True)
 - You can always drop to native FastAPI/SQLModel — the same gate rules still apply.
 - Outbound HTTP is a capability concern, never a module concern: importing httpx /
-  requests / urllib.request / urllib3 / aiohttp in a module is refused by the
+  httpx2 / requests / urllib.request / urllib3 / aiohttp in a module is refused by the
   no_raw_outbound_http rule — SSRF protection, egress allowlists and timeout policy
   belong behind one declared capability, not scattered per call site. That capability
   is `terp-cap-egress`, and it is a declaration rather than a client you configure at