ldw-deploy 0.2.1__py3-none-any.whl

ldw_deploy/__init__.py

@@ -0,0 +1 @@
+"""SSH production targets and deployments for the Local DevOps Workbench."""

ldw_deploy/assets/ldw-remote-deploy.py

@@ -0,0 +1,526 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import fcntl
+import hashlib
+import json
+import os
+import pwd
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import time
+import urllib.error
+import urllib.request
+from contextlib import suppress
+from pathlib import Path, PurePosixPath
+from urllib.parse import urlsplit
+
+PROJECTS_ROOT = Path("/srv/ldw/projects")
+STAGING_ROOT = Path("/home/devops/ldw")
+DOCKER = "/usr/bin/docker"
+COMPONENT = re.compile(r"[a-z][a-z0-9-]{1,62}")
+BUILD = re.compile(r"[a-zA-Z0-9][a-zA-Z0-9.-]{0,127}")
+
+
+def _component(value: str, *, build: bool = False) -> str:
+    pattern = BUILD if build else COMPONENT
+    if pattern.fullmatch(value) is None:
+        raise ValueError(f"invalid deployment component: {value!r}")
+    return value
+
+
+def _relative(value: str) -> str:
+    path = PurePosixPath(value)
+    if not value or path.is_absolute() or value == "." or ".." in path.parts:
+        raise ValueError(f"invalid release path: {value!r}")
+    return str(path)
+
+
+def _staged(name: str) -> Path:
+    if Path(name).name != name or name in {"", ".", ".."}:
+        raise ValueError("invalid staging filename")
+    path = STAGING_ROOT / name
+    if not path.is_file() or path.is_symlink():
+        raise ValueError(f"staged input is not a regular file: {name}")
+    return path
+
+
+def _sha256(path: Path) -> str:
+    with path.open("rb") as handle:
+        return hashlib.file_digest(handle, "sha256").hexdigest()
+
+
+def _verified_staged(record: object) -> Path:
+    if not isinstance(record, dict):
+        raise ValueError("invalid staged input record")
+    name = record.get("name")
+    checksum = record.get("sha256")
+    if not isinstance(name, str) or not isinstance(checksum, str):
+        raise ValueError("staged input record requires name and sha256")
+    path = _staged(name)
+    if _sha256(path) != checksum:
+        raise ValueError(f"staged input checksum mismatch: {name}")
+    return path
+
+
+def _safe_extract(bundle: Path, destination: Path) -> None:
+    with tarfile.open(bundle) as archive:
+        members = archive.getmembers()
+        for member in members:
+            path = PurePosixPath(member.name)
+            if path.is_absolute() or ".." in path.parts or member.issym() or member.islnk():
+                raise ValueError(f"unsafe release archive member: {member.name}")
+        archive.extractall(destination, members=members, filter="data")
+
+
+def _metadata(
+    path: Path,
+    project: str,
+    build_id: str,
+    expected_sha256: str,
+) -> dict[str, object]:
+    if re.fullmatch(r"[a-f0-9]{64}", expected_sha256) is None:
+        raise ValueError("invalid deployment metadata checksum")
+    if _sha256(path) != expected_sha256:
+        raise ValueError("deployment metadata checksum mismatch")
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict) or payload.get("schema_version") != 1:
+        raise ValueError("invalid deployment metadata")
+    if payload.get("project_id") != project or payload.get("build_id") != build_id:
+        raise ValueError("deployment metadata identity mismatch")
+    return payload
+
+
+def _health_url(value: object) -> str:
+    if not isinstance(value, str):
+        raise ValueError("deployment metadata has no health_url")
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "http"
+        or parsed.hostname not in {"127.0.0.1", "localhost"}
+        or parsed.port is None
+        or parsed.username is not None
+        or parsed.password is not None
+    ):
+        raise ValueError("deployment health URL must use loopback HTTP")
+    return value
+
+
+def _compose_argv(release: Path, metadata: dict[str, object], *args: str) -> list[str]:
+    project = str(metadata["project_id"])
+    compose_files = metadata.get("compose_files")
+    profiles = metadata.get("profiles", [])
+    if not isinstance(compose_files, list) or not compose_files:
+        raise ValueError("deployment metadata has no Compose files")
+    if not isinstance(profiles, list):
+        raise ValueError("deployment metadata has invalid profiles")
+    argv = [DOCKER, "compose", "-p", f"ldw-{project}"]
+    for relative in compose_files:
+        if not isinstance(relative, str):
+            raise ValueError("deployment metadata has invalid Compose file")
+        path = release / _relative(relative)
+        if not path.is_file() or path.is_symlink():
+            raise ValueError(f"Compose file is unavailable: {relative}")
+        argv.extend(("-f", str(path)))
+    for profile in profiles:
+        if not isinstance(profile, str) or not profile:
+            raise ValueError("deployment metadata has invalid Compose profile")
+        argv.extend(("--profile", profile))
+    argv.extend(("--env-file", str(release / "runtime.env"), *args))
+    return argv
+
+
+def _run_compose(release: Path, metadata: dict[str, object], *args: str) -> bool:
+    result = subprocess.run(_compose_argv(release, metadata, *args), cwd=release, check=False)
+    return result.returncode == 0
+
+
+def _runtime_environment(release: Path) -> dict[str, str]:
+    environment = os.environ.copy()
+    for line in (release / "runtime.env").read_text(encoding="utf-8").splitlines():
+        if not line or line.startswith("#"):
+            continue
+        key, separator, value = line.partition("=")
+        if not separator or re.fullmatch(r"[A-Z_][A-Z0-9_]*", key) is None:
+            raise ValueError("runtime environment contains an invalid assignment")
+        if value.startswith("'") and value.endswith("'"):
+            value = value[1:-1].replace("\\'", "'").replace("\\\\", "\\")
+        environment[key] = value
+    return environment
+
+
+def _contract_command(metadata: dict[str, object], name: str) -> tuple[str, ...]:
+    stateful = metadata.get("stateful", {})
+    if not isinstance(stateful, dict):
+        raise ValueError("deployment metadata has invalid stateful policy")
+    enabled = stateful.get("enabled", False)
+    if not isinstance(enabled, bool):
+        raise ValueError("deployment metadata has invalid stateful policy")
+    raw = stateful.get(name, [])
+    if not isinstance(raw, list) or any(not isinstance(item, str) or not item for item in raw):
+        raise ValueError(f"deployment metadata has invalid stateful {name} command")
+    if enabled and not raw:
+        raise ValueError(f"stateful deployment is missing the {name} command")
+    return tuple(raw)
+
+
+def _run_contract(
+    release: Path,
+    metadata: dict[str, object],
+    name: str,
+    *,
+    check: bool = True,
+) -> bool:
+    command = _contract_command(metadata, name)
+    if not command:
+        return True
+    account = pwd.getpwnam("devops")
+    environment = _runtime_environment(release)
+    environment.update(
+        {"HOME": account.pw_dir, "LOGNAME": account.pw_name, "USER": account.pw_name}
+    )
+    result = subprocess.run(
+        ("/usr/sbin/runuser", "--user", account.pw_name, "--", *command),
+        cwd=release,
+        env=environment,
+        check=False,
+    )
+    if check and result.returncode:
+        raise subprocess.CalledProcessError(result.returncode, command)
+    return result.returncode == 0
+
+
+def _validate_exposure(release: Path, metadata: dict[str, object]) -> None:
+    rendered = subprocess.run(
+        _compose_argv(release, metadata, "config", "--no-env-resolution", "--format", "json"),
+        cwd=release,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    payload = json.loads(rendered.stdout)
+    services = payload.get("services") if isinstance(payload, dict) else None
+    if not isinstance(services, dict):
+        raise ValueError("effective Compose model has no services")
+    for name, service in services.items():
+        if not isinstance(service, dict):
+            raise ValueError(f"invalid Compose service: {name}")
+        if service.get("network_mode") == "host":
+            raise ValueError(f"Compose service uses host networking: {name}")
+        if service.get("env_file"):
+            raise ValueError(f"Compose service uses an unmanaged environment file: {name}")
+        forbidden = {
+            "privileged mode": service.get("privileged") is True,
+            "host PID namespace": service.get("pid") == "host",
+            "host IPC namespace": service.get("ipc") == "host",
+            "host user namespace": service.get("userns_mode") == "host",
+            "added Linux capabilities": bool(service.get("cap_add")),
+            "host devices": bool(service.get("devices")),
+        }
+        unsafe = [label for label, present in forbidden.items() if present]
+        if unsafe:
+            raise ValueError(f"Compose service {name} uses unsafe privileges: {', '.join(unsafe)}")
+        security_options = service.get("security_opt", [])
+        if isinstance(security_options, list) and any(
+            "unconfined" in str(option).casefold() for option in security_options
+        ):
+            raise ValueError(f"Compose service disables confinement: {name}")
+        volumes = service.get("volumes", [])
+        if not isinstance(volumes, list):
+            raise ValueError(f"Compose service has invalid volumes: {name}")
+        for volume in volumes:
+            if not isinstance(volume, dict):
+                raise ValueError(f"Compose service has an unresolved volume: {name}")
+            if volume.get("type") == "bind":
+                raise ValueError(f"Compose service uses a host bind mount: {name}")
+            source = str(volume.get("source", ""))
+            target = str(volume.get("target", ""))
+            if "docker.sock" in source or "docker.sock" in target:
+                raise ValueError(f"Compose service mounts the Docker socket: {name}")
+        ports = service.get("ports", [])
+        if not isinstance(ports, list):
+            raise ValueError(f"Compose service has invalid ports: {name}")
+        for port in ports:
+            if isinstance(port, dict):
+                host_ip = port.get("host_ip")
+                if host_ip not in {"127.0.0.1", "::1", "localhost"}:
+                    raise ValueError(f"Compose service publishes a non-loopback port: {name}")
+            elif isinstance(port, str) and not port.startswith(("127.0.0.1:", "[::1]:")):
+                raise ValueError(f"Compose service publishes a non-loopback port: {name}")
+    volumes = payload.get("volumes", {})
+    if isinstance(volumes, dict):
+        for name, volume in volumes.items():
+            if isinstance(volume, dict) and volume.get("driver_opts"):
+                raise ValueError(f"Compose volume uses driver options: {name}")
+    secrets = payload.get("secrets", {})
+    if not isinstance(secrets, dict):
+        raise ValueError("Compose model has invalid secrets")
+    if secrets:
+        raise ValueError("Compose file-backed secrets are not supported")
+    configs = payload.get("configs", {})
+    if not isinstance(configs, dict):
+        raise ValueError("Compose model has invalid configs")
+    for name, entry in configs.items():
+        if not isinstance(entry, dict) or "file" not in entry:
+            continue
+        input_path = Path(str(entry["file"])).resolve()
+        if (
+            release.resolve() not in input_path.parents
+            or not input_path.is_file()
+            or input_path.is_symlink()
+        ):
+            raise ValueError(f"Compose configs input escapes the release: {name}")
+
+
+def _healthy(url: str, *, attempts: int = 12) -> bool:
+    for attempt in range(attempts):
+        try:
+            # urlopen follows redirects and raises HTTPError for any other final status.
+            with urllib.request.urlopen(url, timeout=5) as response:  # noqa: S310
+                if 200 <= response.status < 300:
+                    return True
+        except (OSError, urllib.error.URLError):
+            pass
+        if attempt + 1 < attempts:
+            time.sleep(5)
+    return False
+
+
+def _atomic_link(target: Path, destination: Path) -> None:
+    temporary = destination.parent / f".{destination.name}-next"
+    temporary.unlink(missing_ok=True)
+    temporary.symlink_to(target)
+    os.replace(temporary, destination)
+
+
+def _release_metadata(release: Path) -> dict[str, object] | None:
+    metadata = release / "deployment.json"
+    marker = release / ".ldw-deployed"
+    if (
+        not release.is_dir()
+        or release.is_symlink()
+        or not metadata.is_file()
+        or not marker.is_file()
+    ):
+        return None
+    payload = json.loads(metadata.read_text(encoding="utf-8"))
+    return payload if isinstance(payload, dict) else None
+
+
+def _current(root: Path) -> Path | None:
+    link = root / "current"
+    if not link.exists() and not link.is_symlink():
+        return None
+    if not link.is_symlink():
+        raise ValueError("current release pointer is not a symlink")
+    release = link.resolve(strict=True)
+    if release.parent != (root / "releases").resolve() or _release_metadata(release) is None:
+        raise ValueError("current release is not verified")
+    return release
+
+
+def _start(release: Path, metadata: dict[str, object]) -> bool:
+    _validate_exposure(release, metadata)
+    transport = metadata.get("artifact_transport")
+    if transport not in {"registry", "ssh-archive"}:
+        raise ValueError("deployment metadata has invalid artifact transport")
+    return _run_compose(
+        release,
+        metadata,
+        "up",
+        "-d",
+        "--wait",
+        "--wait-timeout",
+        "120",
+        "--pull",
+        "always" if transport == "registry" else "never",
+        "--remove-orphans",
+    ) and _healthy(_health_url(metadata.get("health_url")))
+
+
+def _stop(release: Path, metadata: dict[str, object]) -> bool:
+    return _run_compose(release, metadata, "stop")
+
+
+def deploy(project: str, build_id: str, metadata_name: str, metadata_sha256: str) -> int:
+    project = _component(project)
+    build_id = _component(build_id, build=True)
+    staged_metadata = _staged(metadata_name)
+    metadata = _metadata(staged_metadata, project, build_id, metadata_sha256)
+    bundle = _verified_staged(metadata.get("bundle"))
+    environment = _verified_staged(metadata.get("environment"))
+    provenance = _verified_staged(metadata.get("provenance"))
+    sbom = _verified_staged(metadata.get("sbom"))
+    image_record = metadata.get("image_archive")
+    image_archive = _verified_staged(image_record) if image_record is not None else None
+    root = PROJECTS_ROOT / project
+    releases = root / "releases"
+    release = releases / build_id
+    releases.mkdir(parents=True, exist_ok=True, mode=0o750)
+    if release.exists():
+        raise ValueError("release already exists")
+    release.mkdir(mode=0o755)
+    previous: Path | None = None
+    switched = False
+    try:
+        _safe_extract(bundle, release)
+        shutil.copyfile(environment, release / "runtime.env")
+        (release / "runtime.env").chmod(0o600)
+        shutil.copyfile(provenance, release / "provenance.json")
+        (release / "provenance.json").chmod(0o644)
+        shutil.copyfile(sbom, release / "sbom.cdx.json")
+        (release / "sbom.cdx.json").chmod(0o644)
+        if image_archive is not None:
+            subprocess.run([DOCKER, "load", "--input", str(image_archive)], check=True)
+        shutil.copyfile(staged_metadata, release / "deployment.json")
+        (release / "deployment.json").chmod(0o600)
+        previous = _current(root)
+        contract_root = previous or release
+        _run_contract(contract_root, metadata, "backup")
+        _run_contract(release, metadata, "migration")
+        if previous is not None:
+            _atomic_link(previous, root / "previous")
+        _atomic_link(release, root / "current")
+        switched = True
+        if _start(release, metadata) and _run_contract(release, metadata, "verify"):
+            (release / ".ldw-deployed").touch(mode=0o600)
+            _prune(root)
+            return 0
+        _stop(release, metadata)
+        _run_contract(release, metadata, "rollback", check=False)
+        if previous is not None:
+            previous_metadata = _release_metadata(previous)
+            _atomic_link(previous, root / "current")
+            if previous_metadata is not None:
+                _start(previous, previous_metadata)
+        else:
+            (root / "current").unlink(missing_ok=True)
+        shutil.rmtree(release, ignore_errors=True)
+        return 6
+    except BaseException:
+        if switched:
+            with suppress(OSError, ValueError, subprocess.SubprocessError):
+                _stop(release, metadata)
+            with suppress(OSError, ValueError, subprocess.SubprocessError):
+                _run_contract(release, metadata, "rollback", check=False)
+            if previous is not None:
+                _atomic_link(previous, root / "current")
+                previous_metadata = _release_metadata(previous)
+                if previous_metadata is not None:
+                    with suppress(OSError, ValueError, subprocess.SubprocessError):
+                        _start(previous, previous_metadata)
+            else:
+                (root / "current").unlink(missing_ok=True)
+        if not (release / ".ldw-deployed").exists():
+            shutil.rmtree(release, ignore_errors=True)
+        raise
+
+
+def rollback(project: str, build_id: str | None = None) -> int:
+    project = _component(project)
+    root = PROJECTS_ROOT / project
+    if build_id is None:
+        previous_link = root / "previous"
+        if not previous_link.is_symlink():
+            return 3
+        previous = previous_link.resolve(strict=True)
+        if previous.parent != (root / "releases").resolve():
+            raise ValueError("previous release pointer is invalid")
+        build_id = previous.name
+    build_id = _component(build_id, build=True)
+    target = root / "releases" / build_id
+    target_metadata = _release_metadata(target)
+    if target_metadata is None:
+        return 3
+    original = _current(root)
+    if original == target:
+        return 0 if _start(target, target_metadata) else 5
+    _atomic_link(target, root / "current")
+    try:
+        target_ready = _start(target, target_metadata)
+    except BaseException:
+        if original is not None:
+            _atomic_link(original, root / "current")
+        else:
+            (root / "current").unlink(missing_ok=True)
+        raise
+    if target_ready:
+        if original is not None:
+            _atomic_link(original, root / "previous")
+        return 0
+    _stop(target, target_metadata)
+    if original is None:
+        (root / "current").unlink(missing_ok=True)
+        return 6
+    original_metadata = _release_metadata(original)
+    _atomic_link(original, root / "current")
+    return 6 if original_metadata is not None and _start(original, original_metadata) else 7
+
+
+def _prune(root: Path) -> None:
+    protected = {path.resolve() for path in (root / "current", root / "previous") if path.exists()}
+    releases = sorted(
+        (path for path in (root / "releases").iterdir() if path.is_dir() and not path.is_symlink()),
+        key=lambda path: (path.stat().st_mtime_ns, path.name),
+        reverse=True,
+    )
+    keep = set(protected)
+    for release in releases:
+        if len(keep) >= 3:
+            break
+        keep.add(release.resolve())
+    for release in releases:
+        if release.resolve() not in keep:
+            shutil.rmtree(release)
+
+
+def status(project: str) -> int:
+    project = _component(project)
+    root = PROJECTS_ROOT / project
+    current = _current(root)
+    print(
+        json.dumps(
+            {
+                "project": project,
+                "current": current.name if current is not None else None,
+                "previous": (root / "previous").resolve().name
+                if (root / "previous").exists()
+                else None,
+            },
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def main() -> int:
+    try:
+        project = _component(sys.argv[2]) if len(sys.argv) >= 3 else ""
+        lock_path = Path("/run/lock") / f"ldw-{project}.lock"
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        with lock_path.open("a+b") as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            if len(sys.argv) == 6 and sys.argv[1] == "deploy":
+                return deploy(project, sys.argv[3], sys.argv[4], sys.argv[5])
+            if len(sys.argv) == 3 and sys.argv[1] == "rollback":
+                return rollback(project)
+            if len(sys.argv) == 4 and sys.argv[1] == "rollback":
+                return rollback(project, sys.argv[3])
+            if len(sys.argv) == 3 and sys.argv[1] == "status":
+                return status(project)
+    except (OSError, ValueError, json.JSONDecodeError, subprocess.SubprocessError) as error:
+        print(str(error), file=sys.stderr)
+        return 4
+    print(
+        "usage: ldw-remote-deploy deploy PROJECT BUILD METADATA SHA256 | "
+        "rollback PROJECT [BUILD] | status PROJECT",
+        file=sys.stderr,
+    )
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ldw_deploy/commands.py

@@ -0,0 +1,161 @@
+"""SSH target and production release commands."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Annotated
+
+import typer
+
+from ldw_deploy.service import SshDeploymentService
+from local_devops_workbench.plugin_api import (
+    PLUGIN_API_VERSION,
+    CommandContribution,
+    CoreHandle,
+    render_mapping,
+)
+
+TARGET_HELP = "Bind and inspect SSH production targets."
+DEPLOY_HELP = "Plan and apply immutable production releases."
+target_app = typer.Typer(no_args_is_help=True)
+deploy_app = typer.Typer(no_args_is_help=True)
+run = asyncio.run
+# Core passes one lazy handle to both registrations; commands read it when they run.
+_handles: list[CoreHandle] = []
+
+
+def register_target(handle: CoreHandle) -> CommandContribution:
+    _handles[:] = [handle]
+    return CommandContribution(
+        name="target", app=target_app, help=TARGET_HELP, api_version=PLUGIN_API_VERSION
+    )
+
+
+def register_deploy(handle: CoreHandle) -> CommandContribution:
+    _handles[:] = [handle]
+    return CommandContribution(
+        name="deploy", app=deploy_app, help=DEPLOY_HELP, api_version=PLUGIN_API_VERSION
+    )
+
+
+def _handle() -> CoreHandle:
+    if not _handles:
+        raise RuntimeError("ldw-deploy commands ran before core registered them")
+    return _handles[0]
+
+
+def deployments() -> SshDeploymentService:
+    handle = _handle()
+    return SshDeploymentService(handle.paths, handle.projects, handle.runner, handle.store)
+
+
+def _ensure_linked_project(project_id: str) -> None:
+    _handle().ensure_linked(project_id)
+
+
+@target_app.command("bind")
+def target_bind(
+    project_id: str,
+    target: str,
+    ssh_alias: Annotated[str, typer.Option("--ssh-alias")],
+    host_key_sha256: Annotated[str, typer.Option("--host-key-sha256")],
+    bootstrap_user: Annotated[str, typer.Option("--bootstrap-user")],
+    secret_command: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--secret-command",
+            help="One argv element for the external JSON secret provider; repeat as needed.",
+        ),
+    ] = None,
+    registry: Annotated[str | None, typer.Option("--registry")] = None,
+) -> None:
+    """Pin and bind an existing SSH host without changing it."""
+    _ensure_linked_project(project_id)
+    result = run(
+        deployments().bind(
+            project_id,
+            target,
+            ssh_alias=ssh_alias,
+            host_key_sha256=host_key_sha256,
+            bootstrap_user=bootstrap_user,
+            secret_command=tuple(secret_command or ()),
+            registry=registry,
+        )
+    )
+    render_mapping(
+        _handle().output.console,
+        f"{project_id}/{target} target bound",
+        result,
+        subtitle="Host key and machine identity pinned",
+    )
+
+
+@target_app.command("bootstrap")
+def target_bootstrap(project_id: str, target: str) -> None:
+    """Install the restricted deploy account and narrow root helper."""
+    _ensure_linked_project(project_id)
+    result = run(deployments().bootstrap(project_id, target))
+    render_mapping(_handle().output.console, f"{project_id}/{target} target bootstrapped", result)
+
+
+@target_app.command("status")
+def target_remote_status(
+    project_id: str,
+    target: str,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit stable JSON.")] = False,
+) -> None:
+    """Verify the pinned host identity and current release."""
+    _ensure_linked_project(project_id)
+    result = run(deployments().status(project_id, target))
+    if as_json:
+        _handle().output.print_json(result)
+    else:
+        render_mapping(_handle().output.console, f"{project_id}/{target} target", result)
+
+
+@deploy_app.command("plan")
+def deploy_plan(
+    project_id: str,
+    target: Annotated[str, typer.Option("--target")],
+    as_json: Annotated[bool, typer.Option("--json", help="Emit stable JSON.")] = False,
+) -> None:
+    """Create an immutable production deployment plan."""
+    _ensure_linked_project(project_id)
+    plan = run(deployments().plan(project_id, target))
+    payload = plan.model_dump(mode="json")
+    if as_json:
+        _handle().output.print_json(payload)
+        return
+    render_mapping(_handle().output.console, f"{project_id}/{target} deployment plan", payload)
+    _handle().output.console.print(
+        f"Apply exactly: ldw deploy apply {plan.plan_id} --expect-hash {plan.content_hash}"
+    )
+
+
+@deploy_app.command("apply")
+def deploy_apply(
+    plan_id: str,
+    expect_hash: Annotated[str, typer.Option("--expect-hash")],
+    as_json: Annotated[bool, typer.Option("--json", help="Emit stable JSON.")] = False,
+) -> None:
+    """Apply one exact, unchanged production deployment plan."""
+    result = run(deployments().apply(plan_id, expect_hash=expect_hash))
+    if as_json:
+        _handle().output.print_json(result)
+    else:
+        render_mapping(_handle().output.console, "Production deployment applied", result)
+
+
+@deploy_app.command("rollback")
+def deploy_rollback(
+    project_id: str,
+    target: Annotated[str, typer.Option("--target")],
+    as_json: Annotated[bool, typer.Option("--json", help="Emit stable JSON.")] = False,
+) -> None:
+    """Atomically activate the previous verified release."""
+    _ensure_linked_project(project_id)
+    result = run(deployments().rollback(project_id, target))
+    if as_json:
+        _handle().output.print_json(result)
+    else:
+        render_mapping(_handle().output.console, f"{project_id}/{target} rollback", result)