terp-cli 0.3.0__tar.gz → 0.5.0__tar.gz

terp_cli-0.5.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: terp-cli
+Version: 0.5.0
+Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
+License-Expression: Apache-2.0
+Requires-Python: >=3.13
+Requires-Dist: terp-arch==0.5.0
+Requires-Dist: terp-core==0.5.0
+Requires-Dist: terp-migrations==0.5.0
+Provides-Extra: jobs
+Requires-Dist: terp-cap-outbox==0.5.0; extra == 'jobs'
+Requires-Dist: terp-cap-scheduler-apscheduler==0.5.0; extra == 'jobs'
+Provides-Extra: scheduler
+Requires-Dist: terp-cap-scheduler-apscheduler==0.5.0; extra == 'scheduler'
+Provides-Extra: worker
+Requires-Dist: terp-cap-outbox==0.5.0; extra == 'worker'

{terp_cli-0.3.0 → terp_cli-0.5.0}/pyproject.toml

@@ -4,29 +4,29 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs."
 requires-python = ">=3.13"
 license = "Apache-2.0"
 dependencies = [
-    "terp-core==0.3.0",
+    "terp-core==0.5.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.3.0",
+    "terp-migrations==0.5.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.3.0",
+    "terp-arch==0.5.0",
 ]
 
 # Job-process adapters stay optional: the base CLI must not install the table-owning outbox
 # 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.3.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.3.0"]
+worker = ["terp-cap-outbox==0.5.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.5.0"]
 jobs = [
-    "terp-cap-outbox==0.3.0",
-    "terp-cap-scheduler-apscheduler==0.3.0",
+    "terp-cap-outbox==0.5.0",
+    "terp-cap-scheduler-apscheduler==0.5.0",
 ]
 
 [project.scripts]

{terp_cli-0.3.0 → terp_cli-0.5.0}/src/terp/cli/__init__.py

@@ -18,6 +18,7 @@ from terp.cli.access import (
     render_access_graph,
 )
 from terp.cli.apidocs import api_docs
+from terp.cli.capabilities import render_capabilities
 from terp.cli.dev import dev_plan, run_dev_command
 from terp.cli.docker import run_docker_dev_command
 from terp.cli.jobs import (
@@ -36,6 +37,12 @@ from terp.cli.schema import (
     scan_declared_table_models,
 )
 from terp.cli.seed import run_seed_command
+from terp.cli.grants import (
+    grant_add_command,
+    grant_list_command,
+    grant_revoke_command,
+)
+from terp.cli.service_accounts import create_service_account_command
 from terp.cli.users import create_user_command
 from terp.cli.verify import profile_ids, run_verify_command, verify_manifest
 
@@ -74,6 +81,49 @@ Add a module (the "10-minute module")
      module = ModuleSpec(name="invoices", router=router, policy=Policy.default())
 
 Then run `terp check`. Policy.default() = authenticated; read VIEWER, write EDITOR.
+""",
+    "dependencies": """\
+One module needs another (declared edges)
+
+Modules are independent by default: an import of a sibling is refused. When a real
+dependency exists, DECLARE it — do not hand-roll dependency inversion.
+
+1) Name the sibling in the DEPENDING module's manifest:
+     # app/modules/catalogs/module.py
+     module = ModuleSpec(
+         name="catalogs",
+         router=router,
+         policy=Policy.default(),
+         requires=("connections",),   # <- the edge, in the manifest a reader consults
+     )
+
+2) Now import its published surface:
+     from app.modules.connections.service import ConnectionProfileService
+
+Three limits, each enforced:
+
+- DECLARED. An undeclared sibling import fails `no_cross_module_imports`. The point
+  is not to make coupling hard, it is to make coupling VISIBLE.
+- PUBLIC SURFACE ONLY. An edge grants models / schemas / service / events. Never the
+  dependency's router (that couples two modules through HTTP shapes and lets an
+  in-process call walk past the policy guarding those routes) and never an
+  underscore-prefixed internal. Import a named surface, not the bare package.
+- ONE-WAY. The declared graph must be acyclic — `terp check` reports the cycle and
+  the app refuses to boot on one. A cycle means the two modules are really one.
+
+When NOT to declare an edge:
+
+- You only need to REACT to the other module -> subscribe to its event
+  (`terp guide events`). An event keeps the direction one-way and the coupling loose.
+- BOTH directions want an edge -> the shared concept belongs in a third module that
+  both depend on. Inverting one direction by hand (a Protocol plus a global registry
+  plus a composition-root adapter) is the same coupling with more moving parts and
+  module-global mutable state; declare the edge or extract the concept.
+- The dependency is a capability (audit, files, users) -> that is not a module edge.
+  `requires=("audit",)` still means "must be installed"; capabilities are importable
+  by every module already.
+
+Check it: `terp check`  |  See the declared edges: `terp inspect control-plane`
 """,
     "service": """\
 Services (BaseService)
@@ -86,12 +136,21 @@ Services (BaseService)
   conditions and CANNOT drop soft-delete / tenant scope:
       def business_filters(self):
           return (Invoice.status == "open",)
-- A per-call filter goes in a custom list() built on base_query():
-      def list(self, session, *, skip, limit, status=None):
-          q = self.base_query()
-          if status is not None:
-              q = q.where(Invoice.status == status)
-          return self._paginate(session, q, skip=skip, limit=limit)
+- A per-call filter/sort (a query parameter) is DECLARED, not hand-written. Name the
+  allowed columns on the service and pass the values through — an undeclared field is
+  refused (400), and the caller sends values, never operators:
+      class InvoiceService(BaseService[Invoice, InvoiceCreate, InvoiceUpdate]):
+          model = Invoice
+          filterable = (FilterField("status", Invoice.status),
+                        FilterField("q", Invoice.title, op="contains"))
+          sortable = (SortField("due_on", Invoice.due_on),)
+          default_sort = ("-due_on",)
+      # route: status: str | None = None  ->  typed, and it shows up in OpenAPI
+      rows, total = service.list(session, skip=..., limit=..., filters={"status": status},
+                                 sort=sort)
+  None values are dropped, so an absent optional parameter needs no branching. Filters
+  compose ON TOP of base_query(), so row scope and business_filters() still apply —
+  they cannot widen a read. Don't write a list() override to do this by hand.
 - On a large table, prefer keyset pagination: a route takes CursorPaginationDep and
   returns CursorPage[ReadDTO] from self.list_by_cursor(session, pagination=...) —
   no OFFSET scan, and the exact COUNT runs only when the caller asks
@@ -128,6 +187,56 @@ Authorization (Policy)
   min_role floor AND hold the grant.
 - Route-level extra check: dependencies=[Depends(require_permission("invoices.approve"))].
 - Authority is always a typed object (Role / Permission), never a bare string.
