mozbridge-cli 0.5.0__tar.gz → 0.6.0__tar.gz

{mozbridge_cli-0.5.0 → mozbridge_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mozbridge-cli
-Version: 0.5.0
+Version: 0.6.0
 Summary: Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge.
 Project-URL: Homepage, https://mozbridge.com
 Project-URL: Documentation, https://github.com/jessin01/mozbridge/blob/main/cli/docs/commands.md

{mozbridge_cli-0.5.0 → mozbridge_cli-0.6.0}/docs/commands.md

@@ -1031,6 +1031,127 @@ result never fails the command.
 
 ---
 
+## `mozbridge adopt` / `mozbridge scaffold`
+
+Both wrap real, already-shipped backend endpoints
+(`POST /api/v1/projects/{project_id}/adopt`,
+`POST /api/v1/projects/{project_id}/scaffold` — D3/D3b in
+`backend/app/features/projects/router.py`, see
+`.llm/plans/plane-config-contract.md`) with **zero backend changes**: each
+renders a `docker-compose.app.yml`, validates it against the platform's D2
+compose contract, and — only if it passes — opens a PR on the project's
+own repo adding the file. This is exactly what `mozbridge doctor`'s
+pre-deploy checks recommend when a project has no declared compose shape
+(`deploy_shape` in `backend/app/services/preflight.py`) — until this
+slice, the CLI had no command that could act on that diagnosis.
+
+Same confirmation weight as `mozbridge rollback`/`deploy`: real but
+reversible (opening a PR touches nothing in production and nothing merges
+automatically), so both print what they're about to do and prompt to
+continue, skippable with `--yes`. **Requires**: link + login, same as
+`env`/`registry`/`config`.
+
+Success for either command means **a PR was opened** — printed on its own
+line, never buried in other output. It does **not** mean anything
+deployed, and it does **not** point the platform at the new file:
+`config.app_compose_file` is a deliberately separate, later, manual step
+(`mozbridge config set app_compose_file <path>`, after reviewing and
+merging the PR).
+
+### `mozbridge adopt`
+
+**Flags**: `--container` (required — name of the LIVE container to
+inspect on the project's bound host, e.g. `origyn-app`), `--service`
+(default `backend`), `--yes`.
+
+**When to use it**: the project already has a container RUNNING
+somewhere with no declared compose shape on disk (Origyn is the concrete
+case this endpoint was built for: 9 real Traefik labels, an `origyn-data`
+volume, port 5001, none of it on disk — and its real container is named
+`origyn-app`, not `origyn-backend`). `--container` has **no guessed
+default** — a project's real container name routinely doesn't match its
+slug, so guessing one would silently point this at the wrong container.
+
+**What it does**: `POST /api/v1/projects/{project_id}/adopt`, body
+`{"container": CONTAINER, "service": SERVICE}`. The backend inspects
+`CONTAINER` LIVE on the project's bound host (image, ports, env, volumes,
+Traefik labels), renders a single-service compose file from what's
+ACTUALLY running, validates it against D2, and opens a PR only if that
+passes.
+
+```
+$ mozbridge adopt --container origyn-app
+This will adopt acme/origyn:
+  container -> 'origyn-app' (inspected LIVE on the project's bound host)
+  service   -> 'backend'
+If the rendered compose file passes the D2 contract, a PR will be opened.
+Continue? [y/N]: y
+PR opened:
+  https://github.com/acme/origyn/pull/42
+```
+
+**Failure modes**:
+- Not linked / not logged in: identical messages to every other command
+  above, exit 1.
+- `--container` not found on the project's host: the backend's own 400
+  message verbatim (`container 'X' not found on <host>: ...`), exit 1.
+- Host unreachable (no usable SSH credential, tunnel failure): the
+  backend's own 400/502 message verbatim, exit 1.
+- Rendered compose file fails D2 validation: **no PR is opened**. Every
+  violation prints on its own line, prefixed by the explicit statement
+  that no PR was opened, exit 1:
+
+  ```
+  $ mozbridge adopt --container origyn-app --yes
+  ...
+  Could not adopt the running container: rendered docker-compose.app.yml failed the D2 compose contract validator
+  No PR was opened. D2 violations:
+    - service 'backend' has no healthcheck
+    - image tag 'latest' is not allowed
+  ```
+
+### `mozbridge scaffold`
+
+**Flags**: `--service` (default `backend`), `--yes`. No `--container` —
+scaffold never inspects a live container.
+
+**When to use it**: a genuinely new project that has never run anywhere.
+There's no live container to inspect (that's `adopt`'s job), so this
+renders a starter compose file from whatever the project's OWN declared
+config already has (`backend_image`/`image_name`, `backend_port`,
+`backend_command`, `data_volumes`, `frontend_image`, `alt_domains` — set
+these first with `mozbridge config set`). Deliberately not run
+automatically at project creation: none of those config keys exist yet
+at that point, so an automatic call here would render a backend-only,
+default-port guess for every project — exactly what this endpoint's
+design rejects.
+
+**What it does**: `POST /api/v1/projects/{project_id}/scaffold`, body
+`{"service": SERVICE}`. Same D2-validate-then-PR pipeline and response
+shape as `adopt` above, reading only `project.config` — no host, no
+docker, no SSH.
+
+```
+$ mozbridge scaffold
+This will scaffold acme/new-app from its own declared config:
+  service -> 'backend'
+If the rendered compose file passes the D2 contract, a PR will be opened.
+Continue? [y/N]: y
+PR opened:
+  https://github.com/acme/new-app/pull/7
+```
+
+**Failure modes**:
+- Not linked / not logged in: exit 1, same messages as every command
+  above.
+- Rendered compose file fails D2 validation: **no PR is opened**, every
+  violation on its own line, exit 1 — identical shape to `adopt`'s
+  example above.
+- Any other backend error (e.g. a 500): the raw `ApiError` message,
+  exit 1.
+
+---
+
 ## A note on authorization for `publish` / `rollback`
 
 Both commands work today because a plain human Logto session token passes

{mozbridge_cli-0.5.0 → mozbridge_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mozbridge-cli"
-version = "0.5.0"
+version = "0.6.0"
 description = "Command-line client for the Mozbridge deployment platform: SSO login, build, publish, status, and rollback for any project hosted on Mozbridge."
 readme = "README.md"
 requires-python = ">=3.10"

{mozbridge_cli-0.5.0 → mozbridge_cli-0.6.0}/src/mozbridge_cli/api.py

@@ -557,6 +557,113 @@ def deploy_project(
     return resp.json()
 
 
+def _raise_on_compose_validation_failure(resp: httpx.Response, action: str) -> None:
+    """Shared 422 handler for adopt_project/scaffold_project.
+
+    Both `POST .../adopt` and `POST .../scaffold`
+    (backend/app/features/projects/router.py) render a docker-compose.app.yml
+    and, if it fails the D2 compose contract validator, respond 422 with
+    `detail={"message": "...", "violations": [...]}` — no PR is opened in
+    that case. This is a genuinely useful discovery (a live/declared spec
+    violating the platform's own guardrails), not a generic failure, so the
+    violations are folded verbatim into the raised ApiError's message rather
+    than collapsed into "422 Unprocessable Entity" — the caller (cmd_adopt.py)
+    just echoes `str(exc)` and every violation prints on its own line.
+
+    Any other non-2xx status falls through to the normal `_raise_for_status`
+    path unchanged.
+    """
+    if resp.status_code != 422:
+        _raise_for_status(resp, action)
+        return
+
+    try:
+        detail = resp.json().get("detail")
+    except ValueError:
+        detail = None
+
+    if not isinstance(detail, dict) or "violations" not in detail:
+        _raise_for_status(resp, action)
+        return
+
+    message = detail.get("message") or (
+        "rendered docker-compose.app.yml failed the D2 compose contract validator"
+    )
+    violations = detail.get("violations") or []
+    lines = [f"Could not {action}: {message}", "No PR was opened. D2 violations:"]
+    lines.extend(f"  - {v}" for v in violations)
+    raise ApiError("\n".join(lines))
+
+
+def adopt_project(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    project_id: int,
+    container: str,
+    service: str = "backend",
+) -> dict:
+    """POST /api/v1/projects/{project_id}/adopt, body {"container", "service"}.
+
+    D3 (`.llm/plans/plane-config-contract.md`) — wraps
+    `router.py`'s `adopt_running_container`: inspects `container` LIVE on the
+    project's bound host, renders a single-service `docker-compose.app.yml`
+    from what's ACTUALLY running, validates it against the D2 compose
+    contract, and — only if that passes — opens a PR adding the file to the
+    project's own repo. Nothing is written anywhere if validation fails (see
+    `_raise_on_compose_validation_failure`).
+
+    `container` has no safe client-side default — e.g. Origyn's real
+    container is `origyn-app`, not a guessed `{slug}-backend` — so callers
+    (cmd_adopt.py) must always pass a real, user-supplied name.
+
+    Returns {"pr_url", "pr_number", "branch", "violations": []} on success
+    (200). Raises ApiError (with violations folded into the message) on a
+    422, or the usual ApiError for any other failure — including a 400 when
+    `container` doesn't exist on the host, or a 502 when the host itself
+    can't be reached.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/adopt"
+    payload = {"container": container, "service": service}
+    try:
+        resp = client.post(url, json=payload, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_on_compose_validation_failure(resp, "adopt the running container")
+    return resp.json()
+
+
+def scaffold_project(
+    client: httpx.Client,
+    access_token: str,
+    org_id: int,
+    project_id: int,
+    service: str = "backend",
+) -> dict:
+    """POST /api/v1/projects/{project_id}/scaffold, body {"service"}.
+
+    D3b (`.llm/plans/plane-config-contract.md`) — wraps
+    `router.py`'s `scaffold_project_compose`: renders a starter
+    `docker-compose.app.yml` from the project's OWN declared config
+    (`backend_image`/`backend_port`/`backend_command`/`data_volumes`/
+    `frontend_image`/`alt_domains` — never a live container, since a
+    brand-new project has none), same D2-validate-then-PR pipeline and
+    response shape as `adopt_project` above.
+
+    Returns {"pr_url", "pr_number", "branch", "violations": []} on success
+    (200). Raises ApiError (with violations folded into the message) on a
+    422, same handling as `adopt_project`.
+    """
+    url = f"{config.API_BASE_URL}{config.PROJECTS_PATH}/{project_id}/scaffold"
+    payload = {"service": service}
+    try:
+        resp = client.post(url, json=payload, headers=_headers(access_token, org_id))
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach Mozbridge API: {exc}") from exc
+    _raise_on_compose_validation_failure(resp, "scaffold the project compose file")
+    return resp.json()
+
+
 def get_project_preflight(client: httpx.Client, access_token: str, org_id: int, project_id: int) -> dict:
     """GET /api/v1/projects/{project_id}/preflight -> preflight.Preflight.as_dict().
 

mozbridge_cli-0.6.0/src/mozbridge_cli/cmd_adopt.py

@@ -0,0 +1,179 @@
+"""`mozbridge adopt` / `mozbridge scaffold` — declare a compose shape for the
+linked project by opening a PR, wrapping two real, already-shipped backend
+endpoints (`POST .../adopt`, `POST .../scaffold` in
+backend/app/features/projects/router.py — D3/D3b,
+`.llm/plans/plane-config-contract.md`) with zero backend changes. Same
+wrapping posture as cmd_registry.py/cmd_config.py/cmd_secrets.py.
+
+`mozbridge doctor`'s "Pre-deploy checks" line already surfaces the gap these
+close: when a project has no declared compose shape (`deploy_shape` in
+backend/app/services/preflight.py), it recommends running one of these two
+endpoints — but until now the CLI had no command that could act on that
+diagnosis. This module is that command.
+
+Two flat, single-verb commands (same tier as `doctor`/`login`), not a nested
+sub-typer — neither has further subcommands, so there's nothing to group.
+
+Confirmation weight: opening a PR is real but reversible — nothing merges
+automatically, nothing touches production — so this matches
+`cmd_deploy.py`'s `rollback`/`deploy` confirmation pattern (print what will
+happen, `typer.confirm`, skippable with `--yes`), not the silent posture of
+`env set`/`config set`.
+
+`adopt` vs `scaffold`, when to use which:
+  - `adopt`: a project already has a container RUNNING somewhere (Origyn is
+    the canonical case — 9 real Traefik labels, a data volume, a port, none
+    of it on disk) and you want the platform to read the REAL shape off that
+    live container and declare it.
+  - `scaffold`: a genuinely new project that has never run anywhere. There is
+    no live container to inspect, so this renders a starter compose file from
+    whatever the project's OWN config already declares
+    (backend_image/backend_port/backend_command/data_volumes/etc).
+
+Success for either command means a PR was opened — NOT that anything
+deployed, and NOT that `config.app_compose_file` was updated to point at the
+new file. Both are deliberately separate, later, manual steps (see the
+backend endpoints' own docstrings).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+import typer
+
+from . import api
+from .cmd_shared import require_link_and_session
+
+app = typer.Typer(add_completion=False)
+
+
+@app.command("adopt")
+def adopt_cmd(
+    container: str = typer.Option(
+        ...,
+        "--container",
+        help=(
+            "Name of the LIVE container to inspect on the project's bound host "
+            "(e.g. origyn-app). Required — there is no safe default to guess "
+            "(a project's real container name routinely doesn't match its slug)."
+        ),
+    ),
+    service: str = typer.Option(
+        "backend", "--service", help="Compose service name to render the adopted shape under."
+    ),
+    yes: bool = typer.Option(False, "--yes", help="Skip the interactive confirmation prompt."),
+) -> None:
+    """Adopt a project that's already running with no declared compose shape.
+
+    Use this when a project has a container RUNNING somewhere (on its bound
+    host) but nothing declaring its shape on disk — the platform inspects
+    `--container` LIVE, renders a single-service `docker-compose.app.yml`
+    from what's ACTUALLY running (image, ports, env, volumes, Traefik
+    labels), validates it against the platform's D2 compose contract, and —
+    only if that passes — opens a PR on the project's own repo adding the
+    file. Requires `mozbridge link` and an active login session.
+
+    This is a real, consequential action (same confirmation weight as
+    `mozbridge rollback`): it inspects a live production container and opens
+    a real PR, though nothing merges automatically and nothing here touches
+    a running deployment. Confirmed unless `--yes` is passed.
+
+    Success means a PR was opened — printed on its own line, impossible to
+    miss. It does NOT mean anything was deployed, and it does NOT point the
+    platform at the new file (`config.app_compose_file` is a separate,
+    later, manual step — see `mozbridge config set`).
+
+    If the rendered compose file fails the platform's D2 compose contract
+    validator, the backend returns each violation instead of opening a PR.
+    This command prints every violation on its own line, states plainly that
+    no PR was opened, and exits 1 — there is nothing to go looking for.
+    """
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=60.0) as client:
+        current_link, active_session = require_link_and_session(client, cwd)
+
+        project_desc = f"{current_link.org_slug}/{current_link.project_slug}"
+        typer.echo(f"This will adopt {project_desc}:")
+        typer.echo(f"  container -> {container!r} (inspected LIVE on the project's bound host)")
+        typer.echo(f"  service   -> {service!r}")
+        typer.echo("If the rendered compose file passes the D2 contract, a PR will be opened.")
+        if not yes:
+            typer.confirm("Continue?", abort=True)
+
+        try:
+            result = api.adopt_project(
+                client,
+                active_session.access_token,
+                current_link.org_id,
+                current_link.project_id,
+                container,
+                service=service,
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    typer.echo("PR opened:")
+    typer.echo(f"  {result.get('pr_url')}")
+
+
+@app.command("scaffold")
+def scaffold_cmd(
+    service: str = typer.Option(
+        "backend", "--service", help="Compose service name to render the scaffolded shape under."
+    ),
+    yes: bool = typer.Option(False, "--yes", help="Skip the interactive confirmation prompt."),
+) -> None:
+    """Scaffold a starter compose shape for a project with no running container.
+
+    Use this for a genuinely new project that has never run anywhere — there
+    is no live container to inspect (that's what `mozbridge adopt` is for).
+    Instead, this renders a starter `docker-compose.app.yml` from whatever
+    the project's OWN declared config already has
+    (backend_image/backend_port/backend_command/data_volumes/frontend_image/
+    alt_domains — see `mozbridge config set` to declare them first),
+    validates it against the platform's D2 compose contract, and — only if
+    that passes — opens a PR on the project's own repo adding the file.
+    Requires `mozbridge link` and an active login session.
+
+    Same confirmation weight as `mozbridge adopt`/`rollback`: real but
+    reversible (nothing merges automatically), confirmed unless `--yes` is
+    passed.
+
+    Success means a PR was opened — printed on its own line. It does NOT
+    mean anything was deployed, and it does NOT point the platform at the
+    new file (`config.app_compose_file` is a separate, later, manual step).
+
+    If the rendered compose file fails the platform's D2 compose contract
+    validator, this command prints every violation on its own line, states
+    plainly that no PR was opened, and exits 1.
+    """
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=30.0) as client:
+        current_link, active_session = require_link_and_session(client, cwd)
+
+        project_desc = f"{current_link.org_slug}/{current_link.project_slug}"
+        typer.echo(f"This will scaffold {project_desc} from its own declared config:")
+        typer.echo(f"  service -> {service!r}")
+        typer.echo("If the rendered compose file passes the D2 contract, a PR will be opened.")
+        if not yes:
+            typer.confirm("Continue?", abort=True)
+
+        try:
+            result = api.scaffold_project(
+                client,
+                active_session.access_token,
+                current_link.org_id,
+                current_link.project_id,
+                service=service,
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    typer.echo("PR opened:")
+    typer.echo(f"  {result.get('pr_url')}")

{mozbridge_cli-0.5.0 → mozbridge_cli-0.6.0}/src/mozbridge_cli/main.py

@@ -1,5 +1,6 @@
 """Mozbridge CLI: login / whoami / logout / link / build / publish / diff / status /
-deploy / rollback / logs / env / registry / secrets / config / token / doctor.
+deploy / rollback / logs / env / registry / secrets / config / token / doctor /
+adopt / scaffold.
 
 macOS-only for v1 (no Windows code paths).
 
@@ -7,16 +8,16 @@ This module is a thin composition root: the root Typer `app` is assembled
 from the command modules below, each of which owns one feature area's
 command definitions (see cmd_auth.py, cmd_projects.py, cmd_publish.py,
 cmd_deploy.py, cmd_env.py, cmd_registry.py, cmd_secrets.py, cmd_config.py,
-cmd_token.py, cmd_doctor.py).
+cmd_token.py, cmd_doctor.py, cmd_adopt.py).
 `app.add_typer(<module>.app)`, called with no explicit `name`, merges a
 nameless sub-Typer's commands flatly into `app` (confirmed against Typer's
 real behavior — see cmd_*.py's own module-level Typer() calls, none of
 which pass `name=` except cmd_env's/cmd_registry's/cmd_secrets's/
 cmd_config's/cmd_token's, which is why `env`/`registry`/`secrets`/
-`config`/`token` stay nested command groups while `doctor` — a single flat
-command, same shape as `login`/`whoami`/`logout` — merges directly into
-`app`). `from mozbridge_cli.main import app` continues to expose every
-command exactly as before.
+`config`/`token` stay nested command groups while `doctor`/`adopt`/
+`scaffold` — single flat commands, same shape as `login`/`whoami`/`logout`
+— merge directly into `app`). `from mozbridge_cli.main import app` continues
+to expose every command exactly as before.
 """
 
 from __future__ import annotations
@@ -24,6 +25,7 @@ from __future__ import annotations
 import typer
 
 from . import (
+    cmd_adopt,
     cmd_auth,
     cmd_config,
     cmd_deploy,
@@ -40,10 +42,10 @@ app = typer.Typer(
     name="mozbridge",
     help=(
         "Mozbridge platform CLI: login, whoami, logout, link, build, publish, diff, "
-        "status, deploy, rollback, logs, env, registry, secrets, config, token, doctor."
+        "status, deploy, rollback, logs, env, registry, secrets, config, token, doctor, "
+        "adopt, scaffold."
     ),
     no_args_is_help=True,
-    add_completion=False,
 )
 
 app.add_typer(cmd_auth.app)
@@ -56,6 +58,7 @@ app.add_typer(cmd_secrets.app, name="secrets")
 app.add_typer(cmd_config.app, name="config")
 app.add_typer(cmd_token.app, name="token")
 app.add_typer(cmd_doctor.app)
+app.add_typer(cmd_adopt.app)
 
 
 def app_main() -> None:

mozbridge_cli-0.6.0/tests/test_adopt.py

@@ -0,0 +1,320 @@
+import json
+import time
+
+import httpx
+import respx
+from typer.testing import CliRunner
+
+from mozbridge_cli import config, session
+from mozbridge_cli.link import Link, save_link
+from mozbridge_cli.main import app
+
+runner = CliRunner()
+
+
+def _seed_session():
+    s = session.Session(
+        access_token="AT-valid",
+        refresh_token="RT-valid",
+        id_token="IDT",
+        expires_at=time.time() + 3600,
+    )
+    session.save_session(s)
+    return s
+
+
+def _seed_link(cwd):
+    save_link(cwd, Link(org_id=1, org_slug="acme", project_id=10, project_slug="origyn"))
+
+
+# --- adopt ---------------------------------------------------------------
+
+
+def test_adopt_without_link_gives_clear_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+
+    result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--yes"])
+
+    assert result.exit_code == 1
+    assert "mozbridge link" in result.output
+
+
+def test_adopt_without_login_gives_clear_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_link(tmp_path)
+
+    result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--yes"])
+
+    assert result.exit_code == 1
+    assert "mozbridge login" in result.output
+
+
+def test_adopt_yes_skips_prompt_and_prints_pr_url(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "pr_url": "https://github.com/acme/origyn/pull/42",
+                    "pr_number": 42,
+                    "branch": "mozbridge/adopt-compose",
+                    "violations": [],
+                },
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--yes"])
+
+    assert result.exit_code == 0, result.output
+    assert route.called
+    assert "https://github.com/acme/origyn/pull/42" in result.output
+
+    request = route.calls.last.request
+    assert request.headers["authorization"] == "Bearer AT-valid"
+    assert request.headers["x-organization-id"] == "1"
+    body = json.loads(request.content)
+    assert body == {"container": "origyn-app", "service": "backend"}
+
+
+def test_adopt_custom_service_is_sent(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "pr_url": "https://github.com/acme/origyn/pull/43",
+                    "pr_number": 43,
+                    "branch": "mozbridge/adopt-compose",
+                    "violations": [],
+                },
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--service", "frontend", "--yes"])
+
+    assert result.exit_code == 0, result.output
+    body = json.loads(route.calls.last.request.content)
+    assert body == {"container": "origyn-app", "service": "frontend"}
+
+
+def test_adopt_interactive_confirm_accepted_calls_api(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                200,
+                json={"pr_url": "https://github.com/acme/origyn/pull/44", "pr_number": 44, "violations": []},
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app"], input="y\n")
+
+    assert result.exit_code == 0, result.output
+    assert route.called
+    assert "https://github.com/acme/origyn/pull/44" in result.output
+
+
+def test_adopt_interactive_confirm_declined_makes_no_api_call(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                200, json={"pr_url": "https://github.com/acme/origyn/pull/45", "violations": []}
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app"], input="n\n")
+
+    assert result.exit_code != 0
+    assert not route.called
+
+
+def test_adopt_prints_what_will_happen_before_prompting(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(200, json={"pr_url": "https://x/pull/1", "violations": []})
+        )
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app"], input="n\n")
+
+    assert "acme/origyn" in result.output
+    assert "origyn-app" in result.output
+
+
+def test_adopt_d2_violation_prints_each_violation_and_no_pr_opened_claim(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                422,
+                json={
+                    "detail": {
+                        "message": "rendered docker-compose.app.yml failed the D2 compose contract validator",
+                        "violations": [
+                            "service 'backend' has no healthcheck",
+                            "image tag 'latest' is not allowed",
+                        ],
+                    }
+                },
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--yes"])
+
+    assert result.exit_code == 1
+    assert "service 'backend' has no healthcheck" in result.output
+    assert "image tag 'latest' is not allowed" in result.output
+    assert "No PR was opened" in result.output
+
+
+def test_adopt_container_not_found_error_surfaced_clearly(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/adopt").mock(
+            return_value=httpx.Response(
+                400, json={"detail": "container 'origyn-app' not found on origyn-host: 404 Client Error"}
+            )
+        )
+
+        result = runner.invoke(app, ["adopt", "--container", "origyn-app", "--yes"])
+
+    assert result.exit_code == 1
+    assert "not found on origyn-host" in result.output
+
+
+# --- scaffold --------------------------------------------------------------
+
+
+def test_scaffold_without_link_gives_clear_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+
+    result = runner.invoke(app, ["scaffold", "--yes"])
+
+    assert result.exit_code == 1
+    assert "mozbridge link" in result.output
+
+
+def test_scaffold_without_login_gives_clear_error(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_link(tmp_path)
+
+    result = runner.invoke(app, ["scaffold", "--yes"])
+
+    assert result.exit_code == 1
+    assert "mozbridge login" in result.output
+
+
+def test_scaffold_yes_skips_prompt_and_prints_pr_url(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/scaffold").mock(
+            return_value=httpx.Response(
+                200,
+                json={
+                    "pr_url": "https://github.com/acme/origyn/pull/50",
+                    "pr_number": 50,
+                    "branch": "mozbridge/scaffold-compose",
+                    "violations": [],
+                },
+            )
+        )
+
+        result = runner.invoke(app, ["scaffold", "--yes"])
+
+    assert result.exit_code == 0, result.output
+    assert route.called
+    assert "https://github.com/acme/origyn/pull/50" in result.output
+
+    request = route.calls.last.request
+    assert request.headers["authorization"] == "Bearer AT-valid"
+    assert request.headers["x-organization-id"] == "1"
+    body = json.loads(request.content)
+    assert body == {"service": "backend"}
+
+
+def test_scaffold_custom_service_is_sent(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/scaffold").mock(
+            return_value=httpx.Response(
+                200, json={"pr_url": "https://github.com/acme/origyn/pull/51", "violations": []}
+            )
+        )
+
+        result = runner.invoke(app, ["scaffold", "--service", "frontend", "--yes"])
+
+    assert result.exit_code == 0, result.output
+    body = json.loads(route.calls.last.request.content)
+    assert body == {"service": "frontend"}
+
+
+def test_scaffold_interactive_confirm_declined_makes_no_api_call(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        route = respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/scaffold").mock(
+            return_value=httpx.Response(200, json={"pr_url": "https://x/pull/2", "violations": []})
+        )
+
+        result = runner.invoke(app, ["scaffold"], input="n\n")
+
+    assert result.exit_code != 0
+    assert not route.called
+
+
+def test_scaffold_d2_violation_prints_each_violation_and_no_pr_opened_claim(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    _seed_session()
+    _seed_link(tmp_path)
+
+    with respx.mock:
+        respx.post(f"{config.API_BASE_URL}{config.PROJECTS_PATH}/10/scaffold").mock(
+            return_value=httpx.Response(
+                422,
+                json={
+                    "detail": {
+                        "message": "rendered docker-compose.app.yml failed the D2 compose contract validator",
+                        "violations": ["backend_port is not set"],
+                    }
+                },
+            )
+        )
+
+        result = runner.invoke(app, ["scaffold", "--yes"])
+
+    assert result.exit_code == 1
+    assert "backend_port is not set" in result.output
+    assert "No PR was opened" in result.output