devlift-cli 0.1.0__py3-none-any.whl

devlift_cli/ops/resources.py

@@ -0,0 +1,418 @@
+"""Create and update an S3 / SQS / DynamoDB resource.
+
+The create sequence, identical for every region-scoped resource:
+
+    1. resolve placement (app, env, region → codes)
+    2. validate the name locally, then with the server's duplicate check
+    3. show what will happen; confirm (or --yes)
+    4. POST /infrastructures                 → resource code
+    5. POST /transaction-queue/add-to-queue  → queue item
+    6. POST /transaction-queue/bulk-approve  → approved
+    7. POST /transaction-queue/deploy        → workflow (Temporal) or PR
+    8. --wait: poll the workflow to its end
+
+An update reads the row first (GET list → POST get-detail), shows the diff,
+then runs steps 4-8 with `code` set on step 4 — the same route upserts when
+it is given a code. Steps 4-7 are what the dashboard's create-and-deploy and
+the MCP's edit path do; nothing here is CLI-specific.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+from devlift_cli.api import infra, infra_list
+from devlift_cli.context import Invocation
+from devlift_cli.errors import EXIT_CONFLICT, EXIT_NOT_FOUND, CliError, InputError
+from devlift_cli.ops import wait
+from devlift_cli.ops.placement import canvas_placement, resolve_placement
+from devlift_cli.resolve import allowlist
+from devlift_cli.render import output
+from devlift_cli.render.output import kv_table, rows_table
+from devlift_cli.resolve.names import Placement, Resolver  # noqa: F401  (Placement used for the backfill lookup)
+
+
+@dataclass
+class ResourceKind:
+    noun: str                      # "bucket"
+    infra_type: str                # "s3_infrastructuretype_ref"
+    case_ref_code: str             # "create_bucket"
+    service: str = ""              # placement-allowlist key: "s3", "sqs", "dynamo"
+    name_key: str = "identifier"   # key of the name inside type_specific_config
+    validate_name: Callable[[str], str | None] = lambda _: None
+    labels: dict[str, str] = field(default_factory=dict)   # attribute key → label for the summary
+
+
+@dataclass
+class CreateResult:
+    resource_code: str
+    queue_id: int
+    queue_code: str
+    deploy: dict
+    workflow: dict | None = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "resource_code": self.resource_code,
+            "queue_id": self.queue_id,
+            "queue_code": self.queue_code,
+            "status": self.deploy.get("status"),
+            "workflow_id": self.deploy.get("workflow_id"),
+            "pr_url": self.deploy.get("pr_url"),
+            "pr_number": self.deploy.get("pr_number"),
+        }
+        if self.workflow:
+            data["workflow"] = self.workflow
+        return data
+
+
+def _is_duplicate(check: dict | None) -> str | None:
+    """Read the server's duplicate answer in whichever spelling it uses."""
+    if not check:
+        return None
+    message = check.get("message") or check.get("description") or "already exists"
+    for key in ("is_duplicate", "duplicate", "exists", "is_exists"):
+        if check.get(key) is True:
+            return str(message)
+    if check.get("is_valid") is False or check.get("valid") is False:
+        return str(message)
+    return None
+
+
+def create_resource(
+    inv: Invocation,
+    res: Resolver,
+    kind: ResourceKind,
+    *,
+    name: str,
+    app: str | None,
+    env: str | None,
+    region: str | None,
+    attributes: dict,
+    do_wait: bool = False,
+) -> CreateResult:
+    name = name.strip()
+    problem = kind.validate_name(name)
+    if problem:
+        raise InputError(f"{kind.noun.capitalize()} name: {problem}")
+
+    placement: Placement = resolve_placement(inv, res, app, env, region, service=kind.service or None)
+
+    duplicate = _is_duplicate(
+        infra.validate_duplicate(inv.api, kind.infra_type, placement.application_code, placement.environment, placement.geo_loc_mst_code, name)
+    )
+    if duplicate:
+        where = f"{placement.application_name}/{placement.environment}/{placement.region_name}"
+        text = duplicate if duplicate != "already exists" else f"A {kind.noun} named '{name}' already exists in {where}."
+        raise CliError(text, EXIT_CONFLICT, hint=f"Pick another name, or `devlift {kind.infra_type.split('_')[0]} describe {name} --env {placement.environment}`.")
+
+    # The canvas placement (account + cloud region). Stored in the locator, and
+    # the dashboard drops any resource that lacks it — so it is resolved here,
+    # shown in the summary, and its absence is said out loud before the
+    # confirmation rather than discovered later on an empty canvas.
+    canvas = canvas_placement(inv, placement)
+    config = {kind.name_key: name, **{k: v for k, v in attributes.items() if v is not None}, **canvas}
+
+    rows = [
+        (kind.noun.capitalize(), name),
+        ("Application", placement.application_name),
+        ("Environment", placement.environment),
+        ("Region", placement.region_name),
+    ]
+    if canvas:
+        rows += [("AWS account", canvas["accountId"]), ("Cloud region", canvas["cloudRegion"])]
+    rows += [(kind.labels.get(k, k), _show(v)) for k, v in config.items()
+             if k != kind.name_key and k not in canvas]
+    if inv.show_summary:
+        output.err_console.print(kv_table(rows, title=f"Create {kind.noun}"))
+    if not canvas:
+        output.warn(
+            f"No AWS account and cloud region could be resolved for {placement.region_name}. "
+            f"The {kind.noun} will deploy normally but will NOT appear on the dashboard canvas."
+        )
+    inv.confirm(f"Create this {kind.noun} and start its deployment?")
+
+    created = infra.create_infrastructure(
+        inv.api,
+        infra_type=kind.infra_type,
+        application_code=placement.application_code,
+        environment=placement.environment,
+        geo_loc_mst_code=placement.geo_loc_mst_code,
+        type_specific_config=config,
+    )
+    resource_code = created["code"]
+    output.info(f"Registered {kind.noun} {name} ({resource_code}).")
+
+    return _queue_and_deploy(
+        inv, kind,
+        resource_code=resource_code, name=name, config=config,
+        application_code=placement.application_code,
+        environment=placement.environment,
+        geo_loc_mst_code=placement.geo_loc_mst_code,
+        do_wait=do_wait,
+    )
+
+
+def _queue_and_deploy(
+    inv: Invocation,
+    kind: ResourceKind,
+    *,
+    resource_code: str,
+    name: str,
+    config: dict,
+    application_code: str,
+    environment: str,
+    geo_loc_mst_code: str,
+    do_wait: bool,
+) -> CreateResult:
+    """Steps 5-8: queue the row's current config, approve, deploy, optionally wait.
+
+    Shared by create and update — an update is queued under the same case ref
+    as a create (`create_bucket`, `create_queue`), because the generator
+    rebuilds the resource's terragrunt file from the full config either way;
+    that is also how the dashboard and the MCP's edit path do it.
+    """
+    snapshot = {
+        **config,
+        "applications_mst_code": application_code,
+        "environment": environment,
+        "geo_loc_mst_code": geo_loc_mst_code,
+        "case_ref_code": kind.case_ref_code,
+        "infrastructuretype_ref_code": kind.infra_type,
+        "infrastructure_mst_code": resource_code,
+    }
+    item = infra.add_to_queue(
+        inv.api,
+        transaction_code=resource_code,
+        table_name=infra.TABLE_INFRASTRUCTURE,
+        config_snapshot=snapshot,
+        case_ref_code=kind.case_ref_code,
+    )
+    queue_id, queue_code = int(item["id"]), item["code"]
+
+    approved = infra.bulk_approve(inv.api, [queue_id])
+    if not approved or int(approved.get("updated_count") or 0) < 1:
+        raise CliError(f"Queue item {queue_code} could not be approved: {approved}")
+
+    deploy = infra.deploy_queue_items(inv.api, [queue_id]) or {}
+    result = CreateResult(resource_code=resource_code, queue_id=queue_id, queue_code=queue_code, deploy=deploy)
+
+    if deploy.get("workflow_id"):
+        output.info(f"Deployment queued (workflow {deploy['workflow_id']}).")
+    elif deploy.get("pr_url"):
+        output.info(f"Pull request opened: {deploy['pr_url']}")
+    else:
+        output.info(f"Deployment status: {deploy.get('status')}")
+
+    if do_wait and deploy.get("workflow_id"):
+        result.workflow = wait.wait_for_workflow(inv.api, deploy["workflow_id"], label=f"deploying {name}")
+    elif do_wait:
+        output.warn("Nothing to wait for: the server did not return a workflow id.")
+    return result
+
+
+# ── update ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class UpdateResult:
+    resource_code: str
+    name: str
+    changed: bool
+    diff: list[tuple[str, object, object]]          # (field, current, new)
+    result: CreateResult | None = None               # None when nothing changed
+
+    def to_dict(self) -> dict:
+        data = {
+            "resource_code": self.resource_code,
+            "changed": self.changed,
+            "changes": {f: {"from": a, "to": b} for f, a, b in self.diff},
+        }
+        if self.result:
+            data.update(self.result.to_dict())
+        else:
+            data["status"] = "unchanged"
+        return data
+
+
+def _comparable(value):
+    """Normalise before comparing a flag value with the stored one.
+
+    The stored locator holds booleans as real booleans when the dashboard's
+    canvas wrote them and as "true"/"false" strings when a form did, and
+    numbers arrive either way. Comparing raw would report a change on a value
+    nobody touched — the same rule the MCP's edit path applies."""
+    if isinstance(value, bool) or value is None:
+        return value
+    if isinstance(value, (int, float)):
+        return str(value)
+    text = str(value).strip()
+    if text.lower() in ("true", "false"):
+        return text.lower() == "true"
+    return text
+
+
+def update_resource(
+    inv: Invocation,
+    res: Resolver,
+    kind: ResourceKind,
+    *,
+    name: str,
+    env: str | None,
+    changes: dict,
+    app: str | None = None,
+    check: Callable[[dict], str | None] | None = None,
+    do_wait: bool = False,
+) -> UpdateResult:
+    """Change settings on an existing resource: read the row, diff, confirm,
+    upsert the FULL config with the edits laid over it, queue, deploy.
+
+    The full stored set goes back, not just the changed keys: the generator
+    rebuilds the resolved AWS name from whatever it is handed and defaults
+    anything missing — an absent fifo flag reads as False and points the row
+    at a queue that does not exist. Name and identity fields are never among
+    `changes`; a rename is a new resource. `check` sees the merged config and
+    may veto it (replication without a target account, say).
+    """
+    row = find_resource(inv, res, kind, name, env=env)
+    detail = infra_list.get_infrastructure(inv.api, row["code"]) or {}
+    stored = dict(detail.get("locator") or row.get("locator") or {})
+    resource_code = detail.get("code") or row["code"]
+    shown = infra_list.display_name(detail if detail.get("locator") else row)
+
+    def first(*keys):
+        for source in (detail, row):
+            for key in keys:
+                if source.get(key):
+                    return source[key]
+        return None
+
+    environment = first("environment")
+    geo_loc_mst_code = first("geo_loc_mst_code")
+    if not (environment and geo_loc_mst_code):
+        raise CliError(
+            f"Cannot read where {kind.noun} '{shown}' lives (environment / region), so it cannot be updated from here.",
+            hint="Change it in the DevLift dashboard.",
+        )
+
+    # The application. Older backends do not report it on an infrastructure
+    # row, and the update route requires it. Rather than demand --app, infer
+    # it: only one application can offer this kind of resource in this exact
+    # placement, so when the allowlist leaves exactly one, that is the answer.
+    application_code = res.application(app)["application_code"] if app else first(
+        "applications_mst_code", "application_code", "application_mst_code"
+    )
+    if not application_code:
+        here = [
+            r for r in allowlist.filter_placements(res.placements(), res.tenant_code(), kind.service or None)
+            if r["environment"] == environment and r["geo_loc_mst_code"] == geo_loc_mst_code
+        ]
+        candidates = {r["application_code"]: r["product"] for r in here}
+        if len(candidates) == 1:
+            application_code, product = next(iter(candidates.items()))
+            output.info(f"Application not reported by this backend; {product} is the only one with {kind.noun}s in {environment}.")
+        else:
+            raise InputError(
+                f"This DevLift backend does not say which application {kind.noun} '{shown}' belongs to.",
+                hint="Pass --app NAME (`devlift applications list`)." if candidates
+                     else "Pass --app NAME; no placement matches this resource's environment and region.",
+            )
+
+    # Repair a row written without the canvas placement (an older CLI create):
+    # the resource is invisible on the dashboard until its locator names an
+    # account and a cloud region, and an update is the natural moment to add
+    # them, since it rewrites the whole locator anyway.
+    backfill: dict = {}
+    if not (stored.get("cloudRegionId") and stored.get("accountId")):
+        backfill = canvas_placement(inv, Placement(
+            application_code=application_code, application_name=application_code,
+            environment=environment, geo_loc_mst_code=geo_loc_mst_code, region_name=geo_loc_mst_code,
+        ))
+
+    diff = [(f, stored.get(f), v) for f, v in changes.items() if _comparable(stored.get(f)) != _comparable(v)]
+    if not diff and not backfill:
+        output.info(f"{kind.noun.capitalize()} '{shown}' already has those values. Nothing to change.")
+        return UpdateResult(resource_code=resource_code, name=shown, changed=False, diff=[])
+    if backfill:
+        output.info(
+            f"Adding the missing dashboard placement (account {backfill['accountId']}, "
+            f"{backfill['cloudRegion']}) so '{shown}' appears on the canvas."
+        )
+
+    config = {**stored, **changes, **backfill}
+    problem = check(config) if check else None
+    if problem:
+        raise InputError(problem)
+
+    if inv.show_summary:
+        output.err_console.print(rows_table(
+            ["Field", "Current", "New"],
+            [(kind.labels.get(f, f), _show(a) if a not in (None, "", []) else "–", _show(b) if b not in (None, "", []) else "–") for f, a, b in diff],
+            title=f"Update {kind.noun} {shown} ({environment})",
+        ))
+    inv.confirm(f"Apply these changes to {kind.noun} '{shown}' and start its deployment?")
+
+    updated = infra.create_infrastructure(
+        inv.api,
+        infra_type=kind.infra_type,
+        application_code=application_code,
+        environment=environment,
+        geo_loc_mst_code=geo_loc_mst_code,
+        type_specific_config=config,
+        code=resource_code,                  # upsert: the same route updates when the code is given
+    )
+    resource_code = (updated or {}).get("code") or resource_code
+    output.info(f"Updated {kind.noun} {shown} ({resource_code}).")
+
+    result = _queue_and_deploy(
+        inv, kind,
+        resource_code=resource_code, name=shown, config=config,
+        application_code=application_code, environment=environment, geo_loc_mst_code=geo_loc_mst_code,
+        do_wait=do_wait,
+    )
+    return UpdateResult(resource_code=resource_code, name=shown, changed=True, diff=diff, result=result)
+
+
+def list_resources(inv: Invocation, res: Resolver, kind: ResourceKind, *, app: str | None, env: str | None, region: str | None) -> list[dict]:
+    application_code = res.application(app)["application_code"] if app else None
+    environment = res.environment(env) if env else None
+    geo = None
+    if region:
+        rows = res.regions_for(application_code, environment)
+        match = [r for r in rows if region.lower() in (r["region"].lower(), r["geo_loc_mst_code"].lower())]
+        if not match:
+            raise InputError(f"Unknown region '{region}'. See `devlift regions list`.")
+        geo = match[0]["geo_loc_mst_code"]
+    return infra_list.list_infrastructures(inv.api, infra_type=kind.infra_type, environment=environment, geo_loc_mst_code=geo, application_code=application_code)
+
+
+def find_resource(inv: Invocation, res: Resolver, kind: ResourceKind, name: str, *, env: str | None = None) -> dict:
+    """One row by user-typed name (or code); env narrows when the name repeats."""
+    environment = res.environment(env) if env else None
+    rows = infra_list.list_infrastructures(inv.api, infra_type=kind.infra_type, environment=environment)
+    needle = name.strip().lower()
+    hits = [r for r in rows if needle in (infra_list.display_name(r).lower(), str(r.get("code") or "").lower(), str(r.get("name") or "").lower())]
+    if not hits:
+        raise CliError(f"No {kind.noun} named '{name}'" + (f" in {environment}" if environment else "") + ".", EXIT_NOT_FOUND)
+    if len(hits) > 1:
+        where = ", ".join(f"{infra_list.display_name(r)} ({r.get('environment')}/{r.get('geo_loc_mst_code')})" for r in hits)
+        raise InputError(f"'{name}' matches several {kind.noun}s: {where}", hint="Add --env (and check the region).")
+    return hits[0]
+
+
+def describe_resource(inv: Invocation, res: Resolver, kind: ResourceKind, name: str, *, env: str | None = None) -> dict:
+    row = find_resource(inv, res, kind, name, env=env)
+    detail = infra_list.get_infrastructure(inv.api, row["code"])
+    detail.setdefault("status", row.get("status"))
+    detail.setdefault("derived_variables", row.get("derived_variables"))
+    return detail
+
+
+def _show(value) -> str:
+    if isinstance(value, bool):
+        return "yes" if value else "no"
+    if isinstance(value, str) and value.lower() in ("true", "false"):
+        return "yes" if value.lower() == "true" else "no"
+    if isinstance(value, list):
+        return ", ".join(str(v) for v in value)
+    return str(value)