+- Choosing between a role and a permission, and the grant lifecycle: `terp guide permissions`.
+""",
+    "permissions": """\
+Permissions — when to add one, and how it reaches a subject
+
+WHEN A PERMISSION IS THE RIGHT ANSWER
+- The role ladder answers "how much of this app may you touch?" - VIEWER < EDITOR
+  < ADMIN, coarse and comparable. A permission answers "may you do this ONE thing?"
+  and is not comparable to anything.
+- Add a permission when the authority is NARROWER than a role and does not belong
+  on the ladder: an integration that may export invoices but must not edit them; a
+  finance user who may approve but is not an app admin.
+- Do NOT add a permission for something every EDITOR should be able to do - that is
+  the role, and a permission held by everyone is a checkbox nobody reads.
+- Do NOT model a role as three permissions. The ladder exists so authority stays
+  comparable; a bag of permissions cannot answer "is this account privileged?".
+
+DECLARE IT
+      from terp.core import EDITOR, Permission
+      APPROVE = Permission("invoices.approve", min_role=EDITOR)
+  min_role is a FLOOR, not a shortcut: the caller must clear it AND hold the grant.
+  Both checks are real - the floor stops a grant from smuggling authority to a
+  subject the app never intended to trust that far.
+- Enforce it on the module (Policy(write=APPROVE)) or on one route
+  (dependencies=[Depends(require_permission("invoices.approve"))]).
+- Wire the enforcer once, or the app refuses to boot (fail closed - a Permission
+  requirement with nothing to enforce it would silently pass):
+      create_app(..., permission_enforcer=terp.capabilities.access.enforce_permission)
+
+GRANT IT
+      terp grant add ops@acme.test invoices.approve
+      terp grant add nightly-sync invoices.export     # a service account, by name
+      terp grant list ops@acme.test                   # "why can it do that?"
+      terp grant revoke ops@acme.test invoices.approve
+  A subject is named the way you name it - a user email, a service-account name, or
+  a subject UUID. An unknown permission is refused WITH the app's catalog printed,
+  because a grant of a string the app never checks is a silent no-op, not a lenient
+  grant. Grants are stored per subject id with no foreign key, which is what lets a
+  user, a service account and a group all be granted the same way; a group grant
+  reaches every member (`terp guide access`).
+- Mind the floor: granting a permission to a subject BELOW its min_role stores a row
+  that the rank check will shadow. `terp grant add` warns when it sees this.
+- See the whole declared catalog and every module's policy:
+      terp inspect control-plane --app app.main:build
+
+THE FAILURE MODE THIS EXISTS TO PREVENT
+  An integration needs one narrow capability, granting looks like work, so someone
+  makes it an admin "for now". Least privilege loses to a ten-second workaround. If
+  you catch yourself widening a role to unblock one call, that call wants a
+  permission - and the grant is one command (ADR 0089).
 """,
     "access": """\
 The access model (three layers) — profiles + the access graph
@@ -160,6 +269,8 @@ The access model (three layers) — profiles + the access graph
   write authority, and warnings (e.g. OwnedMixin gates writes only). `--format json`
   is the stable Studio contract; declare services=(InvoiceService,) on the ModuleSpec
   so the data layer is visualizable — an undeclared data layer is a warning.
+- Narrowing authority below a role, and getting a permission to a subject:
+  `terp guide permissions` (declare it, enforce it, `terp grant add`).
 """,
     "ownership": """\
 Object-level (per-row) authorization (OwnedMixin)
@@ -279,6 +390,103 @@ Background jobs (terp.core.enqueue + JobCatalog)
   against the JobCatalog. Run schedules in-process with `terp jobs scheduler` (APScheduler;
   needs terp-cap-scheduler-apscheduler) or via Celery beat — each cron tick enqueues through
   the same typed seam, so a scheduled job stays audited + system-actor stamped.
