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

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

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

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

@@ -4,18 +4,18 @@ build-backend = "hatchling.build"
 
 [project]
 name = "terp-cli"
-version = "0.27.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.27.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.27.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.27.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.27.0"]
-scheduler = ["terp-cap-scheduler-apscheduler==0.27.0"]
+worker = ["terp-cap-outbox==0.28.0"]
+scheduler = ["terp-cap-scheduler-apscheduler==0.28.0"]
 jobs = [
-    "terp-cap-outbox==0.27.0",
-    "terp-cap-scheduler-apscheduler==0.27.0",
+    "terp-cap-outbox==0.28.0",
+    "terp-cap-scheduler-apscheduler==0.28.0",
 ]
 
 [project.scripts]

{terp_cli-0.27.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`.
 
@@ -1759,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
@@ -1784,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": """\
@@ -3578,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(
@@ -3932,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.27.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",
@@ -106,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",
@@ -130,6 +144,7 @@ CAPABILITIES: tuple[Capability, ...] = (
         kind="library",
         wiring="create_app(..., lease_store=DatabaseLeaseStore()) + specs=[leases.module]",
         guide="leases",
+        inventory="terp leases list",
     ),
     Capability(
         name="mail",
@@ -385,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, ())),
@@ -424,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)}")