terp-cli 0.1.0__py3-none-any.whl

terp/cli/dev.py

@@ -0,0 +1,145 @@
+"""``terp dev`` — run the backend and frontend dev servers together (with an OpenAPI preflight).
+
+The full-stack dev loop of design §7: one command boots the API (uvicorn ``--reload``) and the
+frontend dev server side by side, after refreshing the OpenAPI document the frontend contract is
+generated from — so the typed client's source is current before the servers start. A repo with no
+``frontend/`` directory (a backend-only app) runs just the API server.
+
+The command is a pure planner (:func:`dev_plan`, which computes the two process commands) plus a
+thin executor (:func:`run_dev_command`) with the process spawn/supervise primitives injected, so
+the orchestration is fully testable without launching real servers.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from terp.cli.openapi import export_openapi
+
+_POLL_SECONDS = 0.2
+
+
+@dataclass(frozen=True)
+class DevCommand:
+    """One dev process: a label, the argv to launch, and its working directory."""
+
+    label: str
+    argv: tuple[str, ...]
+    cwd: pathlib.Path
+
+
+def dev_plan(
+    *,
+    app_ref: str = "app.main:app",
+    root: str | pathlib.Path = ".",
+    frontend_dir: str = "frontend",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+) -> tuple[DevCommand, DevCommand]:
+    """Pure: the ``(backend, frontend)`` commands ``terp dev`` runs.
+
+    Backend = ``uvicorn <app_ref> --reload`` from the project root; frontend = ``npm run dev``
+    from ``<root>/<frontend_dir>`` (the copier template + example layout). The frontend command
+    is returned unconditionally; the executor runs it only when its directory exists.
+    """
+    root_path = pathlib.Path(root).resolve()
+    backend = DevCommand(
+        label="backend",
+        argv=(
+            sys.executable,
+            "-m",
+            "uvicorn",
+            app_ref,
+            "--reload",
+            "--host",
+            host,
+            "--port",
+            str(port),
+        ),
+        cwd=root_path,
+    )
+    frontend = DevCommand(
+        label="frontend",
+        argv=("npm", "run", "dev"),
+        cwd=root_path / frontend_dir,
+    )
+    return backend, frontend
+
+
+Spawn = Callable[[DevCommand], "subprocess.Popen[bytes]"]
+Supervise = Callable[[Sequence["subprocess.Popen[bytes]"]], None]
+
+
+def _spawn(command: DevCommand) -> subprocess.Popen[bytes]:
+    """Start one dev process, resolving its executable on PATH (so ``npm`` works on Windows)."""
+    executable = shutil.which(command.argv[0]) or command.argv[0]
+    # The argv is an internally composed dev command (uvicorn / npm from dev_plan), run with
+    # shell=False, so there is no shell interpolation of untrusted input.
+    return subprocess.Popen(  # noqa: S603 - internal dev argv, shell=False (no injection)
+        (executable, *command.argv[1:]), cwd=command.cwd
+    )
+
+
+def _supervise(
+    processes: Sequence[subprocess.Popen[bytes]],
+    *,
+    sleep: Callable[[float], None] = time.sleep,
+) -> None:
+    """Block until one process exits, then terminate the rest (a crash or Ctrl+C stops both)."""
+    while all(process.poll() is None for process in processes):
+        sleep(_POLL_SECONDS)
+    for process in processes:
+        if process.poll() is None:
+            process.terminate()
+
+
+def run_dev_command(
+    *,
+    app_ref: str = "app.main:app",
+    root: str | pathlib.Path = ".",
+    frontend_dir: str = "frontend",
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    openapi_out: str = "openapi.json",
+    preflight: bool = True,
+    export: Callable[..., pathlib.Path] = export_openapi,
+    spawn: Spawn = _spawn,
+    supervise: Supervise = _supervise,
+) -> str:
+    """Run the backend + frontend dev servers together, after an OpenAPI preflight.
+
+    The preflight writes the live app's OpenAPI document (the frontend contract's codegen source)
+    so the typed client is current before the servers start; pass ``preflight=False`` to skip it.
+    uvicorn (``--reload``) and the frontend dev server then run side by side until one exits or is
+    interrupted, when the other is stopped too. A repo without ``<frontend_dir>/`` runs backend-only.
+
+    *export* / *spawn* / *supervise* are injected so the orchestration is testable without launching
+    real servers. Returns a one-line summary of what was stopped.
+    """
+    root_path = pathlib.Path(root).resolve()
+    backend, frontend = dev_plan(
+        app_ref=app_ref, root=root_path, frontend_dir=frontend_dir, host=host, port=port
+    )
+    if preflight:
+        destination = export(app_ref, out=root_path / openapi_out, app_root=root_path)
+        print(f"terp dev — OpenAPI preflight wrote {destination}")
+
+    commands = [backend]
+    if frontend.cwd.is_dir():
+        commands.append(frontend)
+    for command in commands:
+        print(f"  {command.label:8} → {' '.join(command.argv)}  (cwd {command.cwd})")
+
+    processes = [spawn(command) for command in commands]
+    supervise(processes)
+    ran = " + ".join(command.label for command in commands)
+    return f"terp dev stopped ({ran})"
+
+
+__all__ = ["DevCommand", "dev_plan", "run_dev_command"]

terp/cli/docker.py

@@ -0,0 +1,57 @@
+"""``terp docker dev`` — the full-stack workbench: Postgres + backend + frontend via Compose watch.
+
+Wraps ``docker compose -f <file> watch`` (Compose v2.22+): it brings up the database, runs the
+one-shot migrate + seed, starts the API (uvicorn) and the frontend (Vite), and live-syncs source
+into the running containers. One command from a checkout to a seeded, running app.
+
+A pure planner (:func:`docker_dev_argv`) plus a thin executor (:func:`run_docker_dev_command`)
+with the process runner injected, so the orchestration is testable without Docker.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import shutil
+import subprocess
+from collections.abc import Callable, Sequence
+
+_DEFAULT_COMPOSE = "docker-compose.yml"
+
+Runner = Callable[[Sequence[str]], int]
+
+
+def docker_dev_argv(
+    compose_file: str | pathlib.Path, *, project_name: str | None = None
+) -> tuple[str, ...]:
+    """The ``docker compose`` argv that runs the workbench with file-watching."""
+    argv = ["docker", "compose", "-f", str(compose_file)]
+    if project_name:
+        argv += ["-p", project_name]
+    argv.append("watch")
+    return tuple(argv)
+
+
+def _run(argv: Sequence[str]) -> int:
+    """Run *argv*, resolving the executable on PATH (so ``docker`` works on Windows)."""
+    executable = shutil.which(argv[0]) or argv[0]
+    return subprocess.call([executable, *argv[1:]])  # noqa: S603 - fixed argv, shell=False
+
+
+def run_docker_dev_command(
+    *,
+    compose_file: str = _DEFAULT_COMPOSE,
+    root: str | pathlib.Path = ".",
+    project_name: str | None = None,
+    runner: Runner | None = None,
+) -> str:
+    """Resolve the compose file under *root* and run ``docker compose watch``.
+
+    A missing compose file fails closed with a clean CLI error. *runner* is injected in tests so
+    the orchestration is verified without Docker; it returns the exit status of the watch process.
+    """
+    candidate = pathlib.Path(compose_file)
+    path = candidate if candidate.is_absolute() else pathlib.Path(root).resolve() / candidate
+    if not path.is_file():
+        raise SystemExit(f"compose file not found: {path} (looked under --root {root!r})")
+    status = (runner or _run)(docker_dev_argv(path, project_name=project_name))
+    return f"docker compose watch exited with status {status}"