+""",
+    "outbox": """\
+Durable post-commit delivery (outbox capability)
+
+- The problem it solves: an in-process dispatcher runs the side effect AFTER the commit,
+  outside the transaction - so a crash between the two loses it, and a rollback after it
+  already fired published a lie. The outbox writes the INTENT to a table in the SAME
+  transaction as the row, and a separate worker delivers it afterwards.
+- terp-cap-outbox is a LIBRARY capability: it ships no router and nothing auto-mounts.
+  You swap the two seams at the composition root:
+      create_app(specs, ..., job_queue=OutboxJobQueue(),
+                 event_dispatcher=outbox_event_dispatcher)
+  It ships its own migrations, so add the dependency and run `terp migrate` before
+  switching the seams over.
+- Nothing in a module changes. You still enqueue(session, job=..., payload=...) and
+  still emit events through the catalog; the seam is swapped once, centrally, so a
+  module never knows whether delivery is in-process or durable.
+- A custom side effect joins the same atomic unit through the service's _after_write
+  hook (which runs inside the write transaction, before the commit):
+      def _after_write(self, session, entity, *, action):
+          enqueue(session, job=RUN_START, payload=RunStartPayload(run_id=entity.id))
+- Run the relay as its own process (not inside the API container):
+      terp jobs worker
+  It leases rows (claim_id + locked_until, SKIP LOCKED), delivers AT LEAST ONCE, retries
+  with exponential backoff, and dead-letters once max_attempts is exhausted. Every
+  handler must therefore be safe to run twice - see `terp guide idempotency`.
+- In production, refuse to boot on the in-process default:
+      create_app(..., job_queue=OutboxJobQueue(),
+                 require_durable_jobs=get_settings().is_production)
+""",
+    "idempotency": """\
+Idempotency (the Idempotency-Key header, terp.core.idempotency)
+
+- Already wired: create_app installs the idempotency middleware for every unsafe method
+  (POST/PUT/PATCH/DELETE). There is nothing to decorate and no per-route opt-in - the
+  CLIENT opts in per request by sending a header:
+      Idempotency-Key: <client-generated unique key>
+  A request without the header behaves exactly as it did before.
+- The semantics, all typed envelopes:
+      first call                -> executes; the response is stored under the key
+      retry, same body          -> the stored response is replayed
+                                   (response header idempotency-replayed: true)
+      same key, different body  -> 422 idempotency_key_mismatch
+      still executing           -> 409 idempotency_in_flight   (Retry-After: 1)
+      malformed key             -> 400 invalid_idempotency_key
+      store unavailable         -> 503 idempotency_unavailable (fail closed - never a
+                                   second write)
+- Use it wherever a retry must not create a second row: starting a run, submitting a
+  payment, POSTing a snapshot from a worker that retries on a network error. Document
+  the header on those routes so the caller actually sends one.
+- The default InMemoryIdempotencyStore is PER PROCESS - correct for dev and a single
+  replica, useless across replicas. A multi-replica deployment needs a shared store, and
+  should refuse to boot without one:
+      create_app(..., idempotency_store=RedisIdempotencyStore(...),
+                 require_shared_idempotency_store=get_settings().is_production)
+  Only a store that marks itself shared (mark_shared_idempotency_store) satisfies the
+  guard, so a load-balanced deployment cannot silently lose the guarantee.
+- Background work carries its own key: enqueue(..., idempotency_key="customers-2026-06-29").
+  Job delivery is at-least-once, so a handler must ALSO be safe to run twice on its own -
+  a natural unique constraint in the database is the strongest form of that.
+""",
+    "realtime": """\
+Realtime push (realtime capability)
+
+- Install terp-cap-realtime; it is a routed capability, so discovery mounts it:
+      create_app(specs, discover_capabilities=True,
+                 capability_names=(..., "realtime"))
+- Declare every channel ONCE at import time, with a typed outbound model and the
+  authorization it demands - never a bare topic string:
+      class RunProgress(BaseModel):
+          run_id: uuid.UUID
+          state: str = Field(max_length=32)
+          done: int = Field(ge=0)
+      RUN_PROGRESS = register_channel(
+          RealtimeChannel("runs.progress", RunProgress, requirement=Roles.VIEWER))
+  RealtimeChannel(name, outbound_model, mode="sse"|"websocket", requirement=...,
+                  inbound_requirement=..., inbound_model=..., on_message=...,
+                  audience=principal_audience | global_audience). The default audience is
+  the principal, so a message reaches only the user you address it to.
+- Publish from a service, an _after_write hook, or a job handler; the payload is
+  validated against the channel's outbound_model:
+      await publish(RUN_PROGRESS, RunProgress(...), audience=str(principal.id))
+- Wire the runtime seams once at the composition root:
+      configure_realtime(permission_enforcer=..., principal_validator=...,
+                         message_session_provider=...)
+  configure_broker / configure_ticket_store replace the in-memory defaults when you run
+  more than one replica (the in-memory ones are per process).
+- Transport is TICKET-based, never a token in a URL: the client POSTs
+  /api/v1/realtime/tickets, receives a one-use short-lived ticket, then connects to
+  /api/v1/realtime/sse/<channel>?ticket=... (or /ws/<channel> in websocket mode). The
+  channel's requirement is enforced when the ticket is minted.
+- Frontend: useRealtimeChannel({ channel: "runs.progress", validate }) from
+  @terpjs/react-core performs the whole dance. Never hand-roll EventSource or WebSocket -
+  the boundary lint refuses both.
+- Inbound (websocket) messages are size-capped, validated against inbound_model, gated by
+  inbound_requirement, and handled by on_message with a real session - so a client message
+  goes through the same audited service path as an HTTP write.
 """,
     "files": """\
 File objects (files capability, ADR 0056/0057)
@@ -325,6 +533,12 @@ Using capabilities
 
 - Capabilities are opt-in packages (terp-cap-*); the base profile is auth + access +
   identity + users (+ projects). Install the ones you need.
+- SEE WHAT EXISTS BEFORE YOU BUILD IT:
+      terp inspect capabilities
+  lists every maintained capability, whether this app already has it, the exact
+  `uv add` line and the composition-root wiring it expects. Durable delivery, realtime
+  push, tenancy, files, webhooks, scheduling and shared multi-replica state are all
+  already solved — hand-rolling one of them is a defect, not a shortcut.
 - A routed capability self-registers: create_app(specs, discover_capabilities=True)
   mounts it at /api/v1/<name> via its entry point — no composition-root edit.
 - A library capability (tenancy, eventbus) ships no router; you import and wire it
@@ -372,6 +586,29 @@ Database migrations (terp migrate)
 - Destructive DDL (drop table/column or alter-column type changes) is refused by
   `terp check` unless the operation carries `# arch-allow-no-destructive-migrations:
   <reason>` on (or immediately above) its line, budgeted by the escape-hatch ratchet.