devlift_cli/ops/status.py

@@ -0,0 +1,152 @@
+"""Deployment and application status: the two different questions.
+
+`deployment` — did DevLift's own pipeline finish? Read from the deployment
+history the dashboard's tracker shows: one workflow, its stages, its PR.
+
+`application` — is the service actually serving? DevLift's pipeline turns
+green when the manifests are merged, before ArgoCD has rolled a pod. That is
+asked of ArgoCD, through the same implementation the assistant's
+get_application_status tool uses, and compared against the deploy's finish
+time so a stale "Healthy" from the previous revision is not mistaken for the
+new one.
+"""
+
+from __future__ import annotations
+
+from devlift_cli.api import deployments as deployments_api
+from devlift_cli.api import infra
+from devlift_cli.context import Invocation
+from devlift_cli.errors import EXIT_NOT_FOUND, CliError
+from devlift_cli.ops import wait
+from devlift_cli.render import output
+from devlift_cli.render.output import kv_table, rows_table
+
+_STATUS_TEXT = {"RUNNING": "running", "COMPLETED": "completed", "FAILED": "failed", "TIMEOUT": "timed out", "TIMEDOUT": "timed out", "CANCELLED": "cancelled"}
+
+
+def _ts(value) -> str:
+    return str(value or "")[:19].replace("T", " ")
+
+
+def _duration(row: dict) -> str:
+    seconds = row.get("duration_seconds")
+    if seconds is None:
+        return ""
+    seconds = int(seconds)
+    return f"{seconds // 60}m {seconds % 60:02d}s" if seconds >= 60 else f"{seconds}s"
+
+
+def stage_line(detail: dict) -> str:
+    """One line for a spinner: the newest stage and the workflow status."""
+    status = str(detail.get("status") or "").upper()
+    stages = detail.get("stages") or []
+    text = _STATUS_TEXT.get(status, status.lower() or "starting")
+    if stages:
+        last = stages[-1]
+        text += f" — {last.get('name')}: {last.get('status')}"
+        if last.get("error"):
+            text += f" ({last['error']})"
+    if detail.get("pr_url"):
+        text += f" (PR #{detail.get('pr_number')})"
+    return text
+
+
+def deployment_detail(inv: Invocation, workflow_id: str, *, do_wait: bool) -> dict:
+    """The history row with stages; polled to a terminal status with --wait.
+    Falls back to the transaction-queue step query for a workflow the history
+    does not know (an older id)."""
+    try:
+        detail = deployments_api.history_detail(inv.api, workflow_id)
+    except CliError as exc:
+        if exc.code != EXIT_NOT_FOUND:
+            raise
+        state = wait.wait_for_workflow(inv.api, workflow_id, label="deployment") if do_wait else (infra.deploy_status(inv.api, workflow_id) or {})
+        return {"workflow_id": workflow_id, "status": str(state.get("step") or "").upper(), "stages": [], "legacy": state}
+    if not do_wait or str(detail.get("status") or "").upper() in deployments_api.TERMINAL:
+        return detail
+
+    last = {"detail": detail}
+
+    def describe():
+        last["detail"] = deployments_api.history_detail(inv.api, workflow_id)
+        status = str(last["detail"].get("status") or "").upper()
+        done = status in deployments_api.TERMINAL
+        return stage_line(last["detail"]), done, done and status != "COMPLETED"
+
+    wait.poll(describe, label="deployment")
+    return last["detail"]
+
+
+def history_table(rows: list[dict]):
+    return rows_table(
+        ["Workflow", "Status", "Started", "Duration", "Application", "Env", "Resources", "PR", "By"],
+        [(r.get("workflow_id"), _STATUS_TEXT.get(str(r.get("status") or "").upper(), r.get("status")), _ts(r.get("started_at")), _duration(r),
+          r.get("application_name"), r.get("environment"),
+          "\n".join(x.get("display_name") or x.get("transaction_code") or "" for x in r.get("resources") or []),
+          f"#{r['pr_number']}" if r.get("pr_number") else "–", r.get("user_name")) for r in rows],
+    )
+
+
+def print_deployment(detail: dict) -> None:
+    output.err_console.print(kv_table([
+        ("Workflow", detail.get("workflow_id")),
+        ("Status", _STATUS_TEXT.get(str(detail.get("status") or "").upper(), detail.get("status"))),
+        ("Started", _ts(detail.get("started_at"))),
+        ("Finished", _ts(detail.get("completed_at")) or "–"),
+        ("Duration", _duration(detail) or "–"),
+        ("Application", f"{detail.get('application_name')} / {detail.get('environment')} / {detail.get('geo_name')}"),
+        ("Pull request", detail.get("pr_url") or "–"),
+        ("Started by", detail.get("user_name")),
+    ] + [("Resource", f"{x.get('display_name')}  [{x.get('queue_status')}]") for x in detail.get("resources") or []], title="Deployment"))
+    stages = detail.get("stages") or []
+    if stages:
+        output.err_console.print(rows_table(
+            ["Stage", "Status", "Started", "Ended", "Error"],
+            [(s.get("name"), s.get("status"), _ts(s.get("started_at")), _ts(s.get("ended_at")), s.get("error") or "") for s in stages],
+            title="Stages",
+        ))
+    elif detail.get("legacy"):
+        output.err_console.print(kv_table([("Step", detail["legacy"].get("step")), ("Result", detail["legacy"].get("result"))]))
+
+
+# ── application (ArgoCD) ─────────────────────────────────────────────────────
+
+def latest_deployment_for(inv: Invocation, *, application_code: str, environment: str, config_code: str) -> dict | None:
+    rows, _ = deployments_api.history(inv.api, application_code=application_code, environment=environment, limit=100)
+    for r in rows:                                   # newest first
+        if any(x.get("transaction_code") == config_code for x in r.get("resources") or []):
+            return r
+    return None
+
+
+def application_status(inv: Invocation, config_code: str, workflow_id: str | None, *, do_wait: bool) -> dict:
+    """ArgoCD's view of the service; with --wait, polled until it settles."""
+    result = deployments_api.application_status(inv.api, config_code, workflow_id)
+    if not do_wait or result.get("settled", True):
+        return result
+    last = {"r": result}
+
+    def describe():
+        last["r"] = deployments_api.application_status(inv.api, config_code, workflow_id)
+        r = last["r"]
+        text = f"{r.get('state')}" + (f" (health {r.get('health_status')}, sync {r.get('sync_status')})" if r.get("health_status") else "")
+        settled = bool(r.get("settled", True))
+        return text, settled, settled and r.get("state") in ("unhealthy", "not_picked_up", "missing", "unavailable")
+
+    try:
+        wait.poll(describe, interval=10.0, timeout=600.0, label="application")
+    except CliError:
+        pass                                          # the state itself is the answer; printed below
+    return last["r"]
+
+
+def print_application(result: dict) -> None:
+    output.err_console.print(kv_table([
+        ("State", result.get("state")),
+        ("", result.get("message")),
+        ("Health", result.get("health_status") or "–"),
+        ("Sync", result.get("sync_status") or "–"),
+        ("Running image", result.get("running_image") or "–"),
+        ("ArgoCD", result.get("argocd_url") or "–"),
+        ("Health URL", result.get("health_url") or "–"),
+    ], title="Application (ArgoCD)"))

