terp-cli 0.22.0__tar.gz → 0.23.0__tar.gz

{terp_cli-0.22.0 → terp_cli-0.23.0}/PKG-INFO

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

{terp_cli-0.22.0 → terp_cli-0.23.0}/pyproject.toml

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

{terp_cli-0.22.0 → terp_cli-0.23.0}/src/terp/cli/__init__.py

@@ -60,6 +60,7 @@ from terp.cli.service_accounts import create_service_account_command
 from terp.cli.users import create_user_command
 from terp.cli.envfile import run_env_command
 from terp.cli.outbox import render_backlog
+from terp.cli.ports import run_ports_command
 from terp.cli.verify import (
     profile_ids,
     run_verify_command,
@@ -575,7 +576,17 @@ Stored references (Ref + OnDelete)
       RESTRICT     the parent must not vanish underneath this row (a ledger entry)
       SET NULL     a pointer allowed to go slack (an optional assignee) -- nullable
       SET_DEFAULT  point at the column default instead (that default must exist)
-      NO_ACTION    the database takes none; something above it owns this lifecycle
+      NO_ACTION    the database corrects nothing; something above it owns this
+                   lifecycle -- it still REFUSES a delete that would orphan a row
+- NO_ACTION STILL REFUSES. It means the database takes no corrective action, not that
+  it stands aside: the foreign key is enforced either way, and NO ACTION differs from
+  RESTRICT only in deferrability, never in whether the parent delete is blocked. So
+  against a HARD-deletable parent, expect the refusal and plan for it -- BaseService
+  turns it into the uniform 409 ConflictError, the same envelope as any other
+  integrity conflict, so you do not map it. Clear the children first; the _after_write
+  recipe below runs BEFORE the parent row is deleted, which is exactly what makes that
+  ordering work. (Against a soft-deletable target none of this can fire at all -- see
+  the SOFT-DELETE note below, where NO_ACTION really does mean nothing happens.)
 - NO_ACTION is a real answer, not a cop-out, and it emits NO clause at all. Two
   consequences worth knowing: adopting the declaration on an existing schema costs
   no migration (the DDL is unchanged, only the source now says the silence was
@@ -1375,6 +1386,21 @@ 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.
+- ADDING A NOT NULL COLUMN is the revision that passes everything you can run and then
+  fails in production. For a new non-nullable field autogenerate writes
+  `add_column(sa.Column('rank', sa.Integer(), nullable=False))`, and that statement
+  succeeds against an empty database and fails against one that holds rows - the rows
+  already there need a value it never supplies. Nothing local catches it, because a
+  migration test upgrades a FRESH scratch database, where the statement is correct.
+  Give the column a server_default and the database back-fills the existing rows as it
+  adds it; new rows still take the model-side default:
+      op.add_column('note', sa.Column('rank', sa.Integer(), nullable=False,
+                                      server_default='0'))
+  Where no literal default is right, expand/contract instead - add the column nullable,
+  back-fill it in the same release, tighten it in a LATER revision. `terp check`
+  refuses the unbackfilled form (`not_null_columns_are_backfilled`); a table that
+  genuinely holds no rows yet opts out with
+  `# arch-allow-not-null-columns-are-backfilled: <reason>`.
 - 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
@@ -1859,6 +1885,28 @@ not concatenate sequences), so both files have to be listed.
 _GENERATED_TOPICS: tuple[str, ...] = ("changelog", "rules")
 
 _RULE_GUIDE_DETAILS: dict[str, str] = {
+     "not_null_columns_are_backfilled": """\
+Compliant decision path for a new NOT NULL column
+
+1. Decide what the rows that already exist should hold. That is the whole question;
+    the statement fails precisely because it never answers it.
+2. When a literal answers it, give the column a server_default. The database writes it
+    into every existing row as it adds the column, and new rows still take the
+    model-side default:
+        op.add_column('note', sa.Column('rank', sa.Integer(), nullable=False,
+                                        server_default='0'))
+3. When no literal is right - the value has to be computed, or looked up - use
+    expand/contract across two releases: add the column NULLABLE, back-fill it (a data
+    migration or a backfill job), and tighten it to NOT NULL in a LATER revision, once
+    nothing writes a NULL.
+4. Do not make the column nullable in the model merely to silence this. The model is
+    the contract; if the field is genuinely optional, say so there and the finding goes
+    away on its own.
+5. Opt out only for a table that genuinely holds no rows in any environment - a table
+    this release introduces, or one seeded from empty - with
+    `# arch-allow-not-null-columns-are-backfilled: <reason>` naming which. A table
+    created in the same upgrade() needs no marker; it is already exempt.
+""",
      "no_raw_outbound_http": """\
 Compliant decision path for outbound HTTP
 
@@ -2627,10 +2675,11 @@ def _build_parser() -> argparse.ArgumentParser:
     )
     access_parser.add_argument(
         "--format",
-        choices=("text", "json"),
+        choices=("text", "json", "surface"),
         default="text",
-        help="Output format: text (human) or json (structured, for any tool or agent "
-        "reading this; default: text)",
+        help="Output format: text (human), json (structured, for any tool or agent "
+        "reading this), or surface (the authority baseline the authz-surface check "
+        "pins — redirect it to authz-surface.json; default: text)",
     )
     capabilities_parser = inspect_subcommands.add_parser(
         "capabilities",
@@ -2816,6 +2865,33 @@ def _build_parser() -> argparse.ArgumentParser:
     env_unset_parser.add_argument(
         "--root", default=".", help="Project root (default: .)"
     )
+    ports_parser = subcommands.add_parser(
+        "ports",
+        help="The host ports this checkout owns, recorded where every starter reads them",
+    )
+    ports_subcommands = ports_parser.add_subparsers(
+        dest="ports_command", required=True
+    )
+    for _name, _help in (
+        ("show", "This checkout's claim, and whether .env publishes it"),
+        ("release", "Drop the claim and remove the published block"),
+        ("list", "Every host-port claim recorded on this machine"),
+    ):
+        _sub = ports_subcommands.add_parser(_name, help=_help)
+        _sub.add_argument("--root", default=".", help="Project root (default: .)")
+    ports_assign_parser = ports_subcommands.add_parser(
+        "assign",
+        help="Claim a free pair and publish it into .env, in one act",
+    )
+    ports_assign_parser.add_argument(
+        "--root", default=".", help="Project root (default: .)"
+    )
+    ports_assign_parser.add_argument(
+        "--reassign",
+        action="store_true",
+        help="Pick a new pair even if one is already claimed or published",
+    )
+
     outbox_parser = subcommands.add_parser(
         "outbox",
         help="Report the durable outbox's backlog - whether anything is draining it",
@@ -3375,6 +3451,14 @@ def main(argv: Sequence[str] | None = None) -> None:
                 declare=getattr(args, "declare", False),
             )
         )
+    if args.command == "ports":
+        raise SystemExit(
+            run_ports_command(
+                action=args.ports_command,
+                root=args.root,
+                reassign=getattr(args, "reassign", False),
+            )
+        )
     if args.command == "outbox" and args.outbox_command == "backlog":
         print(
             render_backlog(

{terp_cli-0.22.0 → terp_cli-0.23.0}/src/terp/cli/access.py

@@ -402,7 +402,16 @@ def _render_access_text(graph: dict[str, object]) -> str:
 
 
 def render_access_graph(graph: dict[str, object], fmt: str = "text") -> str:
-    """Render a prebuilt access *graph* as ``text`` or ``json``."""
+    """Render a prebuilt access *graph* as ``text``, ``json`` or ``surface``.
+
+    ``surface`` is the authority baseline the ``authz-surface`` verify check pins
+    (:mod:`terp.cli.authz_surface`): the same projection reduced to what is an
+    authority claim, sorted at every level so the committed file is diffable.
+    """
+    if fmt == "surface":
+        from terp.cli.authz_surface import render_authz_surface
+
+        return render_authz_surface(graph)
     if fmt == "json":
         return json.dumps(graph, indent=2)
     return _render_access_text(graph)

terp_cli-0.23.0/src/terp/cli/authz_surface.py

@@ -0,0 +1,169 @@
+"""``authz-surface`` — the authority baseline, and the drift check that pins it.
+
+The access graph already replays enforcement rather than describing it: every allowance
+in it is :func:`terp.core.module_spec.decide`'s own answer, computed by the same function
+the kernel guard runs (ADR 0121 §4). So the platform can already *say* who may reach
+what, exactly and truthfully, for any composed app.
+
+What nothing did was **notice when that answer changed**. Widening a module's policy from
+a named permission to a role tier, dropping a ``require_permission`` off a route, adding
+an endpoint under a mount whose policy is public — each is a one-line edit, each changes
+who can reach what, and each left every gate green. The projection was emitted for a pane
+and for a CLI, and read by no check.
+
+This is the check. It reduces the graph to the part that is an authority claim, compares
+it against a committed baseline, and reports the difference in the vocabulary of the
+change rather than as a JSON diff: *this route's requirement moved from X to Y*, *this
+module became public*, *this endpoint is new and nothing has reviewed what it requires*.
+
+**Adoption is opt-in and half-adoption is impossible**, the shape ``api-docs-drift``
+settled on: with no committed baseline the check skips with a note naming the command
+that writes one, because upgrading the framework must not turn an app's gate red for a
+feature it never wired. Once the file is tracked, drift is red.
+
+**A widening is never "fixed" by regenerating.** The baseline is a review artifact: the
+diff belongs in a pull request where somebody looks at it and says yes. Regenerating to
+make a red go away converts the control into a formality, which is why the writer is a
+separate, explicit command and never a ``--fix`` on the checker.
+"""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+#: The committed baseline, at the project root beside the other tracked artifacts.
+SURFACE_ARTIFACT = "authz-surface.json"
+
+#: What an app runs once to adopt the check, and again — deliberately, with the diff in
+#: front of a reviewer — to accept a change.
+ADOPT_HINT = "terp inspect access --app app.main:build --format surface > authz-surface.json"
+
+
+def authz_surface(graph: dict[str, Any]) -> dict[str, Any]:
+    """Reduce an access graph to the part that is an authority claim.
+
+    Deliberately **not** the whole graph. The graph carries things that move for honest
+    reasons — a model's traits, the reconciliation's ``omitted_routes``, whatever a
+    future field adds — and a baseline that churned on those would be regenerated
+    reflexively until nobody read the diff. What survives here is what answers "who may
+    reach what": the role ladder, each permission's floor, and per module its policy plus
+    each endpoint's requirement, extra permissions, and per-rung outcome.
+
+    Sorted at every level, because the baseline is a **diffable** artifact: a set
+    rendered in registration order would produce a reviewable diff only by luck.
+    """
+    roles = [
+        {"name": role["name"], "rank": role["rank"]}
+        for role in sorted(graph.get("roles", ()), key=lambda item: item["rank"])
+    ]
+    permissions = [
+        {"name": permission["name"], "min_role": permission["min_role"]}
+        for permission in sorted(
+            graph.get("permissions", ()), key=lambda item: item["name"]
+        )
+    ]
+    modules = [
+        {
+            "name": module["name"],
+            "policy": module.get("policy"),
+            "access": module.get("access"),
+            "endpoints": [
+                {
+                    "path": endpoint["path"],
+                    "methods": sorted(endpoint.get("methods", ())),
+                    "requirement": endpoint["requirement"],
+                    "extra_permissions": sorted(endpoint.get("extra_permissions", ())),
+                    "by_role": {
+                        rung["role"]: rung["reason"]
+                        for rung in endpoint.get("by_role", ())
+                    },
+                }
+                for endpoint in sorted(
+                    module.get("endpoints", ()),
+                    key=lambda item: (item["path"], sorted(item.get("methods", ()))),
+                )
+            ],
+        }
+        for module in sorted(graph.get("modules", ()), key=lambda item: item["name"])
+    ]
+    return {"authz_surface": 1, "roles": roles, "permissions": permissions, "modules": modules}
+
+
+def render_authz_surface(graph: dict[str, Any]) -> str:
+    """The baseline as the bytes a project commits (trailing newline, stable key order)."""
+    return json.dumps(authz_surface(graph), indent=2, sort_keys=True) + "\n"
+
+
+def _endpoints(surface: dict[str, Any]) -> dict[tuple[str, str], dict[str, Any]]:
+    """Every endpoint keyed by ``(path, methods)`` — the identity a diff compares on."""
+    found: dict[tuple[str, str], dict[str, Any]] = {}
+    for module in surface.get("modules", ()):
+        for endpoint in module.get("endpoints", ()):
+            key = (endpoint["path"], ",".join(endpoint.get("methods", ())) or "WS")
+            found[key] = endpoint
+    return found
+
+
+def diff_authz_surface(baseline: dict[str, Any], current: dict[str, Any]) -> list[str]:
+    """Every authority difference, each phrased as the change a reviewer has to approve.
+
+    Ordered most-alarming first — a route that lost its requirement before one that
+    gained a new rung — because the first lines are the ones that get read.
+    """
+    differences: list[str] = []
+
+    before, after = _endpoints(baseline), _endpoints(current)
+    for key in sorted(before.keys() & after.keys()):
+        was, now = before[key], after[key]
+        path, methods = key
+        if was["requirement"] != now["requirement"]:
+            differences.append(
+                f"{methods} {path}: requirement {was['requirement']!r} -> "
+                f"{now['requirement']!r}"
+            )
+        if was.get("extra_permissions") != now.get("extra_permissions"):
+            differences.append(
+                f"{methods} {path}: required grants "
+                f"{was.get('extra_permissions')} -> {now.get('extra_permissions')}"
+            )
+        widened = [
+            role
+            for role, reason in now.get("by_role", {}).items()
+            if reason in {"allowed", "allowed_in_module", "public"}
+            and was.get("by_role", {}).get(role)
+            not in {"allowed", "allowed_in_module", "public"}
+        ]
+        if widened:
+            differences.append(
+                f"{methods} {path}: now reachable by {sorted(widened)} "
+                "(it was not before)"
+            )
+
+    for key in sorted(after.keys() - before.keys()):
+        path, methods = key
+        differences.append(
+            f"{methods} {path}: NEW endpoint, requirement "
+            f"{after[key]['requirement']!r} - nothing has reviewed what it requires"
+        )
+    for key in sorted(before.keys() - after.keys()):
+        path, methods = key
+        differences.append(f"{methods} {path}: gone from the surface")
+
+    # The ladder itself, last: a changed rank silently re-scores every floor above it.
+    if baseline.get("roles") != current.get("roles"):
+        differences.append(
+            f"the role ladder changed: {baseline.get('roles')} -> {current.get('roles')}"
+        )
+    if baseline.get("permissions") != current.get("permissions"):
+        differences.append("the declared permissions or their floors changed")
+    return differences
+
+
+def read_baseline(root: pathlib.Path) -> dict[str, Any] | None:
+    """The committed baseline, or ``None`` when the project has not adopted the check."""
+    path = root / SURFACE_ARTIFACT
+    if not path.is_file():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))

{terp_cli-0.22.0 → terp_cli-0.23.0}/src/terp/cli/docker.py

@@ -28,6 +28,8 @@ import shutil
 import subprocess
 from collections.abc import Callable, Sequence
 
+from terp.cli import ports
+
 _DEFAULT_COMPOSE = "docker-compose.yml"
 
 #: Lines of a failed service's log to show. Enough for a traceback and the line above it;
@@ -209,6 +211,24 @@ def run_docker_dev_command(
         raise SystemExit(
             f"compose file not found: {path} (looked under --root {root!r})"
         )
+    # Before the stack, not after it: the compose file requires its host ports to
+    # be assigned, and this is what makes that requirement invisible to somebody
+    # who has never heard of `terp ports`. One command from a checkout to a
+    # running app, which is the promise this command already makes and the
+    # property ADR 0134 decision 1 refuses to spend in order to enforce decision
+    # 3. Never fatal — `ensure_assigned` reports instead of raising, because a
+    # start that dies over a ledger is worse than one that lets compose speak.
+    #
+    # Assigned beside the COMPOSE FILE, not beside --root. Compose's project
+    # directory defaults to the directory of the first `-f`, and that is the only
+    # `.env` it reads — so publishing into --root would write the assignment into
+    # a file this very command then ignores, and the start would fail on a
+    # required variable that had just been "set". The two coincide in the ordinary
+    # case and part company for an absolute or nested --compose-file, which is
+    # exactly where the mistake would have been silent.
+    _, note = ports.ensure_assigned(path.parent)
+    if note:
+        print(note)
     status = (runner or _run)(docker_dev_argv(path, project_name=project_name))
     message = f"docker compose watch exited with status {status}"
     if status == 0: