mozbridge-cli 0.1.0__py3-none-any.whl

mozbridge_cli/main.py

@@ -0,0 +1,821 @@
+"""Mozbridge CLI: login / whoami / logout / link / build / publish / diff / status / rollback.
+
+macOS-only for v1 (no Windows code paths).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import httpx
+import typer
+
+from . import api, auth, config, session
+from . import build as buildmod
+from . import compose as composemod
+from . import link as linkmod
+from . import local_build as local_buildmod
+from . import runtime_secrets as runtime_secretsmod
+
+app = typer.Typer(
+    name="mozbridge",
+    help="Mozbridge platform CLI: login, whoami, logout, link, build, publish, diff, status, rollback.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+@app.command("login")
+def login_cmd() -> None:
+    """Sign in via Logto's device authorization flow (opens a URL for you to approve)."""
+    if session.token_from_env() is not None:
+        typer.echo(
+            f"{session.TOKEN_ENV_VAR} is set — this CLI is already authenticating as that "
+            "token for every command, so an interactive `mozbridge login` doesn't apply here. "
+            f"These are mutually exclusive auth modes; unset {session.TOKEN_ENV_VAR} first if "
+            "you want to log in interactively instead.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    with httpx.Client(timeout=30.0) as client:
+        try:
+            authorization = auth.start_device_authorization(client)
+        except httpx.HTTPError as exc:
+            typer.echo(f"Could not start login: {exc}", err=True)
+            raise typer.Exit(code=1)
+
+        if authorization.verification_uri_complete:
+            typer.echo(f"Open this URL to sign in:\n\n  {authorization.verification_uri_complete}\n")
+        typer.echo(f"Or go to {authorization.verification_uri} and enter code: {authorization.user_code}")
+        typer.echo("Waiting for approval...")
+
+        try:
+            token_response = auth.poll_for_token(client, authorization)
+        except auth.AccessDenied as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+        except auth.ExpiredToken as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+        except auth.DeviceLoginError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    new_session = session.session_from_token_response(token_response)
+    path = session.save_session(new_session)
+    typer.echo(f"Logged in. Session saved to {path}")
+
+
+def _load_and_refresh_session(client: httpx.Client) -> session.Session:
+    """Return the bearer token to use for this command.
+
+    Single choke point for auth used by every command below (whoami, link,
+    status, rollback, diff, publish's remote AND --local paths). Checked
+    BEFORE anything session-file-related, mirroring gh/flyctl/Vercel's own
+    env-var precedence: if MOZBRIDGE_TOKEN is set, it is used directly as
+    the bearer token and load_session()/save_session()/refresh-token logic
+    are never invoked — there's no on-disk session file involved in this
+    path. Otherwise, falls back to loading the cached session, refreshing
+    the access token first if expired.
+
+    Exits the process with a clear message if there is no session, or if
+    refresh fails.
+    """
+    env_token = session.token_from_env()
+    if env_token is not None:
+        return session.Session(
+            access_token=env_token,
+            refresh_token=None,
+            id_token=None,
+            expires_at=float("inf"),
+        )
+
+    current = session.load_session()
+    if current is None:
+        typer.echo("Not logged in. Run `mozbridge login` first.", err=True)
+        raise typer.Exit(code=1)
+
+    if not current.is_expired():
+        return current
+
+    if not current.refresh_token:
+        typer.echo("Session expired and cannot be refreshed. Run `mozbridge login` again.", err=True)
+        raise typer.Exit(code=1)
+
+    try:
+        token_response = auth.refresh_access_token(client, current.refresh_token)
+    except auth.RefreshError as exc:
+        typer.echo(f"{exc} — run `mozbridge login` again.", err=True)
+        raise typer.Exit(code=1)
+
+    refreshed = session.session_from_token_response(token_response)
+    # Logto may omit refresh_token on rotation-less refresh — keep the old one.
+    if not refreshed.refresh_token:
+        refreshed.refresh_token = current.refresh_token
+    session.save_session(refreshed)
+    return refreshed
+
+
+@app.command("whoami")
+def whoami_cmd() -> None:
+    """Show the signed-in Mozbridge identity."""
+    with httpx.Client(timeout=30.0) as client:
+        active_session = _load_and_refresh_session(client)
+
+        url = f"{config.API_BASE_URL}{config.WHOAMI_PATH}"
+        try:
+            resp = client.get(url, headers={"Authorization": f"Bearer {active_session.access_token}"})
+        except httpx.HTTPError as exc:
+            typer.echo(f"Could not reach Mozbridge API: {exc}", err=True)
+            raise typer.Exit(code=1)
+
+        if resp.status_code == 401:
+            typer.echo("Session is no longer valid. Run `mozbridge login` again.", err=True)
+            raise typer.Exit(code=1)
+        if resp.status_code != 200:
+            typer.echo(f"Mozbridge API returned {resp.status_code}: {resp.text}", err=True)
+            raise typer.Exit(code=1)
+
+        data = resp.json()
+
+    email = data.get("email") or "(no email on record)"
+    username = data.get("username")
+    full_name = data.get("full_name")
+    display = full_name or username or email
+
+    typer.echo(f"Logged in as {display}")
+    typer.echo(f"  email:            {email}")
+    if username:
+        typer.echo(f"  username:         {username}")
+    typer.echo(f"  user id:          {data.get('id')}")
+    typer.echo(f"  platform admin:   {bool(data.get('is_platform_admin'))}")
+
+
+@app.command("logout")
+def logout_cmd() -> None:
+    """Delete the cached local session. Safe to run even if already logged out."""
+    removed = session.delete_session()
+    if removed:
+        typer.echo("Logged out.")
+    else:
+        typer.echo("Already logged out.")
+
+
+def _pick_one(items: list[dict], *, label: str) -> dict:
+    """Numbered-list interactive picker. No fancy TUI — a prompt is enough for v1."""
+    typer.echo(f"Select a {label}:")
+    for i, item in enumerate(items, start=1):
+        name = item.get("name") or item.get("slug")
+        typer.echo(f"  {i}. {name} ({item.get('slug')})")
+    raw_choice = typer.prompt(f"Enter a number (1-{len(items)})")
+    try:
+        index = int(raw_choice)
+    except ValueError:
+        typer.echo(f"'{raw_choice}' is not a number.", err=True)
+        raise typer.Exit(code=1)
+    if not (1 <= index <= len(items)):
+        typer.echo(f"'{raw_choice}' is not between 1 and {len(items)}.", err=True)
+        raise typer.Exit(code=1)
+    return items[index - 1]
+
+
+def _resolve_by_slug_or_prompt(items: list[dict], slug: str | None, *, label: str) -> dict:
+    if slug is None:
+        if not items:
+            typer.echo(f"No {label}s found for this account.", err=True)
+            raise typer.Exit(code=1)
+        return _pick_one(items, label=label)
+
+    for item in items:
+        if item.get("slug") == slug:
+            return item
+    available = ", ".join(sorted(i.get("slug", "") for i in items)) or "(none)"
+    typer.echo(
+        f"{label.capitalize()} '{slug}' not found or not visible to this account. Available: {available}",
+        err=True,
+    )
+    raise typer.Exit(code=1)
+
+
+@app.command("link")
+def link_cmd(
+    org: str | None = typer.Option(None, "--org", help="Organization slug to link (skips the picker)."),
+    project: str | None = typer.Option(None, "--project", help="Project slug to link (skips the picker)."),
+) -> None:
+    """Link the current directory to a Mozbridge org + project.
+
+    Writes .mozbridge/link.json in the current directory. Used by `build`
+    and `publish` to know where to ship.
+    """
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=30.0) as client:
+        active_session = _load_and_refresh_session(client)
+
+        try:
+            orgs = api.list_organizations(client, active_session.access_token)
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+        chosen_org = _resolve_by_slug_or_prompt(orgs, org, label="organization")
+
+        try:
+            projects = api.list_projects(client, active_session.access_token, chosen_org["id"])
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+        chosen_project = _resolve_by_slug_or_prompt(projects, project, label="project")
+
+    new_link = linkmod.Link(
+        org_id=chosen_org["id"],
+        org_slug=chosen_org["slug"],
+        project_id=chosen_project["id"],
+        project_slug=chosen_project["slug"],
+    )
+    path = linkmod.save_link(cwd, new_link)
+    typer.echo(f"Linked {chosen_org['slug']}/{chosen_project['slug']} -> {path}")
+    typer.echo(linkmod.ensure_gitignored(cwd))
+
+
+@app.command("build")
+def build_cmd() -> None:
+    """Zip the current directory into a build artifact. Does not upload.
+
+    A dry-run-adjacent primitive: prints the path and size of what a
+    `publish` would ship.
+    """
+    result = buildmod.build_zip(Path.cwd())
+    size_kb = result.size_bytes / 1024
+    typer.echo(f"Built {result.zip_path} ({size_kb:.1f} KB, {result.file_count} files)")
+
+
+def _upload_context(
+    client: httpx.Client,
+    active_session: session.Session,
+    current_link: linkmod.Link,
+    context_dir: Path,
+) -> str:
+    """Zip `context_dir`, create a source-upload session, PUT the bytes, return upload_id.
+
+    Shared by both the single-component path (context_dir == cwd) and each
+    distinct build-context group in the multi-component path. Raises
+    `typer.Exit` (already having echoed a clear message) on any failure —
+    callers do not need their own try/except around this.
+    """
+    result = buildmod.build_zip(context_dir)
+    typer.echo(f"Built {result.zip_path} ({result.size_bytes / 1024:.1f} KB, {result.file_count} files)")
+    try:
+        try:
+            upload_session = api.create_source_upload(
+                client,
+                active_session.access_token,
+                current_link.org_id,
+                current_link.project_id,
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+        zip_bytes = result.zip_path.read_bytes()
+        try:
+            api.put_source_upload_bytes(
+                client,
+                active_session.access_token,
+                current_link.org_id,
+                upload_session["put_url"],
+                zip_bytes,
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+    finally:
+        result.zip_path.unlink(missing_ok=True)
+
+    return upload_session["upload_id"]
+
+
+def _publish_single_component(
+    client: httpx.Client, active_session: session.Session, current_link: linkmod.Link, cwd: Path
+) -> None:
+    """Today's original publish flow, unchanged: one zip of the whole directory,
+    one upload, one trigger_build call — no image_name/context_path/
+    dockerfile_path override, so the backend applies its own defaults exactly
+    as it always has.
+    """
+    upload_id = _upload_context(client, active_session, current_link, cwd)
+
+    try:
+        build_response = api.trigger_build(
+            client,
+            active_session.access_token,
+            current_link.org_id,
+            current_link.project_id,
+            upload_id,
+        )
+    except api.ApiError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1)
+
+    task_id = build_response.get("task_id")
+    typer.echo(f"Build triggered (task_id={task_id}).")
+    typer.echo("Run `mozbridge status` to check progress, or poll the Mozbridge dashboard.")
+
+
+def _publish_multi_component(
+    client: httpx.Client,
+    active_session: session.Session,
+    current_link: linkmod.Link,
+    cwd: Path,
+    groups: dict[Path, list[composemod.ResolvedComponent]],
+) -> None:
+    """One trigger_build call per compose service with a `build:` key.
+
+    Services that share an identical resolved build context are zipped and
+    uploaded exactly once (`groups` is already de-duplicated by
+    compose.group_by_context) and reuse that one upload_id across their
+    individual trigger_build calls. Every component is attempted even if an
+    earlier one fails, so one broken service never hides the outcome of the
+    others; failures are collected and reported clearly at the end.
+    """
+    total = sum(len(components) for components in groups.values())
+    typer.echo(
+        f"Found {total} component(s) to publish from compose ({len(groups)} distinct build context(s))."
+    )
+
+    succeeded: list[tuple[str, int | str | None]] = []
+    failed: list[tuple[str, str]] = []
+
+    for context_dir, components in groups.items():
+        service_names = ", ".join(c.service_name for c in components)
+        if not context_dir.is_dir():
+            typer.echo(f"[{service_names}] build context not found: {context_dir}", err=True)
+            for component in components:
+                failed.append((component.service_name, f"build context not found: {context_dir}"))
+            continue
+
+        typer.echo(f"--- Context {context_dir} ({service_names}) ---")
+        try:
+            upload_id = _upload_context(client, active_session, current_link, context_dir)
+        except typer.Exit:
+            # _upload_context already echoed the specific error; every
+            # component sharing this context failed with it.
+            for component in components:
+                failed.append((component.service_name, "upload failed — see error above"))
+            continue
+
+        for component in components:
+            typer.echo(f"[{component.service_name}] Triggering build (image={component.image_name})...")
+            try:
+                build_response = api.trigger_build(
+                    client,
+                    active_session.access_token,
+                    current_link.org_id,
+                    current_link.project_id,
+                    upload_id,
+                    image_name=component.image_name,
+                    context_path=component.context_path,
+                    dockerfile_path=component.dockerfile_path,
+                )
+            except api.ApiError as exc:
+                typer.echo(f"[{component.service_name}] FAILED: {exc}", err=True)
+                failed.append((component.service_name, str(exc)))
+                continue
+            task_id = build_response.get("task_id")
+            typer.echo(f"[{component.service_name}] Build triggered (task_id={task_id}).")
+            succeeded.append((component.service_name, task_id))
+
+    typer.echo("")
+    typer.echo(f"Publish summary: {len(succeeded)} succeeded, {len(failed)} failed (of {total}).")
+    for service_name, task_id in succeeded:
+        typer.echo(f"  OK   {service_name} (task_id={task_id})")
+    for service_name, reason in failed:
+        typer.echo(f"  FAIL {service_name}: {reason}", err=True)
+
+    if failed:
+        raise typer.Exit(code=1)
+
+    typer.echo("Run `mozbridge status` to check progress, or poll the Mozbridge dashboard.")
+
+
+@app.command("publish")
+def publish_cmd(
+    local: bool = typer.Option(
+        False,
+        "--local",
+        help=(
+            "Build and push the image(s) on THIS machine, using the project's own "
+            "registry credential, instead of uploading source for the platform to "
+            "build — then register the resulting digest(s) for deploy. Requires "
+            f"{runtime_secretsmod.BUILD_TOKEN_ENV_VAR} (see the error message for how "
+            "to get one)."
+        ),
+    ),
+) -> None:
+    """Build the current directory and publish it to the linked Mozbridge project.
+
+    Requires `mozbridge link` to have been run here, and an active login
+    session.
+
+    If a compose file is present (docker-compose.yml, compose.yaml, or
+    docker-compose.yaml — Docker's own discovery order) and at least one of
+    its services has a `build:` key, each such service is published as its
+    own component/image: one create_source_upload -> PUT -> trigger_build
+    per component, with contexts shared across services de-duplicated to a
+    single upload. Otherwise (no compose file, or none of its services
+    build) this falls back unchanged to the original single-component flow:
+    zip the whole directory, one upload, one trigger_build call.
+
+    `--local` replaces the upload+remote-build step entirely: components are
+    resolved the same way, but each is built and pushed with the developer's
+    own local `docker`, using registry credentials fetched with a SEPARATE
+    build-scoped token (MOZBRIDGE_BUILD_TOKEN), then registered via the same
+    trigger_build endpoint using the regular login session. See
+    `_publish_local` below.
+    """
+    cwd = Path.cwd()
+    current_link = linkmod.load_link(cwd)
+    if current_link is None:
+        typer.echo(
+            "This directory is not linked to a Mozbridge project. Run `mozbridge link` first.", err=True
+        )
+        raise typer.Exit(code=1)
+
+    if local:
+        _publish_local(cwd, current_link)
+        return
+
+    components: list[composemod.Component] = []
+    compose_path = composemod.find_compose_file(cwd)
+    if compose_path is not None:
+        components = composemod.parse_components(compose_path)
+
+    with httpx.Client(timeout=120.0) as client:
+        active_session = _load_and_refresh_session(client)
+
+        if components:
+            typer.echo(f"Using {compose_path.name} for multi-component publish.")
+            groups = composemod.resolve_components(
+                cwd, current_link.org_slug, current_link.project_slug, components
+            )
+            _publish_multi_component(client, active_session, current_link, cwd, groups)
+        else:
+            _publish_single_component(client, active_session, current_link, cwd)
+
+
+def _publish_local(cwd: Path, current_link: linkmod.Link) -> None:
+    """`mozbridge publish --local`: build+push image(s) on THIS machine using
+    the project's own registry credentials (fetched with a SEPARATE
+    build-scoped token), then register each resulting digest via the same
+    trigger_build endpoint `publish` already calls — using the regular LOGIN
+    session, never the build token. See runtime_secrets.py's module
+    docstring for why these two credentials must never cross.
+
+    Order of checks is deliberate: cheap, local, no-network checks first
+    (MOZBRIDGE_BUILD_TOKEN present, docker installed/daemon reachable) so a
+    misconfigured environment fails fast with zero docker or HTTP calls,
+    before login-session refresh or any network call is attempted.
+    """
+    build_token = os.environ.get(runtime_secretsmod.BUILD_TOKEN_ENV_VAR)
+    if not build_token:
+        typer.echo(
+            f"{runtime_secretsmod.BUILD_TOKEN_ENV_VAR} is not set.\n\n"
+            "`mozbridge publish --local` builds and pushes images on this machine, "
+            "so it needs a SEPARATE credential from your `mozbridge login` session: "
+            "a project-scoped service token with the 'build' scope (registry/build "
+            "credentials only — it can never reach a deploy host key). Create one "
+            "via the Mozbridge dashboard or API (Project Settings -> Service Tokens "
+            "-> New, scope 'build') — this CLI does not create or mint tokens "
+            "itself. Then:\n\n"
+            f"  export {runtime_secretsmod.BUILD_TOKEN_ENV_VAR}=<token>\n",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        local_buildmod.check_docker_available()
+    except local_buildmod.DockerUnavailableError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(code=1)
+
+    components: list[composemod.Component] = []
+    compose_path = composemod.find_compose_file(cwd)
+    if compose_path is not None:
+        components = composemod.parse_components(compose_path)
+
+    with httpx.Client(timeout=180.0) as client:
+        active_session = _load_and_refresh_session(client)
+
+        try:
+            secrets = runtime_secretsmod.fetch_runtime_secrets(client, build_token)
+        except runtime_secretsmod.RuntimeSecretsError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+        registry_user = secrets.get("GHCR_USER")
+        registry_password = secrets.get("GHCR_TOKEN")
+        if not registry_password or not registry_user:
+            missing = "GHCR_TOKEN" if not registry_password else "GHCR_USER"
+            typer.echo(
+                f"The runtime-secrets response did not include {missing}. This project "
+                "may not have a registry credential configured yet — set one via "
+                "PUT /projects/{project_id}/registry (Project Settings -> Registry in "
+                "the Mozbridge dashboard).",
+                err=True,
+            )
+            raise typer.Exit(code=1)
+
+        try:
+            local_buildmod.docker_login(local_buildmod.REGISTRY, registry_user, registry_password)
+        except local_buildmod.DockerError as exc:
+            typer.echo(f"docker login to {local_buildmod.REGISTRY} failed: {exc}", err=True)
+            raise typer.Exit(code=1)
+
+        if components:
+            typer.echo(f"Using {compose_path.name} for local multi-component publish.")
+            groups = composemod.resolve_components(
+                cwd, current_link.org_slug, current_link.project_slug, components
+            )
+        else:
+            image_name = composemod.default_image_name(current_link.org_slug, current_link.project_slug)
+            single = composemod.ResolvedComponent(
+                service_name="app",
+                image_name=image_name,
+                context_dir=cwd,
+                context_path=".",
+                dockerfile_path="Dockerfile",
+            )
+            groups = {cwd: [single]}
+
+        _local_build_and_register(client, active_session, current_link, groups)
+
+
+def _local_build_and_register(
+    client: httpx.Client,
+    active_session: session.Session,
+    current_link: linkmod.Link,
+    groups: dict[Path, list[composemod.ResolvedComponent]],
+) -> None:
+    """docker build -> docker push -> trigger_build(source_type='prebuilt') for
+    every component in `groups`. Mirrors `_publish_multi_component`'s
+    per-component OK/FAIL reporting and partial-failure semantics: every
+    component is attempted even if an earlier one fails.
+    """
+    total = sum(len(components) for components in groups.values())
+    typer.echo(f"Building {total} component(s) locally with docker...")
+
+    succeeded: list[tuple[str, str]] = []
+    failed: list[tuple[str, str]] = []
+
+    for context_dir, components in groups.items():
+        if not context_dir.is_dir():
+            for component in components:
+                typer.echo(f"[{component.service_name}] build context not found: {context_dir}", err=True)
+                failed.append((component.service_name, f"build context not found: {context_dir}"))
+            continue
+
+        for component in components:
+            tag = f"{component.image_name}:{local_buildmod.local_tag()}"
+            typer.echo(f"[{component.service_name}] docker build -> {tag} ...")
+            try:
+                local_buildmod.docker_build(context_dir, component.dockerfile_path, tag)
+            except local_buildmod.DockerError as exc:
+                typer.echo(f"[{component.service_name}] FAILED (docker build): {exc}", err=True)
+                failed.append((component.service_name, f"docker build failed: {exc}"))
+                continue
+
+            typer.echo(f"[{component.service_name}] docker push {tag} ...")
+            try:
+                digest = local_buildmod.docker_push(tag)
+            except local_buildmod.DockerError as exc:
+                typer.echo(f"[{component.service_name}] FAILED (docker push): {exc}", err=True)
+                failed.append((component.service_name, f"docker push failed: {exc}"))
+                continue
+
+            typer.echo(f"[{component.service_name}] Registering {component.image_name}@{digest} ...")
+            try:
+                api.trigger_prebuilt_build(
+                    client,
+                    active_session.access_token,
+                    current_link.org_id,
+                    current_link.project_id,
+                    component.image_name,
+                    digest,
+                )
+            except api.ApiError as exc:
+                typer.echo(f"[{component.service_name}] FAILED (register): {exc}", err=True)
+                failed.append((component.service_name, str(exc)))
+                continue
+
+            typer.echo(f"[{component.service_name}] Registered.")
+            succeeded.append((component.service_name, digest))
+
+    typer.echo("")
+    typer.echo(f"Local publish summary: {len(succeeded)} succeeded, {len(failed)} failed (of {total}).")
+    for service_name, digest in succeeded:
+        typer.echo(f"  OK   {service_name} ({digest})")
+    for service_name, reason in failed:
+        typer.echo(f"  FAIL {service_name}: {reason}", err=True)
+
+    if failed:
+        raise typer.Exit(code=1)
+
+    typer.echo("Run `mozbridge status` to check progress, or poll the Mozbridge dashboard.")
+
+
+@app.command("diff")
+def diff_cmd() -> None:
+    """Preview what `mozbridge publish` would do right now. Does not publish anything.
+
+    Requires `mozbridge link` and an active login session, same as `publish`.
+    Makes no mutating API calls: it only GETs the linked project's most
+    recent deployment (the same call `mozbridge status` makes) for context,
+    plus local filesystem reads to work out what `publish` would build. No
+    upload, no trigger_build.
+
+    This compares local components against the most recent deployment
+    RECORD only — the platform does not expose the actually-deployed
+    compose content anywhere, so this is not a full semantic compose diff,
+    just "here's what's live" next to "here's what publish would build".
+    """
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=30.0) as client:
+        current_link, active_session = _require_link_and_session(client, cwd)
+
+        try:
+            deployments = api.list_project_deployments(
+                client, active_session.access_token, current_link.org_id, current_link.project_id
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    typer.echo(
+        f"Diff for {current_link.org_slug}/{current_link.project_slug} "
+        "(preview only — mozbridge publish has NOT been run)."
+    )
+    typer.echo("")
+
+    typer.echo("Currently deployed (most recent deployment record):")
+    if deployments:
+        latest = deployments[0]
+        stable_marker = " [stable]" if latest.get("is_stable") else ""
+        typer.echo(
+            f"  #{latest.get('id')}  {latest.get('deployed_at') or '(no timestamp)'}  "
+            f"{latest.get('component')}={latest.get('version')}  "
+            f"{latest.get('status')}{stable_marker}"
+        )
+    else:
+        typer.echo("  No deployments yet.")
+    typer.echo("")
+
+    components: list[composemod.Component] = []
+    compose_path = composemod.find_compose_file(cwd)
+    if compose_path is not None:
+        components = composemod.parse_components(compose_path)
+
+    if not components:
+        if compose_path is not None:
+            typer.echo(
+                f"{compose_path.name} was found but has no services with a `build:` key. "
+                "`mozbridge publish` would fall back to the single-component path: "
+                "zip the whole current directory and publish it as one component."
+            )
+        else:
+            typer.echo(
+                "No compose file found (docker-compose.yml, compose.yaml, or "
+                "docker-compose.yaml). `mozbridge publish` would use the "
+                "single-component path: zip the whole current directory and "
+                "publish it as one component."
+            )
+        return
+
+    groups = composemod.resolve_components(cwd, current_link.org_slug, current_link.project_slug, components)
+    total = sum(len(resolved) for resolved in groups.values())
+    typer.echo(
+        f"Using {compose_path.name}. `mozbridge publish` would publish {total} component(s) "
+        f"from {len(groups)} distinct build context(s):"
+    )
+    for context_dir, resolved in groups.items():
+        service_names = ", ".join(c.service_name for c in resolved)
+        missing_note = "  (WARNING: build context not found on disk)" if not context_dir.is_dir() else ""
+        typer.echo(f"--- Context {context_dir} ({service_names}){missing_note} ---")
+        for component in resolved:
+            typer.echo(f"  [{component.service_name}]")
+            typer.echo(f"    image_name:      {component.image_name}")
+            typer.echo(f"    context_path:    {component.context_path}")
+            typer.echo(f"    dockerfile_path: {component.dockerfile_path}")
+
+    typer.echo("")
+    typer.echo(
+        "Note: this diff compares local components against the most recent "
+        "deployment record only, not the actually-deployed compose content "
+        "(the platform doesn't expose that) — it is not a full semantic "
+        "compose diff."
+    )
+
+
+def _require_link_and_session(client: httpx.Client, cwd: Path) -> tuple[linkmod.Link, session.Session]:
+    """Shared guard for `status`, `rollback`, and `diff`: same clear-error pattern as `publish`."""
+    current_link = linkmod.load_link(cwd)
+    if current_link is None:
+        typer.echo(
+            "This directory is not linked to a Mozbridge project. Run `mozbridge link` first.", err=True
+        )
+        raise typer.Exit(code=1)
+    active_session = _load_and_refresh_session(client)
+    return current_link, active_session
+
+
+@app.command("status")
+def status_cmd() -> None:
+    """Show the linked project's status and its 5 most recent deployments."""
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=30.0) as client:
+        current_link, active_session = _require_link_and_session(client, cwd)
+
+        try:
+            project = api.get_project(
+                client, active_session.access_token, current_link.org_id, current_link.project_id
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+        try:
+            deployments = api.list_project_deployments(
+                client, active_session.access_token, current_link.org_id, current_link.project_id
+            )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    typer.echo(f"{project.get('name')} ({project.get('slug')})")
+    typer.echo(f"  status: {project.get('status')}")
+
+    if not deployments:
+        typer.echo("No deployments yet.")
+        return
+
+    typer.echo("Recent deployments:")
+    for deployment in deployments[:5]:
+        stable_marker = " [stable]" if deployment.get("is_stable") else ""
+        typer.echo(
+            f"  #{deployment.get('id')}  {deployment.get('deployed_at') or '(no timestamp)'}  "
+            f"{deployment.get('component')}={deployment.get('version')}  "
+            f"{deployment.get('status')}{stable_marker}"
+        )
+
+
+@app.command("rollback")
+def rollback_cmd(
+    to: int | None = typer.Option(
+        None, "--to", help="Deployment id to roll back to. Omit to roll back to the previous deployment."
+    ),
+    yes: bool = typer.Option(False, "--yes", help="Skip the interactive confirmation prompt."),
+) -> None:
+    """Roll back the linked project's deployment. A real, consequential production action."""
+    cwd = Path.cwd()
+
+    with httpx.Client(timeout=30.0) as client:
+        current_link, active_session = _require_link_and_session(client, cwd)
+
+        target_desc = f"deployment #{to}" if to is not None else "the previous deployment"
+        project_desc = f"{current_link.org_slug}/{current_link.project_slug}"
+        typer.echo(f"This will roll back {project_desc} to {target_desc}.")
+        typer.echo("Target environment: prod.")
+        if not yes:
+            typer.confirm("Continue?", abort=True)
+
+        try:
+            if to is not None:
+                result = api.rollback_project_to(
+                    client,
+                    active_session.access_token,
+                    current_link.org_id,
+                    current_link.project_id,
+                    to,
+                )
+            else:
+                result = api.rollback_project(
+                    client, active_session.access_token, current_link.org_id, current_link.project_id
+                )
+        except api.ApiError as exc:
+            typer.echo(str(exc), err=True)
+            raise typer.Exit(code=1)
+
+    task_id = result.get("task_id") or result.get("target_task")
+    typer.echo(f"Rollback triggered (task_id={task_id}).")
+
+
+def app_main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    app_main()