devlift_cli/ops/wait.py

@@ -0,0 +1,82 @@
+"""Polling with a spinner, for --wait."""
+
+from __future__ import annotations
+
+import time
+from typing import Callable
+
+from rich.live import Live
+from rich.spinner import Spinner
+from rich.text import Text
+
+from devlift_cli.api import infra
+from devlift_cli.api.client import ApiClient
+from devlift_cli.errors import EXIT_ERROR, CliError
+from devlift_cli.render import output
+
+# DeploymentWorkflow steps, in the order they normally happen.
+_STEP_TEXT = {
+    "acquiring_locks": "acquiring locks",
+    "creating_pr": "creating pull request",
+    "waiting_for_plan": "waiting for terraform plan",
+    "verifying_plan": "verifying plan",
+    "waiting_for_approval": "waiting for PR approval",
+    "waiting_for_apply": "applying",
+    "posting_apply_comment": "applying",
+    "waiting_for_merge": "waiting for merge",
+    "active": "done",
+    "completed": "done",
+    "failed": "failed",
+}
+_TERMINAL_OK = {"active", "completed", "done", "succeeded", "success"}
+_TERMINAL_FAIL = {"failed", "error", "cancelled", "canceled"}
+
+
+def poll(describe: Callable[[], tuple[str, bool, bool]], interval: float = 5.0, timeout: float = 3600.0, label: str = "deploying") -> None:
+    """Call `describe()` until it reports done. It returns (status_line, done, failed)."""
+    deadline = time.time() + timeout
+    spinner = Spinner("dots", text=Text(label))
+    with Live(spinner, console=output.err_console, refresh_per_second=8, transient=True):
+        while True:
+            line, done, failed = describe()
+            spinner.text = Text(f"{label}: {line}")
+            if done:
+                break
+            if time.time() > deadline:
+                raise CliError(f"Gave up waiting after {int(timeout)}s (last status: {line}).", EXIT_ERROR)
+            time.sleep(interval)
+    if failed:
+        raise CliError(f"Deployment failed: {line}", EXIT_ERROR)
+    output.success(f"{label}: {line}")
+
+
+def wait_for_workflow(api: ApiClient, workflow_id: str, label: str = "deploying") -> dict:
+    """Follow a transaction-queue DeploymentWorkflow to its end; return the last state."""
+    last: dict = {}
+    hiccups = 0
+
+    def describe() -> tuple[str, bool, bool]:
+        nonlocal last, hiccups
+        try:
+            last = infra.deploy_status(api, workflow_id) or {}
+            hiccups = 0
+        except CliError as exc:
+            # The status route answers 503 while the workflow service is busy;
+            # the deployment itself is unaffected. Keep polling for a while.
+            if not exc.transient or hiccups >= 12:
+                raise
+            hiccups += 1
+            return f"{_STEP_TEXT.get(str(last.get('step') or '').lower(), 'waiting for status')} (status service busy, retry {hiccups})", False, False
+        step = str(last.get("step") or "").lower()
+        result = last.get("result") or {}
+        text = _STEP_TEXT.get(step, step or "starting")
+        if last.get("pr_number") and last.get("repo_full_name"):
+            text += f" (PR #{last['pr_number']} on {last['repo_full_name']})"
+        failed = step in _TERMINAL_FAIL or (isinstance(result, dict) and str(result.get("status", "")).lower() in _TERMINAL_FAIL)
+        done = failed or step in _TERMINAL_OK or (isinstance(result, dict) and bool(result) and str(result.get("status", "")).lower() in _TERMINAL_OK)
+        if failed and isinstance(result, dict) and result.get("error"):
+            text += f": {result['error']}"
+        return text, done, failed
+
+    poll(describe, label=label)
+    return last