terp/cli/jobs.py

@@ -0,0 +1,238 @@
+"""``terp jobs`` — run a job (the external-scheduler trigger) and inspect the catalog.
+
+The jobs seam (ADR 0043) is driven from the CLI two ways:
+
+* ``terp jobs run <name> --payload <json>`` is the most abstract possible scheduler —
+  any cron / k8s CronJob / systemd timer / Azure timer invokes it, so a scheduled job
+  works today with zero broker infra. It builds the app (so ``create_app`` has configured
+  the live :class:`~terp.core.JobCatalog` + queue), resolves the named job, validates the
+  JSON payload against its schema, and enqueues it through the typed
+  :func:`terp.core.enqueue` chokepoint.
+* ``terp jobs list`` / ``terp inspect jobs`` render the registered jobs straight from the
+  control plane's catalog (like ``terp inspect control-plane`` renders the authority map),
+  so the listing is generated and cannot drift from what the app actually runs.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import json
+import pathlib
+import sys
+
+from fastapi import FastAPI
+
+from terp.core import ControlPlane, enqueue
+from terp.core.db import get_session
+from terp.core.jobs import active_job_catalog
+
+
+def _load_control_plane(dotted: str) -> ControlPlane:
+    """Resolve a ``module:attribute`` reference to a :class:`~terp.core.ControlPlane`."""
+    module_name, _, attr = dotted.partition(":")
+    if not module_name:
+        raise SystemExit(f"{dotted!r} is not a valid 'module:attribute' reference")
+    module = importlib.import_module(module_name)
+    candidate = getattr(module, attr or "control_plane")
+    if not isinstance(candidate, ControlPlane):
+        raise SystemExit(f"{dotted!r} did not resolve to a terp.core.ControlPlane instance")
+    return candidate
+
+
+def _load_app(dotted: str) -> FastAPI:
+    """Resolve a ``module:attribute`` reference to a FastAPI app (instance or factory).
+
+    Building the app runs ``create_app``, which configures the live job catalog + queue —
+    so ``terp jobs run`` enqueues against exactly what the app would run. Mirrors the
+    ``terp openapi`` loader.
+    """
+    module_name, _, attr = dotted.partition(":")
+    if not module_name:
+        raise SystemExit(f"{dotted!r} is not a valid 'module:attribute' reference")
+    module = importlib.import_module(module_name)
+    candidate = getattr(module, attr or "app")
+    if isinstance(candidate, FastAPI):
+        return candidate
+    if callable(candidate):
+        built = candidate()
+        if isinstance(built, FastAPI):
+            return built
+    raise SystemExit(f"{dotted!r} did not resolve to a FastAPI application")
+
+
+def render_jobs(dotted: str = "control_plane:control_plane") -> str:
+    """Render the control plane's registered jobs (the ``jobs list`` / ``inspect jobs`` view).
+
+    Generated from the live :class:`~terp.core.JobCatalog`, so it always matches what the
+    app declares — name, routing queue, retry budget, and visibility — plus the configured
+    system actor a user-less job runs as.
+    """
+    plane = _load_control_plane(dotted)
+    lines = ["Jobs"]
+    if not plane.jobs.jobs:
+        lines.append("  <none declared>")
+    for job in sorted(plane.jobs.jobs, key=lambda item: item.name):
+        lines.append(
+            f"  {job.name}  queue={job.queue}  visibility={job.visibility.value}  "
+            f"retry={job.retry.max_attempts}x"
+        )
+    if plane.job_system_actor_id is not None:
+        lines.append("")
+        lines.append(f"System actor: {plane.job_system_actor_id}")
+    return "\n".join(lines)
+
+
+def run_job_command(
+    name: str,
+    *,
+    payload: str = "{}",
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+) -> str:
+    """Build *app_ref*, resolve job *name*, validate *payload* JSON, and enqueue it.
+
+    *app_root* is placed first on ``sys.path`` so the app package imports when ``terp`` runs
+    as an installed console script. An unknown job name or malformed JSON fails closed with
+    a ``SystemExit`` (a clean CLI error), and the payload is validated against the job's
+    schema before enqueuing, so a bad trigger never reaches a handler.
+    """
+    root = str(pathlib.Path(app_root).resolve())
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    _load_app(app_ref)
+    job = active_job_catalog().get(name)
+    if job is None:
+        raise SystemExit(
+            f"job {name!r} is not registered in the app's JobCatalog; "
+            f"run `terp jobs list` to see the declared jobs"
+        )
+    try:
+        data = json.loads(payload)
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"--payload is not valid JSON: {exc}") from exc
+    payload_obj = job.payload_schema.model_validate(data)
+    with contextlib.closing(get_session()) as gen:
+        session = next(gen)
+        job_id = enqueue(session, job=job, payload=payload_obj)
+    return f"enqueued {name!r} (job id {job_id})"
+
+
+def run_worker_command(
+    *,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+    max_cycles: int | None = None,
+    batch_size: int = 10,
+    lease_seconds: float = 30.0,
+) -> str:
+    """Build *app_ref*, then drain the durable outbox until empty (or *max_cycles*).
+
+    The worker-container entrypoint (ADR 0045). Building the app runs ``create_app``, so the
+    live :class:`~terp.core.JobCatalog` is configured (the worker's ``run_job`` resolves each
+    job by name) and the durable :class:`~terp.capabilities.outbox.OutboxJobQueue` is wired.
+    It then leases due ``outbox_message`` rows, runs jobs through the context-binding kernel
+    runner and events through the in-process handlers, and retries / dead-letters per each
+    job's :class:`~terp.core.RetryPolicy`. ``SKIP LOCKED`` is enabled automatically on
+    PostgreSQL; on SQLite the portable atomic-UPDATE lease is used. Requires the
+    ``terp-cap-outbox`` capability (an app wiring the durable queue already depends on
+    it; a standalone worker image installs ``terp-cli[worker]`` or the combined
+    ``terp-cli[jobs]`` extra).
+    """
+    root = str(pathlib.Path(app_root).resolve())
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    _load_app(app_ref)
+
+    from sqlmodel import Session
+
+    try:
+        from terp.capabilities.outbox import OutboxWorker
+    except ImportError as exc:
+        raise SystemExit(
+            "terp jobs worker requires the terp-cap-outbox capability, which is not "
+            "installed. Add terp-cap-outbox to the app's dependencies (wiring the "
+            "durable OutboxJobQueue already requires it) or install `terp-cli[worker]` "
+            "(or `terp-cli[jobs]` for worker + scheduler support)."
+        ) from exc
+    from terp.core._internal.engine import get_engine
+
+    engine = get_engine()
+    worker = OutboxWorker(
+        lambda: Session(engine),
+        batch_size=batch_size,
+        lease_seconds=lease_seconds,
+        skip_locked=engine.dialect.name == "postgresql",
+    )
+    result = worker.run(max_cycles=max_cycles)
+    return (
+        f"outbox worker drained: claimed={result.claimed} dispatched={result.dispatched} "
+        f"retried={result.retried} dead-lettered={result.dead_lettered} lost={result.lost}"
+    )
+
+
+def _default_scheduler() -> object:
+    """Build the default scheduler process: a blocking APScheduler wrapped by the adapter.
+
+    A dedicated ``terp jobs scheduler`` process runs APScheduler's ``BlockingScheduler`` (its
+    ``start`` blocks the main thread), driving each schedule's tick through the jobs seam.
+    Requires the ``terp-cap-scheduler-apscheduler`` capability.
+    """
+    from sqlmodel import Session
+
+    try:
+        from apscheduler.schedulers.blocking import BlockingScheduler
+
+        from terp.capabilities.scheduler_apscheduler import ApschedulerScheduler
+    except ImportError as exc:
+        raise SystemExit(
+            "terp jobs scheduler requires the terp-cap-scheduler-apscheduler "
+            "capability, which is not installed. Add terp-cap-scheduler-apscheduler "
+            "to the app's dependencies, install `terp-cli[scheduler]` (or the combined "
+            "`terp-cli[jobs]` extra), or run schedules with Celery beat."
+        ) from exc
+    from terp.core._internal.engine import get_engine
+
+    engine = get_engine()
+    return ApschedulerScheduler(lambda: Session(engine), scheduler=BlockingScheduler())
+
+
+def run_scheduler_command(
+    *,
+    app_ref: str = "app.main:app",
+    app_root: str | pathlib.Path = ".",
+    scheduler: object | None = None,
+) -> str:
+    """Build *app_ref*, then run the in-process scheduler until stopped (the scheduler entrypoint).
+
+    The scheduler-process entrypoint deferred from ADR 0048: building the app runs ``create_app``,
+    so the live :class:`~terp.core.ScheduleCatalog` (and the :class:`~terp.core.JobCatalog` its
+    jobs resolve against) is configured. It registers every declared schedule with an
+    APScheduler-backed :class:`~terp.core.Scheduler` and starts it — each cron tick fires the
+    schedule through the typed :func:`~terp.core.enqueue` chokepoint, so a scheduled job flows
+    through the active :class:`~terp.core.JobQueue` (run it off-request with ``terp jobs worker``
+    when the durable outbox is wired). ``start`` **blocks** until the process is stopped (SIGINT).
+    *scheduler* is injectable for tests; the default wraps a blocking APScheduler and requires the
+    ``terp-cap-scheduler-apscheduler`` capability.
+    """
+    root = str(pathlib.Path(app_root).resolve())
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    _load_app(app_ref)
+
+    from terp.core.scheduling import active_schedule_catalog
+
+    catalog = active_schedule_catalog()
+    scheduler = scheduler if scheduler is not None else _default_scheduler()
+    scheduler.register_all(catalog)
+    names = ", ".join(catalog.names()) or "<none>"
+    scheduler.start()  # blocks until the process is stopped (a long-running daemon)
+    return f"scheduler stopped; {len(catalog.schedules)} schedule(s) registered: {names}"
+
+
+__all__ = [
+    "render_jobs",
+    "run_job_command",
+    "run_scheduler_command",
+    "run_worker_command",
+]

terp/cli/openapi.py

@@ -0,0 +1,67 @@
+"""``terp openapi`` — export the app's OpenAPI document for the frontend contract.
+
+The frontend contract's API client is *generated* from the backend OpenAPI (design
+§7.1), so the two can never drift. This command writes that document straight from the
+live FastAPI app — the same object ``create_app`` returns — into a JSON file the
+frontend codegen consumes. It is the Python-side seam of Phase 4: no hand-rolled fetch
+client and no second, hand-maintained schema (ADR 0041).
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import pathlib
+import sys
+from typing import Any
+
+from fastapi import FastAPI
+
+
+def _load_app(dotted: str) -> FastAPI:
+    """Resolve a ``module:attribute`` reference to a FastAPI application.
+
+    Accepts either an app instance (``app.main:app``) or a zero-argument factory that
+    returns one (``app.main:build``), mirroring uvicorn's ``--factory`` convention.
+    """
+    module_name, _, attr = dotted.partition(":")
+    if not module_name:
+        raise SystemExit(f"{dotted!r} is not a valid 'module:attribute' reference")
+    module = importlib.import_module(module_name)
+    candidate = getattr(module, attr or "app")
+    if isinstance(candidate, FastAPI):
+        return candidate
+    if callable(candidate):
+        built = candidate()
+        if isinstance(built, FastAPI):
+            return built
+    raise SystemExit(f"{dotted!r} did not resolve to a FastAPI application")
+
+
+def export_openapi(
+    app_ref: str = "app.main:app",
+    *,
+    out: str | pathlib.Path = "openapi.json",
+    app_root: str | pathlib.Path = ".",
+) -> pathlib.Path:
+    """Write *app_ref*'s OpenAPI document to *out* as JSON; return the path.
+
+    *app_root* is placed first on ``sys.path`` so the app package imports when ``terp``
+    runs as an installed console script (where the working directory is not on the path).
+    The output is sorted and indented, so a regenerated contract diffs cleanly.
+    """
+    root = str(pathlib.Path(app_root).resolve())
+    if root not in sys.path:
+        sys.path.insert(0, root)
+    app = _load_app(app_ref)
+    spec: dict[str, Any] = app.openapi()
+    destination = pathlib.Path(out)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    # newline="\n" keeps the generated artifact byte-stable across platforms, so a
+    # committed, drift-checked contract does not flip to CRLF when regenerated on Windows.
+    destination.write_text(
+        json.dumps(spec, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+        newline="\n",
+    )
+    return destination

terp/cli/profiles.py

@@ -0,0 +1,148 @@
+"""Permission profiles — named access models that compile to Terp primitives.
+
+A profile is a **preset, never a new mechanism**: choosing one only decides which
+existing, enforced primitives the scaffold composes — ``Policy`` for module /
+endpoint access, model traits (``OwnedMixin`` / ``TenantScopedMixin``) for the
+data layer, and the matching service base. The result is ordinary Terp code the
+architecture gate checks like any hand-written module, and the access graph
+(``terp inspect access``) renders exactly what was generated — the profile is
+the UX layer; the typed declarations remain the enforceable contract.
+
+Profiles are deliberately few and composable-by-name (a Studio can present them
+as answers to "who can see / edit these records?"):
+
+- ``shared``          authenticated app-wide rows; read VIEWER, write EDITOR
+- ``role-gated``      like ``shared`` but mutations require ADMIN
+- ``owner-private``   the creator owns each row; only the owner may update/delete
+- ``tenant-private``  rows are isolated per tenant (reads filtered, writes stamped)
+- ``tenant-owner``    tenant isolation + per-row owner write gate
+
+Anything richer (a named ``Permission`` grant, a team/ACL predicate) starts from
+one of these and layers the existing seams on top — see ``terp guide access``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ModuleProfile:
+    """One named permission profile the scaffold can compile to primitives."""
+
+    name: str
+    summary: str
+    #: names imported from ``terp.core`` in the generated ``module.py``
+    policy_imports: tuple[str, ...]
+    #: the ``Policy`` expression placed on the generated ``ModuleSpec``
+    policy_expr: str
+    #: extra ``terp.core`` names mixed into the generated table model
+    core_model_mixins: tuple[str, ...] = ()
+    #: extra import lines for the generated ``models.py`` (capability mixins)
+    model_import_lines: tuple[str, ...] = ()
+    #: extra class names (from *model_import_lines*) mixed into the model
+    capability_model_mixins: tuple[str, ...] = ()
+    #: the service base class name for the generated ``service.py``
+    service_base: str = "BaseService"
+    #: the import line providing *service_base*
+    service_import_line: str = "from terp.core import BaseService"
+    #: extra scaffold follow-up notes (wiring the profile depends on)
+    notes: tuple[str, ...] = field(default_factory=tuple)
+
+    @property
+    def model_mixins(self) -> tuple[str, ...]:
+        """Every mixin the generated model composes, in declaration order."""
+        return self.core_model_mixins + self.capability_model_mixins
+
+
+PROFILES: dict[str, ModuleProfile] = {
+    "shared": ModuleProfile(
+        name="shared",
+        summary="Authenticated shared workspace: read VIEWER, write EDITOR (Policy.default()).",
+        policy_imports=("ModuleSpec", "Policy"),
+        policy_expr="Policy.default()",
+    ),
+    "role-gated": ModuleProfile(
+        name="role-gated",
+        summary="Reads for every authenticated VIEWER; mutations require ADMIN.",
+        policy_imports=("ADMIN", "VIEWER", "ModuleSpec", "Policy"),
+        policy_expr="Policy(read=VIEWER, write=ADMIN)",
+    ),
+    "owner-private": ModuleProfile(
+        name="owner-private",
+        summary=(
+            "The creator owns each row: BaseService stamps owner_id on create and "
+            "refuses a non-owner update/delete (OwnedMixin, ADR 0029)."
+        ),
+        policy_imports=("ModuleSpec", "Policy"),
+        policy_expr="Policy.default()",
+        core_model_mixins=("OwnedMixin",),
+        notes=(
+            "OwnedMixin gates writes only; to also hide other owners' rows from reads,"
+            " register a scope predicate (terp guide ownership).",
+        ),
+    ),
+    "tenant-private": ModuleProfile(
+        name="tenant-private",
+        summary=(
+            "Rows are isolated per tenant: every read is filtered to the current "
+            "tenant and create stamps tenant_id (TenantScopedMixin + TenantScopedService)."
+        ),
+        policy_imports=("ModuleSpec", "Policy"),
+        policy_expr="Policy.default()",
+        model_import_lines=("from terp.capabilities.tenancy import TenantScopedMixin",),
+        capability_model_mixins=("TenantScopedMixin",),
+        service_base="TenantScopedService",
+        service_import_line="from terp.capabilities.tenancy import TenantScopedService",
+        notes=(
+            "Wire the tenant context at the composition root:"
+            " create_app(..., middleware=[Middleware(TenantMiddleware, ...)])"
+            " (terp guide tenancy).",
+        ),
+    ),
+    "tenant-owner": ModuleProfile(
+        name="tenant-owner",
+        summary=(
+            "Tenant isolation plus a per-row owner write gate: reads are tenant-"
+            "filtered, and only a row's owner may update/delete it."
+        ),
+        policy_imports=("ModuleSpec", "Policy"),
+        policy_expr="Policy.default()",
+        core_model_mixins=("OwnedMixin",),
+        model_import_lines=("from terp.capabilities.tenancy import TenantScopedMixin",),
+        capability_model_mixins=("TenantScopedMixin",),
+        service_base="TenantScopedService",
+        service_import_line="from terp.capabilities.tenancy import TenantScopedService",
+        notes=(
+            "Wire the tenant context at the composition root (terp guide tenancy).",
+            "OwnedMixin gates writes only; register a scope predicate for owner-"
+            "filtered reads (terp guide ownership).",
+        ),
+    ),
+}
+
+DEFAULT_PROFILE = "shared"
+
+
+def profile_names() -> tuple[str, ...]:
+    """Every profile name, sorted — the CLI ``choices`` source of truth."""
+    return tuple(sorted(PROFILES))
+
+
+def get_profile(name: str) -> ModuleProfile:
+    """Resolve *name* to a profile, failing closed with the valid choices."""
+    try:
+        return PROFILES[name]
+    except KeyError:
+        raise SystemExit(
+            f"unknown profile {name!r}: choose one of {', '.join(profile_names())}"
+        ) from None
+
+
+__all__ = [
+    "DEFAULT_PROFILE",
+    "PROFILES",
+    "ModuleProfile",
+    "get_profile",
+    "profile_names",
+]