terp-cli 0.32.0__tar.gz → 0.34.0__tar.gz

{terp_cli-0.32.0 → terp_cli-0.34.0}/PKG-INFO

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

{terp_cli-0.32.0 → terp_cli-0.34.0}/pyproject.toml

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

{terp_cli-0.32.0 → terp_cli-0.34.0}/src/terp/cli/__init__.py

@@ -683,6 +683,11 @@ Stored references (Ref + OnDelete)
   chosen), and a database reports its default action as absent rather than as the
   words NO ACTION -- which is why emitting the literal would make every
   model-versus-database comparison report drift on that constraint forever.
+- A reference you WRITE must point at a row you could READ. The foreign key checks that
+  the target exists; every flush also checks it against the target's row scope
+  (tenancy, soft-delete, an owner read scope), on insert and whenever an update changes
+  the reference - however the flush is reached, an autoflush included. Out of scope
+  reads exactly like missing: the same 409.
 - Ref() forwards everything else to Field(), and indexes by default: an unindexed
   foreign key turns every parent delete and every join into a table scan.
       owner_id: uuid.UUID | None = Ref("user.id", on_delete=OnDelete.SET_NULL,
@@ -1007,6 +1012,11 @@ Multi-tenant rows (tenancy capability)
       class Doc(BaseTable, TenantScopedMixin, table=True): ...
       class DocService(TenantScopedService[Doc, DocCreate, DocUpdate]): model = Doc
 - Never filter tenant_id by hand — the framework owns the predicate (the gate forbids it).
+- A reference stays inside its tenant. Every flush checks each Ref it writes against
+  the target model's row scope, so a row cannot point at another
+  tenant's row (nor at a soft-deleted one): the write fails with the same 409 a missing
+  target gets, and says nothing about the other tenant. Nothing to wire - it follows from
+  the predicate the mixin registers.
 - The current tenant comes from the request (TenantMiddleware binds the JWT `tenant`
   claim); in tests use tenant_context(tenant_id).
 - Wire it through the create_app middleware seam — never add_middleware (the gate
@@ -1454,8 +1464,23 @@ Realtime push (realtime capability)
 - 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).
+- The default broker and ticket store are PER PROCESS: a publish reaches only subscribers
+  connected to the process that published. That breaks with a second replica, and it
+  breaks with ONE replica too once a job handler runs in `terp jobs worker` - the worker
+  serves no transport, so its publish reaches nobody. Share both through Redis
+  (terp-cap-redis[realtime]) and promise it, so a missing wiring fails instead of
+  dropping messages:
+      configure_broker(RedisRealtimeBroker.from_url(settings.REDIS_URL))
+      configure_ticket_store(RedisConnectionTicketStore.from_url(settings.REDIS_URL))
+      configure_realtime(..., require_shared_broker=settings.is_production)
+  The worker runs the same composition root, so it wires the same broker. Pub/sub is
+  server-wide: the database index is in the channel names, but two deployments sharing
+  one Redis server AND database need distinct namespace=... values. Delivery is
+  fire-and-forget either way: a message published while nobody listens is gone, and a
+  publish Redis does not take (connecting and the reply are each bounded at 2s) is
+  dropped with a logged warning - it never fails the write that published it. A
+  transport subscribes before it answers, so an unreachable Redis is an SSE 503 or a
+  WebSocket closed 1013 before accept, and the browser backs off.
 - 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
@@ -1579,6 +1604,26 @@ Using capabilities
   and egress auditing attach. A sanctioned internal target is a declared
   `allow_private_addresses=True`, visible in the composition root, never a quiet
   exception inside the client.
+- A vendor SDK builds its own HTTP client, so neither the rule (it reads YOUR imports)
+  nor EgressClient sees its traffic. Hold the whole process to the declaration at the
+  socket, in the composition root the web process and the worker both run:
+      install_egress_guard(EgressGuard.for_policies(
+          rates_policy,                              # every EgressPolicy you declared
+          hosts=("api.vendor.example",),             # what an SDK calls, by exact name
+          infrastructure=("db", "redis", "smtp.relay.internal"),  # names, IPs or CIDRs
+      ))
+  It holds what goes through Python's socket module on IPv4/IPv6, whichever library
+  calls it: a lookup of an undeclared name (getaddrinfo, gethostbyname) is refused
+  before it is made, and a connect or datagram into a private / loopback / link-local /
+  metadata range is refused unless it is declared infrastructure; a peer given by name
+  (localhost too) is resolved and every address held. The refusal is EgressRefusedError
+  (502); under an async client it can arrive inside an ExceptionGroup. It cannot see
+  uvloop, so it refuses to install beside it and refuses `import uvloop` after it: run
+  uvicorn with --loop asyncio (uvicorn[standard] picks uvloop otherwise), and a worker
+  or scheduler with asyncio.run. Native drivers that open their own sockets (libpq,
+  gRPC's C core) are invisible to it and a public IP literal passes; the deployment's
+  network policy holds those. Built for Linux: on Windows asyncio's socketpair connects
+  to loopback, so a new event loop is refused unless loopback is declared.
 - Credentials never live in module source: a credential-shaped assignment (password,
   api_key, token, ...) to a string literal — or a recognizable secret-token literal
   anywhere — is refused by the no_hardcoded_credentials rule. Wire secrets through
@@ -1778,28 +1823,36 @@ Frontend module screens (@terpjs/react-core)
   everything composes the token-styled @terpjs/react-core surface. The full catalog (with
   per-export "Use" guidance) is the @terpjs/react-core README; each export also carries
   JSDoc, so your editor shows the same guidance inline.
-- The boundary lint (@terpjs/eslint-boundaries) refuses, fail-closed:
+- The boundary lint (@terpjs/eslint-boundaries) refuses, fail-closed, in every file under
+  frontend/src/ — a component beside the modules is held exactly like one inside them:
     raw <button>/<input>/<select>/<textarea>   ->  Button / Input / Select / Textarea
     raw <table>                                ->  DataView          (terp guide dataview)
     raw <dialog>                               ->  ConfirmDialog
     raw <form>                                 ->  Stack as="form"   (terp guide forms)
     raw fetch / XMLHttpRequest                 ->  useTerpClient() + unwrap (typed client)
     WebSocket / EventSource / sendBeacon       ->  the generated client (one egress path)
-    style={} / className / module stylesheets  ->  layout via Stack/DetailList; design tokens
+    style={} / className / any stylesheet      ->  layout via Stack/DetailList; design tokens
     <a href="/...">                            ->  the router's Link (role-aware, no reload)
     deep imports (@terpjs/*/src, @terpjs/*/dist)   ->  import from the package root only
     data-terp / data-terp-* anywhere in src    ->  compose the component that renders it
   The data-terp markers are react-core's own: its stylesheet and the runtime layout check
   trust them. A framework screen you replace (renderTerpApp({ login })) is yours, so its
   tests find it by role and accessible name, not by the framework screen's markers.
+  The bootstrap (src/main.tsx) is the one file that imports stylesheets, and only the token
+  pipeline's three: @terpjs/contract/tokens.css, ./house-style.css and ./theme.css. A
+  library's stylesheet is refused there too: it would paint outside the palettes. A
+  stylesheet loaded through import() or import.meta.glob is refused the same way.
+  Modules stay independent: a module never imports a sibling, and code outside the modules
+  (a shared helper) never imports from one, since shared code is what modules depend on.
+  The bootstrap finds the modules with import.meta.glob, which is not an import.
 - Frontend security defaults (each its own lint rule, same error-only footing):
   dangerouslySetInnerHTML and DOM HTML-injection sinks (innerHTML/outerHTML/
   insertAdjacentHTML/document.write) are refused — render text, or Markdown from
   @terpjs/react-core for rich text; eval() / new Function() are refused; javascript:
   URLs in href/src are refused; a static target="_blank" link needs rel="noopener".
 - Every routed view renders a page archetype (Page / OverviewPage / DetailPage / HubPage /
-  DashboardPage / FormPage / SettingsPage / SplitPage); buildAppRouter refuses an unframed
-  view at runtime, fail closed. An app can ratchet
+  DashboardPage / FormPage / SettingsPage / SplitPage / WorkspacePage); buildAppRouter
+  refuses an unframed view at runtime, fail closed. An app can ratchet
   further with an opt-in slot-typed layout contract (terp guide layouts).
 - Route paths and params are CHECKED, from generated types (ADR 0092). The router is built
   at runtime from the manifests, so nothing type-checks a path or a param name until you
@@ -1873,7 +1926,7 @@ Forms (react-core primitives)
         <Button type="submit" variant="primary">Save</Button>
       </Stack>
 - Field wraps label + control + hint/error for one field; Stack (vertical by default)
-  is the layout — never style={} / className / a module stylesheet.
+  is the layout — never style={} / className / a stylesheet.
 - Submit through the typed client: const client = useTerpClient();
   await unwrap(client.POST("/api/v1/invoices/", { body })); a failure throws ApiError
   ({code, status, requestId, fields}) — map codes to copy with useErrorMessage, show
@@ -1938,8 +1991,8 @@ Theming and branding (design tokens, palettes, the brand mark)
 
 - EVERY style is a design token. The react-core primitives paint from CSS custom
   properties shipped by @terpjs/contract (tokens.css), which is why the boundary lint
-  refuses `style={}`, `className` and module stylesheets: a module that painted itself
-  would not follow the palette. Modules never need theme-specific code.
+  refuses `style={}`, `className` and stylesheets in every src/ file: code that painted
+  itself would not follow the palette. Modules never need theme-specific code.
 - THE SHIPPED PALETTES, plus "system":
       midday  twilight  evening  night  contrast
   Named for the time of day they suit: midday is the light set, twilight a dimmed dark,
@@ -2095,6 +2148,10 @@ Layout contracts (slot-typed layouts, ADR 0079)
                       BarChart / ProportionBar / StatusHistory / Timeline / Divider / Text +
                       the same states and ConfirmDialog: "how is the whole doing", its
                       figures in the summary band
+      WorkspacePage -> ONE CanvasHost + the same states and ConfirmDialog: one canvas that
+                      fills the screen. The host takes ONE canvas child (an svg, or a
+                      canvas library's root) and sizes it to the whole box; what is
+                      drawn ON it is yours. The trail is `parents`, as on DashboardPage
   Grid is not an overview-body component, deliberately: an overview body is a data
   collection, a grid of cards into each area is a hub, and sections of figures and charts
   are a dashboard — each has its own archetype. Heading is admitted nowhere: a heading in a governed body must OWN its
@@ -2137,7 +2194,9 @@ Layout contracts (slot-typed layouts, ADR 0079)
   app's areas is a HubPage; one area's collection (how each one is doing) an OverviewPage;
   how the whole is doing a DashboardPage -- a landing that also carries the app's figures is
   one, as the hub preset scaffolds it; one record a DetailPage; entering a record a
-  FormPage; settings a SettingsPage; a list beside the record it selects a SplitPage.
+  FormPage; settings a SettingsPage; a list beside the record it selects a SplitPage; work
+  done on a surface (a diagram of nodes and connections, a plan) a WorkspacePage, whose one
+  CanvasHost takes every pixel the shell leaves - a canvas never needs a style to be sized.
 - Alternate framed and unframed blocks. The frame belongs to the data a reader works with:
   a collection, a chart and a lone figure sit on the surface, the collection brightest. A
   boxed Card steps back onto --color-bg-subtle, for a group of controls or one section of

{terp_cli-0.32.0 → terp_cli-0.34.0}/src/terp/cli/verify.py

@@ -1090,6 +1090,45 @@ def _node_modules_problem(root: pathlib.Path, workspace: str) -> str | None:
     )
 
 
+#: The status a shell gives a command it cannot find, and the one a check answers with
+#: when the tool it runs is not installed.
+_NOT_FOUND = 127
+
+
+def _run_argv(
+    argv: list[str], root: pathlib.Path, *, env: dict[str, str] | None = None
+) -> subprocess.CompletedProcess[str]:
+    """Run *argv* in *root* as a fixed argv, with no shell; a missing tool is a result.
+
+    Every check that shells out comes through here, so a tool that is not installed
+    answers the way a shell would, exit 127 naming the tool, instead of raising. Only the
+    manifest runner used to catch it. The runners with a body of their own (route types,
+    the API client, the API reference) let ``FileNotFoundError`` escape the profile loop:
+    the run ended in a traceback about ``subprocess``, every check after that one went
+    unrun and unreported, and the one fact worth reading, which tool is missing, was a
+    frame deep in the stack.
+
+    The message is the result's stdout, so each caller's own formatting of a finished
+    command carries it unchanged.
+    """
+    executable = shutil.which(argv[0]) or argv[0]
+    try:
+        return subprocess.run(  # noqa: S603 - fixed argv, shell=False
+            [executable, *argv[1:]],
+            cwd=root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+            env=None if env is None else {**os.environ, **env},
+        )
+    except FileNotFoundError:
+        return subprocess.CompletedProcess(
+            argv, _NOT_FOUND, stdout=f"{argv[0]}: executable not found on PATH", stderr=""
+        )
+
+
 def _run_subprocess(
     check: VerifyCheck, root: pathlib.Path, *, env: dict[str, str] | None = None
 ) -> tuple[int, str]:
@@ -1109,20 +1148,7 @@ def _run_subprocess(
         problem = _node_modules_problem(root, _npm_workspace(argv))
         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
-            [executable, *argv[1:]],
-            cwd=root,
-            capture_output=True,
-            text=True,
-            encoding="utf-8",
-            errors="replace",
-            check=False,
-            env=None if env is None else {**os.environ, **env},
-        )
-    except FileNotFoundError:
-        return 127, f"{argv[0]}: executable not found on PATH"
+    completed = _run_argv(argv, root, env=env)
     return completed.returncode, completed.stdout + (
         "\n" + completed.stderr if completed.stderr else ""
     )
@@ -1640,17 +1666,7 @@ def _run_routes_drift(root: pathlib.Path) -> tuple[int, str]:
     problem = _node_modules_problem(root, "frontend")
     if problem is not None:
         return 1, problem
-    argv = routes_argv(check=True)
-    executable = shutil.which(argv[0]) or argv[0]
-    completed = subprocess.run(  # noqa: S603 - fixed manifest argv, shell=False
-        [executable, *argv[1:]],
-        cwd=root,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
+    completed = _run_argv(routes_argv(check=True), root)
     return completed.returncode, f"{completed.stdout}{completed.stderr}"
 
 
@@ -1663,21 +1679,6 @@ _API_DOCS_ARTIFACTS = ("platform-api.md", "terp_core.pyi")
 _API_DOCS_ADOPT_HINT = "commit docs/platform-api.md + docs/terp_core.pyi to enable"
 
 
-def _tracked(root: pathlib.Path, relative: str) -> bool:
-    """Whether *relative* is a file git is tracking in *root*."""
-    git = shutil.which("git") or "git"
-    completed = subprocess.run(  # noqa: S603 - fixed argv, shell=False
-        [git, "ls-files", "--error-unmatch", "--", relative],
-        cwd=root,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
-    return completed.returncode == 0
-
-
 def _run_api_docs_drift(root: pathlib.Path) -> tuple[int, str]:
     """Regenerate the API reference and fail on drift from the committed copy.
 
@@ -1707,7 +1708,20 @@ def _run_api_docs_drift(root: pathlib.Path) -> tuple[int, str]:
             f"({_API_DOCS_ADOPT_HINT})",
         )
     relatives = [f"docs/{name}" for name in _API_DOCS_ARTIFACTS]
-    tracked = [relative for relative in relatives if _tracked(root, relative)]
+    probes = {
+        relative: _run_argv(["git", "ls-files", "--error-unmatch", "--", relative], root)
+        for relative in relatives
+    }
+    if any(probe.returncode == _NOT_FOUND for probe in probes.values()):
+        # Not "untracked, skipped": without git there is no answer to whether the pair is
+        # tracked, and reading that silence as "no" would turn this check green over a
+        # comparison it never made.
+        return (
+            _NOT_FOUND,
+            "git: executable not found on PATH - the drift check asks git whether "
+            f"{' + '.join(relatives)} are tracked, so it cannot run without it",
+        )
+    tracked = [relative for relative, probe in probes.items() if probe.returncode == 0]
     if not tracked:
         return (
             0,
@@ -1729,16 +1743,7 @@ def _run_api_docs_drift(root: pathlib.Path) -> tuple[int, str]:
         written = [str(path) for path in api_docs(str(docs))]
     finally:
         os.chdir(previous)
-    git = shutil.which("git") or "git"
-    completed = subprocess.run(  # noqa: S603 - fixed argv, shell=False
-        [git, "diff", "--exit-code", "--", *relatives],
-        cwd=root,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
+    completed = _run_argv(["git", "diff", "--exit-code", "--", *relatives], root)
     output = "\n".join(
         ["\n".join(f"wrote {path}" for path in written), completed.stdout]
     )
@@ -1941,17 +1946,7 @@ def _run_api_client(root: pathlib.Path) -> tuple[int, str]:
         return 1, f"could not export the OpenAPI document: {refusal}"
     finally:
         os.chdir(previous)
-    argv = ["npm", "--prefix", "frontend", "run", "generate"]
-    executable = shutil.which(argv[0]) or argv[0]
-    completed = subprocess.run(  # noqa: S603 - fixed argv, shell=False
-        [executable, *argv[1:]],
-        cwd=root,
-        capture_output=True,
-        text=True,
-        encoding="utf-8",
-        errors="replace",
-        check=False,
-    )
+    completed = _run_argv(["npm", "--prefix", "frontend", "run", "generate"], root)
     output = f"wrote {written.name}\n{completed.stdout}{completed.stderr}"
     if completed.returncode != 0:
         output += (