+- MOVING A MODEL TO ANOTHER MODULE is the one edit that looks free and is not. Just
+  moving the class emits NO ddl at all - the losing package stops owning the table so
+  its scoped autogenerate cannot propose a drop, and the gaining package diffs against
+  a database where the table already exists so it proposes no create. Your database
+  keeps upgrading; CI and staging stay green. Then the NEXT ordinary change to that
+  model (an added column) is authored into the gaining package's INDEPENDENT history,
+  which - with no foreign key between the two packages - a fresh install may run
+  BEFORE the history that creates the table: "no such table", months later, in a new
+  environment, blamed on an innocent add_column. Terp refuses the split at `terp
+  migrate make` and in the build-time guard. Move a table properly, expand/contract:
+      1. Give the new module its own model with its own __tablename__;
+         `terp migrate make <new>` creates it.
+      2. Copy the rows in that same release (a data migration, or a backfill job),
+         and write to both tables while the old one still has readers.
+      3. In a LATER release, once nothing reads the old table, drop it - with
+         `# arch-allow-no-destructive-migrations: <reason>` and a human reviewer.
+  Step 3 stays human-reviewed on purpose: dropping a populated table is a genuine,
+  irreversible risk, and the one place where a second pair of eyes is worth the
+  friction. If the model is simply in the wrong module and holds no data you care
+  about, the cheap fix is to move the class BACK and rename the module instead.
+  Already shipped the move and planning the expand/contract for a later release? The
+  owning package's models.py may carry `# arch-allow-table-ownership-is-not-split:
+  <reason>`, counted by the escape-hatch budget like any other opt-out.
 - Adopt Terp on an EXISTING database (built by create_all or by hand) without dropping
   data - baseline each history at head, then only genuinely new migrations apply:
       terp migrate stamp                   # records head, runs no DDL
@@ -594,6 +831,7 @@ Golden rules (the gate enforces these — follow them and it stays green):
 More:  terp guide <topic>   (topics: {_TOPIC_NAMES})
     terp guide <rule>            (the exact rule's remediation and related pattern)
        terp guide rules             (every architecture rule the gate enforces, generated)
+       terp inspect capabilities    (what the platform offers: installed vs adoptable)
        terp inspect control-plane   (your roles / permissions / module authority map)
        terp inspect access          (the full access graph: modules, endpoints, data traits)
        terp check                   (run the full architecture gate locally)
@@ -683,6 +921,25 @@ def guide(topic: str | None = None) -> str:
     return _render_rule_guide(topic)
 
 
+def gate_root(root: str | pathlib.Path = ".", *, package: str = "app") -> pathlib.Path:
+    """Resolve the directory the architecture gate scans, from a CLI ``--root``.
+
+    The gate's unit of scope is the **app package** — the test harness calls
+    ``assert_app_clean("app")``, so ``app/`` is what the rules walk. A CLI ``--root``,
+    though, is naturally the *project* root (that is where every other ``terp``
+    command runs, and the default is ``.``), which also contains code the gate does
+    not govern: a standalone ``engine/``, ``conformance/``, tooling scripts. Scanning
+    that made the two entry points to the same gate disagree about scope.
+
+    So ``--root`` accepts either: if it contains the app package, the package dir is
+    the scan root; otherwise *root* is already the package dir and is used as-is.
+    Both spellings then hold the app to exactly the scope ``uv run pytest`` does.
+    """
+    path = pathlib.Path(root)
+    candidate = path / package
+    return candidate if candidate.is_dir() else path
+
+
 def check_report(
     root: str = ".", *, package: str = "app", budget_path: str | None = None
 ) -> dict[str, object]:
@@ -706,9 +963,10 @@ def check_report(
     from terp.arch import check_app, guide_topic_for, ungoverned_marker_violations
     from terp.arch.rules import GUIDE_TOPIC_BY_RULE
 
-    violations = list(check_app(root, package=package, budget_path=budget_path))
+    scan_root = gate_root(root, package=package)
+    violations = list(check_app(scan_root, package=package, budget_path=budget_path))
     if budget_path is None:
-        violations.extend(ungoverned_marker_violations(root, package=package))
+        violations.extend(ungoverned_marker_violations(scan_root, package=package))
     violations.sort(key=lambda violation: (violation.path, violation.line, violation.rule))
     rules = set(GUIDE_TOPIC_BY_RULE)
     if budget_path is None:
@@ -976,6 +1234,7 @@ def _module_json(spec: ModuleSpec) -> dict[str, object]:
     return {
         "name": spec.name,
         "policy": policy,
+        "requires": list(spec.requires),
         "emits": [event.name for event in spec.emits],
         "subscribes": [event.name for event in spec.subscribes],
         "jobs": [job.name for job in spec.jobs],
@@ -998,6 +1257,8 @@ def _render_text(plane: ControlPlane, specs: Sequence[ModuleSpec]) -> str:
         lines.append("  <none provided>")
     for spec in sorted(specs, key=lambda item: item.name):
         lines.append(f"  {spec.name}  {_policy_label(spec)}")
+        if spec.requires:
+            lines.append(f"    requires: {', '.join(sorted(spec.requires))}")
     lines.append("")
     lines.append("Audit")
     if plane.audit.enabled:
@@ -1166,6 +1427,17 @@ def _build_parser() -> argparse.ArgumentParser:
         default="text",
         help="Output format: text (human) or json (structured, for Studio; default: text)",
     )
+    capabilities_parser = inspect_subcommands.add_parser(
+        "capabilities",
+        help="Every maintained terp-cap-* package: installed here vs available to "
+        "adopt, with the `uv add` line and its composition-root wiring",
+    )
+    capabilities_parser.add_argument(
+        "--format",
+        choices=("text", "json"),
+        default="text",
+        help="Output format: text (human) or json (structured, for Studio; default: text)",
+    )
     schema_parser = inspect_subcommands.add_parser(
         "schema",
         help="The schema graph: every table with ownership, traits, and fail-visible "
@@ -1349,7 +1621,12 @@ def _build_parser() -> argparse.ArgumentParser:
     )
 
     check_parser = subcommands.add_parser("check", help="Run the architecture gate locally")
-    check_parser.add_argument("--root", default=".", help="App root (default: .)")
+    check_parser.add_argument(
+        "--root",
+        default=".",
+        help="Project root, or the app package itself; the gate scans the app package "
+        "(default: .)",
+    )
     check_parser.add_argument("--package", default="app", help="App package (default: app)")
     check_parser.add_argument(
         "--budget", default=None, help="Escape-hatch budget JSON (governs # arch-allow markers)"
@@ -1423,6 +1700,78 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Env var holding the new password; prompts if unset (default: TERP_USER_PASSWORD)",
     )
 
+    sa_parser = subcommands.add_parser(
+        "service-account",
+        help="Manage machine credentials (so an integration never needs a person's login)",
+    )
+    sa_subcommands = sa_parser.add_subparsers(dest="service_account_command", required=True)
+    sa_create_parser = sa_subcommands.add_parser(
+        "create", help="Provision a service account and print its credentials once"
+    )
+    sa_create_parser.add_argument("name", help="Human-readable name of the integration")
+    sa_create_parser.add_argument(
+        "--role",
+        required=True,
+        help="viewer / editor / admin or an integer rank (required: an integration's "
+        "authority is chosen, never inherited)",
+    )
+    sa_create_parser.add_argument(
+        "--description", default=None, help="What this credential is for, and who owns it"
+    )
+    sa_create_parser.add_argument(
+        "--expires-in-days",
+        type=int,
+        default=365,
+        help="Days until the credential lapses; 0 means never (default: 365)",
+    )
+    sa_create_parser.add_argument(
+        "--app",
+        default="app.main:app",
+        help="Dotted module:attribute of the FastAPI app (default: app.main:app)",
+    )
+    sa_create_parser.add_argument(
+        "--app-root", default=".", help="App root placed first on sys.path (default: .)"
+    )
+
+    grant_parser = subcommands.add_parser(
+        "grant",
+        help="Assign, list and revoke a subject's permission grants (least privilege "
+        "without hand-writing an admin API call)",
+    )
+    grant_subcommands = grant_parser.add_subparsers(dest="grant_command", required=True)
+
+    _SUBJECT_HELP = (
+        "A user email, a service-account name, or a subject UUID"
+    )
+    for _name, _help in (
+        ("add", "Grant a permission to a subject (idempotent, audited)"),
+        ("revoke", "Revoke a permission from a subject"),
+    ):
+        _p = grant_subcommands.add_parser(_name, help=_help)
+        _p.add_argument("subject", help=_SUBJECT_HELP)
+        _p.add_argument("permission", help="The permission name the app declares")
+        _p.add_argument(
+            "--app",
+            default="app.main:app",
+            help="Dotted module:attribute of the FastAPI app (default: app.main:app)",
+        )
+        _p.add_argument(
+            "--app-root", default=".", help="App root placed first on sys.path (default: .)"
+        )
+
+    grant_list_parser = grant_subcommands.add_parser(
+        "list", help="List every permission a subject holds, including via groups"
+    )
+    grant_list_parser.add_argument("subject", help=_SUBJECT_HELP)
+    grant_list_parser.add_argument(
+        "--app",
+        default="app.main:app",
+        help="Dotted module:attribute of the FastAPI app (default: app.main:app)",
+    )
+    grant_list_parser.add_argument(
+        "--app-root", default=".", help="App root placed first on sys.path (default: .)"
+    )
+
     seed_parser = subcommands.add_parser(
         "seed", help="Run the app's seed routine (idempotent demo / bootstrap data; dev only)"
     )
@@ -1485,6 +1834,9 @@ def main(argv: Sequence[str] | None = None) -> None:
     if args.command == "inspect" and args.inspect_command == "schema":
         print(inspect_schema(app_root=args.app_root, package=args.package, fmt=args.format))
         return
+    if args.command == "inspect" and args.inspect_command == "capabilities":
+        print(render_capabilities(fmt=args.format))
+        return
     if args.command == "guide":
         if args.topic is not None and args.topic not in guide_choices():
             raise SystemExit(
@@ -1569,7 +1921,11 @@ def main(argv: Sequence[str] | None = None) -> None:
             return
         from terp.arch import assert_app_clean
 
-        assert_app_clean(args.root, package=args.package, budget_path=args.budget)
+        assert_app_clean(
+            gate_root(args.root, package=args.package),
+            package=args.package,
+            budget_path=args.budget,
+        )
         print("terp.arch: app is clean")
         return
     if args.command == "verify":
@@ -1593,6 +1949,39 @@ def main(argv: Sequence[str] | None = None) -> None:
             )
         )
         return
+    if args.command == "service-account" and args.service_account_command == "create":
+        print(
+            create_service_account_command(
+                args.name,
+                role=args.role,
+                description=args.description,
+                expires_in_days=args.expires_in_days or None,
+                app_ref=args.app,
+                app_root=args.app_root,
+            )
+        )
+        return
+    if args.command == "grant":
+        _commands = {
+            "add": grant_add_command,
+            "revoke": grant_revoke_command,
+        }
+        if args.grant_command == "list":
+            print(
+                grant_list_command(
+                    args.subject, app_ref=args.app, app_root=args.app_root
+                )
+            )
+            return
+        print(
+            _commands[args.grant_command](
+                args.subject,
+                args.permission,
+                app_ref=args.app,
+                app_root=args.app_root,
+            )
+        )
+        return
     if args.command == "seed":
         print(run_seed_command(app_ref=args.app, app_root=args.app_root, seed_ref=args.seed))
         return
@@ -1610,9 +1999,14 @@ __all__ = [
     "api_docs",
     "check_report",
     "check_report_envelope",
+    "create_service_account_command",
     "create_user_command",
+    "grant_add_command",
+    "grant_list_command",
+    "grant_revoke_command",
     "dev_plan",
     "export_openapi",
+    "gate_root",
     "guide",
     "guide_topics",
     "guide_choices",

terp_cli-0.5.0/src/terp/cli/capabilities.py

@@ -0,0 +1,254 @@
+"""The adoptable-capability registry behind ``terp inspect capabilities``.
+
+The gate tells an author what they may **not** do; nothing told them what the platform
+already **offers**. An app that needs run progress hand-rolls polling, an app that needs
+durable delivery fires a post-commit callback and hopes — not because the author was
+careless, but because ``terp-cap-realtime`` and ``terp-cap-outbox`` were invisible from
+inside the project. Discoverability is a platform responsibility, so it ships as a
+command: one screen listing every capability, whether this app has it, the exact
+``uv add`` line, and the composition-root shape it expects.
+
+The registry is static (it must describe capabilities that are *not* installed), so it
+is pinned against the real packages by ``tests/architecture/test_cli_capabilities.py``:
+every capability directory appears here exactly once, and ``kind`` agrees with whether
+the package declares a ``terp.capabilities`` router entry point.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from importlib import metadata
+
+
+@dataclass(frozen=True)
+class Capability:
+    """One adoptable ``terp-cap-*`` package, as an author needs to see it."""
+
+    name: str
+    """Package suffix, e.g. ``realtime`` (dist ``terp-cap-realtime``)."""
+
+    summary: str
+    """One line: what it gives you, in problem terms."""
+
+    kind: str
+    """``routed`` (discovery mounts a router) or ``library`` (you wire it yourself)."""
+
+    wiring: str
+    """The composition-root shape, copy-pasteable."""
+
+    guide: str | None = None
+    """``terp guide`` topic covering it, when one exists."""
+
+    @property
+    def distribution(self) -> str:
+        """The PyPI distribution name."""
+        return "terp-cap-" + self.name.replace("_", "-")
+
+    @property
+    def module(self) -> str:
+        """The import path."""
+        return "terp.capabilities." + self.name
+
+
+CAPABILITIES: tuple[Capability, ...] = (
+    Capability(
+        name="access",
+        summary="RBAC permission grants + a fail-closed require_permission dependency.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True)",
+        guide="access",
+    ),
+    Capability(
+        name="audit",
+        summary="Durable append-only sink for the core audit seam (who changed what).",
+        kind="routed",
+        wiring="create_app(..., audit_sink=persist_audit)",
+    ),
+    Capability(
+        name="auth",
+        summary="Argon2 password hashing, JWT access tokens, the get_principal seam.",
+        kind="library",
+        wiring="mount the login router in app/auth.py",
+        guide="passwords",
+    ),
+    Capability(
+        name="eventbus",
+        summary="In-process dispatcher for the core event seam — react without coupling.",
+        kind="library",
+        wiring="create_app(..., event_dispatcher=dispatch_in_process)",
+        guide="events",
+    ),
+    Capability(
+        name="files",
+        summary="Owner-scoped file objects: metadata in the DB, bytes behind a storage port.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True)",
+        guide="files",
+    ),
+    Capability(
+        name="groups",
+        summary="Admin-managed user groups that bundle access-grant permissions.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True)",
+        guide="access",
+    ),
+    Capability(
+        name="identity",
+        summary="Persisted user store backing authentication.",
+        kind="library",
+        wiring="create_app(..., discover_capabilities=True)",
+    ),
+    Capability(
+        name="jobs_celery",
+        summary="Run catalog jobs on a Celery broker, with zero domain change.",
+        kind="library",
+        wiring="create_app(..., job_queue=CeleryJobQueue(...))",
+        guide="jobs",
+    ),
+    Capability(
+        name="oidc",
+        summary="Single sign-on via the OpenID Connect code flow with PKCE.",
+        kind="library",
+        wiring="build_oidc_module(...) in app/auth.py, mounted when OIDC_* is set",
+    ),
+    Capability(
+        name="outbox",
+        summary="Transactional, leased, retrying post-commit delivery for jobs and events.",
+        kind="library",
+        wiring=(
+            "create_app(..., job_queue=OutboxJobQueue(), "
+            "event_dispatcher=outbox_event_dispatcher)"
+        ),
+        guide="outbox",
+    ),
+    Capability(
+        name="realtime",
+        summary="Typed, policy-gated SSE/WebSocket channels with one-use connection tickets.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True) + configure_realtime(...)",
+        guide="realtime",
+    ),
+    Capability(
+        name="redis",
+        summary="Shared idempotency / throttling / cache state for multi-replica deploys.",
+        kind="library",
+        wiring="create_app(..., idempotency_store=RedisIdempotencyStore(...))",
+        guide="idempotency",
+    ),
+    Capability(
+        name="scheduler_apscheduler",
+        summary="Fire catalog schedules on their cron in-process, through the jobs seam.",
+        kind="library",
+        wiring="terp jobs scheduler",
+        guide="jobs",
+    ),
+    Capability(
+        name="scheduler_celery_beat",
+        summary="Drive catalog schedules from Celery beat, through the jobs seam.",
+        kind="library",
+        wiring="celery beat against the generated schedule",
+        guide="jobs",
+    ),
+    Capability(
+        name="sync",
+        summary="Reconcile a local entity against an external system on the jobs seam.",
+        kind="library",
+        wiring="declare a SyncSpec; run it through the jobs/scheduler seam",
+        guide="jobs",
+    ),
+    Capability(
+        name="tenancy",
+        summary="Tenant isolation by construction (session-level filter + insert stamp).",
+        kind="library",
+        wiring="install_tenancy(...) at the composition root",
+        guide="tenancy",
+    ),
+    Capability(
+        name="users",
+        summary="Admin user management over the identity store.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True)",
+    ),
+    Capability(
+        name="webhooks",
+        summary="Reliable, signed, SSRF-guarded outbound webhooks on the jobs/outbox seam.",
+        kind="routed",
+        wiring="create_app(..., discover_capabilities=True)",
+    ),
+)
+
+
+def _is_installed(capability: Capability) -> bool:
+    """Whether *capability*'s distribution is resolvable in this environment."""
+    try:
+        metadata.distribution(capability.distribution)
+    except metadata.PackageNotFoundError:
+        return False
+    return True
+
+
+def render_capabilities(*, fmt: str = "text") -> str:
+    """Render every adoptable capability, marking the ones this app already has.
+
+    Answers the question the gate never could: *what else is on the shelf?* Installed
+    capabilities are listed first so the reader sees the current profile, then the
+    adoptable ones with the exact ``uv add`` line and wiring shape — no package index
+    search, no guessing at a name.
+    """
+    rows = [(cap, _is_installed(cap)) for cap in CAPABILITIES]
+    if fmt == "json":
+        return json.dumps(
+            {
+                "capabilities": [
+                    {
+                        "name": cap.name,
+                        "distribution": cap.distribution,
+                        "module": cap.module,
+                        "summary": cap.summary,
+                        "kind": cap.kind,
+                        "wiring": cap.wiring,
+                        "guide": cap.guide,
+                        "installed": installed,
+                    }
+                    for cap, installed in rows
+                ]
+            },
+            indent=2,
+        )
+
+    installed = [cap for cap, present in rows if present]
+    available = [cap for cap, present in rows if not present]
+    lines = [
+        "Capabilities",
+        "",
+        "Opt-in packages the platform maintains. A `routed` capability mounts its own",
+        "router when discovery is on; a `library` capability is imported and wired at",
+        "the composition root. Adopting one is always: add the dependency, wire it, run",
+        "`uv run terp migrate` if it ships tables.",
+        "",
+        f"Installed in this app ({len(installed)})",
+        "",
+    ]
+    for cap in installed:
+        lines.append(f"  {cap.distribution:<32} {cap.kind}")
+        lines.append(f"      {cap.summary}")
+    if not installed:
+        lines.append("  (none)")
+    lines += ["", f"Available to adopt ({len(available)})", ""]
+    for cap in available:
+        lines.append(f"  {cap.distribution:<32} {cap.kind}")
+        lines.append(f"      {cap.summary}")
+        lines.append(f"      uv add {cap.distribution}")
+        lines.append(f"      {cap.wiring}")
+        if cap.guide is not None:
+            lines.append(f"      uv run terp guide {cap.guide}")
+    if not available:
+        lines.append("  (none — every maintained capability is installed)")
+    lines += [
+        "",
+        "Do not hand-roll what a capability owns. If you need something none of these",
+        "covers, stop and report the missing capability rather than building a local",
+        "substitute (`uv run terp guide capability`).",
+    ]
+    return "\n".join(lines)

terp_cli-0.5.0/src/terp/cli/grants.py

@@ -0,0 +1,233 @@
+"""``terp grant`` — assign, list and revoke a subject's permission grants.
+
+Terp has had per-subject permission grants since ADR 0013, and almost nobody uses
+them. The reason is not that operators prefer broad roles; it is that granting was
+the expensive option:
+
+- it needed an **admin token**, so you had to already be the thing you were trying
+  to avoid needing;
+- it needed the subject's **UUID**, which nobody has — people have an email address
+  or the name of an integration;
+- it needed the **exact permission string**, and nothing anywhere would tell you
+  which strings the app actually checks.
+
+Faced with that, the rational move is to bump the account to a role that already
+clears the check and move on. Least privilege loses to a ten-second workaround every
+time. So this command removes all three costs: it resolves a subject from an email or
+a service-account name, it validates the permission against the app's own catalog and
+*prints the catalog* when you get it wrong, and it writes through the audited
+``AccessService`` chokepoint without an HTTP round trip.
+
+It deliberately does **not** grow a ``--force`` for an unknown permission. A grant of
+a string the app never checks is not a lenient grant, it is a silent no-op — and the
+person who wrote it will believe the integration is authorized until it is not.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import pathlib
+import uuid
+
+from fastapi import FastAPI
+from sqlmodel import Session
+
+from terp.cli._appref import load_app, push_app_root
+from terp.core.db import get_session
+
+
+def _catalog(app: FastAPI) -> dict[str, str]:
+    """The app's declared permissions, name -> minimum role name.
+
+    Read off the composed app's control plane rather than a static list, so the
+    command can only ever offer permissions this app really enforces.
+    """
+    plane = getattr(getattr(app, "state", None), "terp_control_plane", None)
+    if plane is None:
+        raise SystemExit(
+            "the app exposes no control plane (create_app records it on app.state) — "
+            "pass a terp app factory, e.g. --app app.main:build"
+        )
+    return {
+        permission.name: permission.min_role.name
+        for permission in plane.permissions.permissions
+    }
+
+
+def _resolve_permission(app: FastAPI, permission: str) -> str:
+    """Check *permission* against the app's catalog, or fail listing the choices.
+
+    The error is the feature: "unknown permission" alone sends the reader back to
+    grepping the source, which is the moment they give up and widen the role instead.
+    """
+    catalog = _catalog(app)
+    if permission in catalog:
+        return permission
+    known = "\n".join(
+        f"  {name}  (needs role {min_role} or higher)"
+        for name, min_role in sorted(catalog.items())
+    )
+    raise SystemExit(
+        f"unknown permission {permission!r}. This app declares:\n{known}\n\n"
+        "A grant of a permission the app never checks is a silent no-op, so it is "
+        "refused rather than stored."
+    )
+
+
+def _resolve_subject(session: Session, subject: str) -> tuple[uuid.UUID, str]:
+    """Resolve *subject* — a UUID, a user email, or a service-account name.
+
+    Grants are keyed by a bare subject id with no foreign key (ADR 0013), which is
+    what lets a user, a service account and a group all be granted the same way. The
+    cost is that the id means nothing to a human, so this command accepts what people
+    actually have and does the lookup itself.
+    """
+    with contextlib.suppress(ValueError):
+        return uuid.UUID(subject), f"subject {subject}"
+
+    if "@" in subject:
+        from terp.capabilities.users import UsersService
+
+        user = UsersService().get_by_email(session, subject)
+        if user is None:
+            raise SystemExit(f"no user with email {subject!r}")
+        return user.id, f"user {subject!r}"
+
+    from terp.capabilities.identity import ServiceAccountService
+
+    account = ServiceAccountService().get_by_name(session, subject)
+    if account is None:
+        raise SystemExit(
+            f"no service account named {subject!r} (pass an email for a user, a "
+            "service-account name for a machine, or a subject UUID for anything else)"
+        )
+    return account.id, f"service account {subject!r}"
+
+
+def _load(app_ref: str, app_root: str | pathlib.Path) -> FastAPI:
+    push_app_root(app_root)
+    return load_app(app_ref)
+
+
+def _rank_shortfall(
+    app: FastAPI, session: Session, subject: str, permission: str
+) -> str | None:
+    """Describe the subject's role if it sits below *permission*'s minimum, else None.
+
+    Only answerable for subjects that carry a rank of their own — a bare UUID or a
+    group has none, and for those the question belongs to whatever the id resolves to.
+    """
+    plane = app.state.terp_control_plane
+    # The caller resolved *permission* against this same catalog, so the lookup cannot
+    # miss — an undeclared permission never reaches this point.
+    declared = next(p for p in plane.permissions.permissions if p.name == permission)
+
+    rank: int | None = None
+    if "@" in subject:
+        from terp.capabilities.users import UsersService
+
+        user = UsersService().get_by_email(session, subject)
+        rank = None if user is None else user.role
+    else:
+        from terp.capabilities.identity import ServiceAccountService
+
+        account = ServiceAccountService().get_by_name(session, subject)
+        rank = None if account is None else account.role
+
+    if rank is None or rank >= declared.min_role.rank:
+        return None
+    return f"{plane.permissions.role_for_rank(rank).name} (rank {rank})"
+
+
+def grant_add_command(
+    subject: str,
+    permission: str,
+    *,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+) -> str:
+    """Grant *permission* to *subject*, audited and idempotent."""
+    app = _load(app_ref, app_root)
+    name = _resolve_permission(app, permission)
+    min_role = _catalog(app)[name]
+
+    from terp.capabilities.access import AccessService
+    from terp.core import AppError
+
+    with contextlib.closing(get_session()) as gen:
+        session = next(gen)
+        subject_id, label = _resolve_subject(session, subject)
+        try:
+            AccessService().grant(session, subject_id, name)
+        except AppError as exc:
+            raise SystemExit(f"could not grant {name!r} to {label}: {exc}") from exc
+        shortfall = _rank_shortfall(app, session, subject, name)
+    granted = f"granted {name!r} to {label} ({subject_id})"
+    if shortfall is None:
+        return granted
+    # The guard checks rank before it checks grants, so a grant to a subject below the
+    # permission's minimum role is stored but can never fire. Saying so here is the
+    # whole point of the command: a grant that silently does nothing is worse than no
+    # grant, because the operator walks away believing the integration is authorized.
+    return (
+        f"{granted}\n"
+        f"  WARNING: {name!r} requires role {min_role} or higher and this subject is "
+        f"{shortfall}. The grant is stored but will not take effect until the "
+        "subject's role rank reaches that minimum."
+    )
+
+
+def grant_revoke_command(
+    subject: str,
+    permission: str,
+    *,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+) -> str:
+    """Revoke *permission* from *subject*.
+
+    The permission is **not** validated against the catalog here: a permission the app
+    has since stopped declaring is exactly the stale grant you most want to be able to
+    clean up.
+    """
+    _load(app_ref, app_root)
+
+    from terp.capabilities.access import AccessService
+
+    with contextlib.closing(get_session()) as gen:
+        session = next(gen)
+        subject_id, label = _resolve_subject(session, subject)
+        removed = AccessService().revoke(session, subject_id, permission)
+    if not removed:
+        return f"{label} did not hold {permission!r}; nothing to revoke"
+    return f"revoked {permission!r} from {label} ({subject_id})"
+
+
+def grant_list_command(
+    subject: str,
+    *,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+) -> str:
+    """List everything *subject* holds — the answer to "why can it do that?".
+
+    Grants inherited through group membership are included, because the question being
+    asked is what this subject can do, not which rows happen to name it.
+    """
+    app = _load(app_ref, app_root)
+    catalog = _catalog(app)
+
+    from terp.capabilities.access import AccessService
+
+    with contextlib.closing(get_session()) as gen:
+        session = next(gen)
+        subject_id, label = _resolve_subject(session, subject)
+        held = sorted(AccessService().permissions_for(session, subject_id))
+    if not held:
+        return f"{label} ({subject_id}) holds no permission grants"
+    lines = "\n".join(
+        f"  {name}"
+        + ("" if name in catalog else "   [stale: this app no longer declares it]")
+        for name in held
+    )
+    return f"{label} ({subject_id}) holds:\n{lines}"

terp_cli-0.5.0/src/terp/cli/service_accounts.py

@@ -0,0 +1,79 @@
+"""``terp service-account create`` — provision a machine credential against the store.
+
+The bootstrap problem is the same one ``terp user create`` solves, one step further
+along: an integration needs a credential before it can call anything, and the only
+alternative to a command like this is for somebody to hand it a person's password.
+Given how that ends — a shared admin login nobody can revoke without breaking a
+production job — the machine path has to be at least as easy as the wrong one.
+
+The generated secret is printed **once**, to stdout, and never stored in the clear.
+There is no command to read it back; a lost secret is re-provisioned. The account's
+role rank is required, not defaulted, because the whole point is that an integration's
+authority is chosen rather than inherited.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import datetime
+import pathlib
+
+from terp.cli._appref import load_app, push_app_root
+from terp.cli.users import resolve_role
+from terp.core.db import get_session
+
+
+def create_service_account_command(
+    name: str,
+    *,
+    role: str,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+    description: str | None = None,
+    expires_in_days: int | None = 365,
+) -> str:
+    """Build *app_ref*, then provision service account *name* at *role*, audited.
+
+    *expires_in_days* defaults to a year rather than to "never": a machine credential
+    outlives the ticket that justified it and the person who created it, so an end date
+    it has to be renewed past is the only thing that reliably forces a second look.
+    Pass ``None`` for a non-expiring credential — deliberately, and in writing.
+    """
+    push_app_root(app_root)
+    load_app(app_ref)
+
+    from terp.capabilities.identity import ServiceAccountService
+    from terp.capabilities.identity.schemas import ServiceAccountCreate
+    from terp.core import AppError
+
+    rank = resolve_role(role)
+    expires_at = (
+        datetime.datetime.now(datetime.UTC) + datetime.timedelta(days=expires_in_days)
+        if expires_in_days is not None
+        else None
+    )
+    service = ServiceAccountService()
+    with contextlib.closing(get_session()) as gen:
+        session = next(gen)
+        try:
+            account, secret = service.provision(
+                session,
+                ServiceAccountCreate(
+                    name=name,
+                    role_rank=rank,
+                    description=description,
+                    expires_at=expires_at,
+                ),
+            )
+        except AppError as exc:
+            raise SystemExit(f"could not create service account {name!r}: {exc}") from exc
+
+    expiry = account.expires_at.date().isoformat() if account.expires_at else "never"
+    return (
+        f"created service account {name!r} (id {account.id}, role rank {rank}, "
+        f"expires {expiry})\n"
+        f"  client_id:     {account.client_id}\n"
+        f"  client_secret: {secret}\n"
+        "\nThe secret is shown once and is not recoverable. Store it in the "
+        "integration's secret store now; if it is lost, provision a new account."
+    )

{terp_cli-0.3.0 → terp_cli-0.5.0}/src/terp/cli/verify.py

@@ -255,9 +255,86 @@ def _reports_in(stdout: str) -> list[dict]:
     ]
 
 
+def _node_platform() -> tuple[str, str]:
+    """This machine as npm names it — ``process.platform`` / ``process.arch``."""
+    import platform as _platform
+
+    system = {"win32": "win32", "darwin": "darwin"}.get(sys.platform, "linux")
+    machine = _platform.machine().lower()
+    arch = {
+        "amd64": "x64",
+        "x86_64": "x64",
+        "aarch64": "arm64",
+        "arm64": "arm64",
+    }.get(machine, machine)
+    return system, arch
+
+
+def _node_modules_problem(root: pathlib.Path) -> str | None:
+    """Explain an unusable ``frontend/node_modules``, or None if it looks fine.
+
+    An npm install is platform-specific: the native binaries a bundler needs are
+    optional dependencies gated on ``os``/``cpu``, so a tree installed on the
+    Windows host has no Linux binary, and running the gate in the container dies
+    with a raw Node stack (``Cannot find module '@rolldown/binding-linux-x64-gnu'``)
+    that names neither the cause nor the fix. Every Terp failure states the fix, so
+    this is detected up front rather than left to the reader to decode.
+
+    The lockfile already records which optional packages belong on which platform,
+    so the check is exact and needs no list of native package names to maintain.
+    """
+    frontend = root / "frontend"
+    if not (frontend / "package.json").is_file():
+        return None
+    modules = frontend / "node_modules"
+    if not modules.is_dir():
+        return (
+            "frontend/node_modules is missing — the frontend checks cannot run.\n"
+            "  Fix: npm --prefix frontend ci"
+        )
+
+    lockfile = frontend / "package-lock.json"
+    if not lockfile.is_file():
+        return None
+    try:
+        packages = json.loads(lockfile.read_text(encoding="utf-8")).get("packages", {})
+    except (OSError, ValueError):
+        return None
+
+    system, arch = _node_platform()
+    missing = [
+        name
+        for name, entry in packages.items()
+        if name.startswith("node_modules/")
+        and isinstance(entry, dict)
+        # Only packages this platform is *supposed* to have: an entry with no os/cpu
+        # constraint is platform-neutral, and one constrained elsewhere is absent by
+        # design rather than by a bad install.
+        and system in (entry.get("os") or [system])
+        and arch in (entry.get("cpu") or [arch])
+        and (entry.get("os") or entry.get("cpu"))
+        and not (frontend / name).exists()
+    ]
+    if not missing:
+        return None
+    return (
+        f"frontend/node_modules was installed for a different platform: "
+        f"{len(missing)} package(s) this machine ({system}/{arch}) needs are absent, "
+        f"e.g. {missing[0].removeprefix('node_modules/')}.\n"
+        "  This happens when the tree is installed on the host and the gate runs in "
+        "a container (or vice versa); native binaries are per-platform optional "
+        "dependencies and do not travel.\n"
+        "  Fix: npm --prefix frontend ci   (run it where the gate runs)"
+    )
+
+
 def _run_subprocess(check: VerifyCheck, root: pathlib.Path) -> tuple[int, str]:
     """Run one manifest command (shell-less; ``&&`` composites never land here)."""
     argv = shlex.split(check.command)
+    if argv and argv[0] == "npm":
+        problem = _node_modules_problem(root)
+        if problem is not None:
+            return 1, problem
     executable = shutil.which(argv[0]) or argv[0]
     try:
         completed = subprocess.run(  # noqa: S603 - fixed manifest argv, shell=False

terp_cli-0.3.0/PKG-INFO

@@ -1,16 +0,0 @@
-Metadata-Version: 2.4
-Name: terp-cli
-Version: 0.3.0
-Summary: Terp command-line tool — inspect, scaffolding, migrations, checks, api-docs.
-License-Expression: Apache-2.0
-Requires-Python: >=3.13
-Requires-Dist: terp-arch==0.3.0
-Requires-Dist: terp-core==0.3.0
-Requires-Dist: terp-migrations==0.3.0
-Provides-Extra: jobs
-Requires-Dist: terp-cap-outbox==0.3.0; extra == 'jobs'
-Requires-Dist: terp-cap-scheduler-apscheduler==0.3.0; extra == 'jobs'
-Provides-Extra: scheduler
-Requires-Dist: terp-cap-scheduler-apscheduler==0.3.0; extra == 'scheduler'
-Provides-Extra: worker
-Requires-Dist: terp-cap-outbox==0.3.0; extra == 'worker'