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

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

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

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

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

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

@@ -16,7 +16,7 @@ from terp.core import ControlPlane, CorsPolicy, ModuleSpec
 if TYPE_CHECKING:  # terp-arch stays off the common `terp guide` / `terp inspect` path
     from terp.arch import ScanRoot
 
-from terp.cli._output import emit
+from terp.cli._output import emit, use_utf8_output
 from terp.cli.access import (
     build_access_graph_for_app,
     render_access,
@@ -229,8 +229,11 @@ Adopt it by declaring the table (a project from the template already has it):
 
     [tool.deptry.per_rule_ignores]
     # `terp.*` is one PEP 420 namespace across distributions, and pydantic
-    # re-exports through sqlmodel / pydantic-settings.
-    DEP003 = ["terp", "pydantic"]
+    # re-exports through sqlmodel / pydantic-settings. fastapi, sqlmodel,
+    # sqlalchemy and alembic are the stack terp-core and terp-migrations bring,
+    # which the template's code, `terp new module` and `terp migrate make` all
+    # import directly: constrained by that release, not by a second pin here.
+    DEP003 = ["terp", "pydantic", "fastapi", "sqlmodel", "sqlalchemy", "alembic"]
 
 and installing the tool: `uv add --dev deptry`.
 
@@ -1554,7 +1557,82 @@ Using capabilities
   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
   settings / sealed config (ADR 0055), never source.
-""",    "migrations": """\
+- Sending e-mail is a capability too: `import smtplib` is refused by the same
+  no_raw_outbound_http rule, and terp-cap-mail is where it goes — `terp guide mail`.
+""",
+    "mail": """\
+Sending e-mail (terp-cap-mail)
+
+- Mail is a capability concern, never a module concern: `import smtplib` anywhere in the
+  app is refused by the no_raw_outbound_http rule. Install the capability:
+      uv add terp-cap-mail
+- ONE relay per application, declared ONCE in the composition root (app/main.py) from
+  fixed environment variables:
+      import os
+      from terp.capabilities.mail import configure_mail, mail_settings_from_environment
+      configure_mail(mail_settings_from_environment(os.environ))
+    MAIL_FROM       the sender of EVERY message: "Name <noreply@example.com>" or a bare
+                    address
+    SMTP_HOST       the relay's bare hostname (smtp.example.com)
+    SMTP_PORT       optional: 587 for starttls, 465 for tls
+    SMTP_SECURITY   starttls (the default) | tls | none
+    SMTP_USERNAME / SMTP_PASSWORD   set together, or neither
+  The session is encrypted and the certificate verified; there is no setting that turns
+  verification off. `none` exists for a local mail catcher: a production boot refuses
+  it, and signing in over it is refused everywhere. With neither MAIL_FROM nor SMTP_HOST set,
+  development LOGS each message instead of delivering it and a production boot is
+  REFUSED. Declare the variables in environment.schema.json so a deployment renders them
+  per environment: SMTP_PASSWORD with "format": "secret", SMTP_HOST "format":
+  "hostname", SMTP_PORT "format": "port", and MAIL_FROM + SMTP_HOST in "required" so a
+  deploy without a relay is refused before it boots.
+- Register the job the capability enqueues (control_plane/jobs.py):
+      from terp.capabilities.mail import MAIL_SEND
+      job_catalog = JobCatalog([MAIL_SEND])
+  A job catalog needs ControlPlane(job_system_actor_id=...) in production — `terp guide
+  jobs`.
+- Send from INSIDE the write the mail is about: the service's _after_write hook runs in
+  that write's transaction, so the mail commits - or rolls back - with it. A send_mail
+  after the write has returned is a transaction of its own, and nothing ties the two.
+      from terp.core import AuditAction
+      from terp.capabilities.mail import MailMessage, send_mail
+      class OrderService(BaseService[Order, OrderCreate, OrderUpdate]):
+          def _after_write(self, session, entity, action):
+              if action is AuditAction.UPDATED and entity.status == "shipped":
+                  send_mail(session, MailMessage(
+                      to=[entity.customer_email],    # plain addresses, at most MAX_RECIPIENTS
+                      subject="Your order has shipped",   # one line: a line break is refused
+                      text=f"Order {entity.number} is on its way.",   # plain text
+                      reply_to="sales@example.com",  # optional: where a person's answer goes
+                  ))
+  List the job on the sending module, ModuleSpec(jobs=[MAIL_SEND]), so boot checks that
+  the catalog declares it.
+  There is no per-message sender (every mail is from MAIL_FROM), no HTML body and no
+  attachment. The same notice to many people is one send_mail per person, which also
+  keeps every recipient's address private from the others.
+- send_mail only ENQUEUES the MAIL_SEND job. Wire the durable outbox so the mail commits
+  — or rolls back — with the write, and survives a restart:
+      from terp.capabilities.outbox import OutboxJobQueue
+      create_app(..., job_queue=OutboxJobQueue(),
+                 require_durable_jobs=settings.is_production)
+  and run `terp jobs worker` beside the API. A relay that is down is retried with
+  backoff and ends dead-lettered: `terp outbox backlog` counts it and `terp outbox
+  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.
+- Test without a relay:
+      from terp.capabilities.mail import (
+          CapturingMailTransport, MailSettings, configure_mail, reset_mail)
+      sent = CapturingMailTransport()
+      configure_mail(MailSettings(sender="App <noreply@example.test>",
+                                  host="smtp.example.test"), transport=sent)
+      ...exercise the feature...
+      assert sent.sent[0]["Subject"] == "Your order has shipped"
+      reset_mail()
+- A provider reachable only over its HTTP API is a different transport, declared in the
+  same place: configure_mail(settings, transport=<a callable built on
+  terp.capabilities.egress>). Call sites stay send_mail either way.
+""",
+    "migrations": """\
 Database migrations (terp migrate)
 
 - Each table-owning package (capability or app module) owns an INDEPENDENT, linear
@@ -1684,6 +1762,10 @@ Frontend module screens (@terpjs/react-core)
     style={} / className / module stylesheets  ->  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.
 - 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
@@ -1709,6 +1791,12 @@ Frontend module screens (@terpjs/react-core)
   OpenAPI export) and unwrap(...) which throws a typed ApiError carrying code/status.
 - The one governed opt-out is a justified `// terp-allow-<rule>: <reason>` marker whose
   counts must exactly match the app's checked-in escape-hatch-budget.json (a ratchet).
+- Unit tests sit beside the code as src/**/*.test.tsx and run with
+  npm --prefix frontend test (vitest in jsdom; `terp verify` runs it too). jsdom has no
+  <dialog> modal API, so frontend/vitest.setup.ts calls installDialogPolyfill() from
+  @terpjs/react-core/testing: a test can open a ConfirmDialog and confirm it, cancel it or
+  press Escape. Focus and the inert page behind a modal are not emulated there; they
+  belong to the browser suite in conformance/.
 - Run the lint locally: npm --prefix frontend run lint (part of the gate).
 """,
     "dataview": """\
@@ -2142,11 +2230,15 @@ Compliant decision path for outbound HTTP
 1. Preserve the requested integration and its external contract. Removing the live
     call, returning static/local data, or moving the client import to an unscanned
     helper only to make the gate green is not a compliant fix.
-2. Use a maintained purpose-built capability when its semantics match. For example,
-    terp-cap-webhooks owns signed webhook POST delivery; it is not a generic GET client.
-3. The maintained Terp capability surface currently has no generic outbound-fetch
-    capability for arbitrary HTTP GETs. App modules therefore cannot implement a live
-    news/feed fetch through a sanctioned generic API today.
+2. Use the maintained capability whose semantics match:
+    - an HTTP call to a host you can name: terp-cap-egress (EgressClient, with that
+      exact host on its EgressPolicy allowlist);
+    - signed webhook POST delivery to subscriber URLs: terp-cap-webhooks;
+    - sending e-mail: terp-cap-mail (configure_mail once in the composition root,
+      send_mail per message) - never smtplib. `terp guide mail`.
+3. There is no sanctioned path to an ARBITRARY host: EgressPolicy takes exact hostnames
+    and refuses wildcards, so a feature that must fetch whatever URL a user supplies has
+    no compliant implementation today.
 4. When no matching capability exists, stop and report the missing capability. Leave
     the check red until a human approves an escape hatch or the platform supplies a
     reviewed adapter capability. Do not create an app-local helper package merely to
@@ -3499,19 +3591,21 @@ def _build_parser() -> argparse.ArgumentParser:
     dev_parser.add_argument(
         "--port",
         type=int,
-        default=DEFAULT_API_PORT,
+        default=None,
         help=(
-            f"Backend host port (default: {DEFAULT_API_PORT}) -- in the range Terp owns, "
-            "away from the 8000 another application on this machine is probably using"
+            "Backend host port (default: the pair claimed for this checkout, the one "
+            "`terp ports show` prints and a workbench and docker compose use; claimed "
+            f"and published on first run; {DEFAULT_API_PORT} if none can be claimed)"
         ),
     )
     dev_parser.add_argument(
         "--web-port",
         type=int,
-        default=DEFAULT_WEB_PORT,
+        default=None,
         help=(
-            f"Frontend host port (default: {DEFAULT_WEB_PORT}); passed through to the "
-            "frontend dev server, which would otherwise take its own 5173"
+            "Frontend host port (default: the web half of the same claimed pair; "
+            f"{DEFAULT_WEB_PORT} if none can be claimed); the frontend dev server refuses "
+            "a taken port rather than wandering to the next one"
         ),
     )
     dev_parser.add_argument(
@@ -3853,6 +3947,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
 def main(argv: Sequence[str] | None = None) -> None:
     """Console entry point."""
+    use_utf8_output()
     parser = _build_parser()
     args = parser.parse_args(argv)
     if args.command == "inspect" and args.inspect_command == "control-plane":

terp_cli-0.28.0/src/terp/cli/_output.py

@@ -0,0 +1,60 @@
+"""The one place ``terp``'s command dispatch writes to standard output.
+
+A CLI's job is to print, so ``no_print`` is not a defect report against this package --
+it is the reason ``packages/backend/cli`` is recorded in
+``packages/backend/UNSCANNED.json`` rather than scanned. What the record is for is the
+direction of travel: a count there may fall and never rise, so the dispatcher acquiring
+one more bare ``print`` per command added is the shape that makes it rise forever.
+
+One seam fixes that and is worth having on its own terms. Everything the dispatcher
+says to an operator goes through here, which is where a ``--quiet``, a machine-readable
+envelope, or a decision to route diagnostics to stderr would go. Thirty-eight call sites
+answering that question independently is thirty-eight places such a change has to find.
+
+Deliberately not a logger. This is a command's ANSWER, not a diagnostic about producing
+it: it belongs on stdout unconditionally, it is what a shell pipes into the next thing,
+and a log level that could suppress it would make the tool lie about having run.
+"""
+
+from __future__ import annotations
+
+import codecs
+import sys
+
+__all__ = ["emit", "use_utf8_output"]
+
+
+def emit(text: object = "") -> None:
+    """Write one line of command output to stdout, flushed.
+
+    Flushed because a pipe is block-buffered: a one-shot command loses nothing by it, but
+    ``terp dev`` runs until it is stopped, and a line saying it restarted the backend is only
+    worth reading while that is true. Unflushed, it sat in the buffer until the process ended,
+    and a stopped process's buffer is simply lost.
+    """
+    print(text, flush=True)
+
+
+def use_utf8_output() -> None:
+    """Write standard output and error as UTF-8 where the stream would not.
+
+    On Windows a pipe or a file takes the ANSI code page -- cp1252 on a Western install --
+    and a pipe is exactly how ``terp`` is read by an agent, an editor task or a workbench,
+    none of which is a console. cp1252 has no ``→``, so the line ``terp dev`` prints before
+    it starts the servers ended the command with ``UnicodeEncodeError`` instead; and text
+    this CLI does not author -- a module's label, a finding quoting a source line -- can do
+    the same to any command. UTF-8 encodes every string, and it is the default Python itself
+    moves to for these streams (PEP 686).
+
+    Changed only where it is not already UTF-8, so a console (which Python already drives
+    through the console API as UTF-8) and every Linux or macOS terminal are left exactly as
+    they were. A stream that cannot be reconfigured -- none at all, or a replacement such
+    as ``io.StringIO`` -- is left alone. ``backslashreplace`` rather than ``strict``, so the
+    one thing UTF-8 cannot encode, a lone surrogate from an undecodable file name, prints
+    as an escape rather than ending the command.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is None or codecs.lookup(stream.encoding).name == "utf-8":
+            continue
+        reconfigure(encoding="utf-8", errors="backslashreplace")

{terp_cli-0.25.0 → terp_cli-0.28.0}/src/terp/cli/capabilities.py

@@ -44,6 +44,17 @@ class Capability:
     guide: str | None = None
     """``terp guide`` topic covering it, when one exists."""
 
+    inventory: str | None = None
+    """The command that lists what this app holds of it, when the CLI has one.
+
+    The registry is built from packages, so it can say an app *has* a capability and
+    nothing about what the app has *done* with it. That gap misled a reader into
+    concluding an app had no machine credentials because the identity line said only
+    "user store": the service accounts it had issued were one command away, and nothing
+    on this screen named the command. Rendered for installed capabilities only — an
+    unadopted one has nothing to list.
+    """
+
     @property
     def distribution(self) -> str:
         """The PyPI distribution name."""
@@ -62,6 +73,7 @@ CAPABILITIES: tuple[Capability, ...] = (
         kind="routed",
         wiring="create_app(..., discover_capabilities=True)",
         guide="access",
+        inventory="terp grant list <subject>",
     ),
     Capability(
         name="audit",
@@ -90,6 +102,13 @@ CAPABILITIES: tuple[Capability, ...] = (
         wiring="create_app(..., discover_capabilities=True)",
         guide="files",
     ),
+    Capability(
+        name="mfa",
+        summary="A TOTP second factor with recovery codes, wired into login through the second_factor seam.",
+        kind="library",
+        wiring="build_login_module(..., second_factor=MfaService()) + specs=[mfa.module]",
+        guide="passwords",
+    ),
     Capability(
         name="groups",
         summary="Admin-managed user groups that bundle access-grant permissions.",
@@ -99,9 +118,11 @@ CAPABILITIES: tuple[Capability, ...] = (
     ),
     Capability(
         name="identity",
-        summary="Persisted user store backing authentication.",
+        summary="Persisted user store backing authentication, and the service accounts an integration signs in with.",
         kind="library",
         wiring="create_app(..., discover_capabilities=True)",
+        guide="package-boundaries",
+        inventory="terp service-account list",
     ),
     Capability(
         name="jobs_celery",
@@ -123,6 +144,14 @@ CAPABILITIES: tuple[Capability, ...] = (
         kind="library",
         wiring="create_app(..., lease_store=DatabaseLeaseStore()) + specs=[leases.module]",
         guide="leases",
+        inventory="terp leases list",
+    ),
+    Capability(
+        name="mail",
+        summary="Send e-mail through one declared relay — encrypted, a fixed sender, delivered by the jobs seam so a send commits with its write.",
+        kind="library",
+        wiring="configure_mail(mail_settings_from_environment(os.environ)) + JobCatalog([MAIL_SEND])",
+        guide="mail",
     ),
     Capability(
         name="oidc",
@@ -371,6 +400,7 @@ def render_capabilities(*, fmt: str = "text", root: str | pathlib.Path = ".") ->
                         "kind": cap.kind,
                         "wiring": cap.wiring,
                         "guide": cap.guide,
+                        "inventory": cap.inventory,
                         "installed": version is not None,
                         "version": version,
                         "seams": list(seams.get(cap.name, ())),
@@ -410,6 +440,8 @@ def render_capabilities(*, fmt: str = "text", root: str | pathlib.Path = ".") ->
     for cap, version in installed:
         lines.append(f"  {cap.distribution:<32} {version:<10} {cap.kind}")
         lines.append(f"      {cap.summary}")
+        if cap.inventory is not None:
+            lines.append(f"      what this app has: uv run {cap.inventory}")
         missing = unwired.get(cap.name, ())
         if missing:
             lines.append(f"      not used here: {', '.join(missing)}")