elan-cli 0.1.0__py3-none-any.whl

elan_cli/client.py

@@ -0,0 +1,115 @@
+"""Talking to the deploy service, with a token that is fresh when it is used.
+
+ONE PLACE THAT ATTACHES A CREDENTIAL, so there is one place to get it wrong.
+Every command goes through `Api`, which refreshes before it sends rather than
+after it fails — a token that expires mid-request comes back as a 401 the CLI
+cannot tell from a revoked session, and retrying a POST that may have been
+accepted is worse than not retrying it.
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from elan_cli import auth
+from elan_cli.config import Config
+
+
+class ApiError(Exception):
+    """A refusal from the service, already phrased for the developer."""
+
+
+class Api:
+    def __init__(self, config: Config, *, client: httpx.Client | None = None,
+                 tokens: auth.Tokens | None = None) -> None:
+        self.config = config
+        self._client = client or httpx.Client(timeout=120.0)
+        self._tokens = tokens
+
+    def token(self) -> str:
+        """An access token, refreshed only when there is not a live one.
+
+        THE CACHE IS WHY THIS IS NOT A ROUND TRIP EVERY TIME. `self._tokens`
+        lives on the instance, so a fresh process always started with none and
+        every command — `invoke`, `agents`, `status` — paid a keyring read, a
+        TLS handshake to the issuer and a token refresh before doing any work
+        of its own. Roughly a second, on commands whose own work is one API
+        call.
+        """
+        if self._tokens is not None and self._tokens.valid:
+            return self._tokens.access_token
+
+        # ACROSS PROCESSES, not just within one.
+        held = auth.cached_access(self.config.issuer)
+        if held is not None:
+            self._tokens = held
+            return held.access_token
+
+        stored = auth.stored(self.config.issuer)
+        if not stored:
+            raise ApiError("not signed in. Run `elan login`.")
+        self._tokens = auth.refresh(self.config, stored, client=self._client)
+        # ROTATION HANDLED, because an issuer may return a NEW refresh token
+        # and invalidate the old one. Keeping the original would work once and
+        # then sign the developer out with no explanation.
+        #
+        # AND THE ORDER MATTERS: `auth.store` clears the cached access token,
+        # so the new one is written AFTER it. Reversed, a rotation would
+        # silently discard the token it had just minted and the next command
+        # would refresh again — the cache would appear to do nothing.
+        if self._tokens.refresh_token:
+            auth.store(self.config.issuer, self._tokens.refresh_token)
+        auth.cache_access(self.config.issuer, self._tokens)
+        return self._tokens.access_token
+
+    def request(self, method: str, path: str, **kwargs) -> dict:
+        url = f"{self.config.api}{path}"
+        try:
+            response = self._client.request(
+                method, url,
+                headers={"Authorization": f"Bearer {self.token()}"}, **kwargs)
+        except httpx.HTTPError as exc:
+            raise ApiError(f"cannot reach {url}: {exc}") from exc
+
+        if response.status_code == 401:
+            raise ApiError(
+                "the service rejected your token. Run `elan login` again.")
+        if response.status_code == 403:
+            # 403 AND NOT 404 IS DELIBERATE ON THE SERVICE SIDE, so the message
+            # here should not soften it into "not found": the resource exists
+            # and belongs to somebody else.
+            raise ApiError(
+                "that belongs to another tenant. Your token says who you are, "
+                "and the path disagreed with it.")
+        if response.status_code == 404:
+            raise ApiError(f"no such thing: {path}")
+        if response.status_code >= 400:
+            raise ApiError(_refusal(response))
+        return response.json() if response.content else {}
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def _refusal(response: httpx.Response) -> str:
+    """The service's own problems, one per line.
+
+    `cross_check` returns EVERY problem rather than the first, and the CLI must
+    not collapse that back to one: a developer fixing one, pushing, and waiting
+    for the next is the afternoon the service's behaviour exists to prevent.
+    """
+    try:
+        payload = response.json()
+    except ValueError:
+        return f"HTTP {response.status_code}: {response.text[:300]}"
+
+    problems = payload.get("problems")
+    if problems:
+        lines = [f"refused — {len(problems)} problem(s):", ""]
+        for problem in problems:
+            lines.append(f"  {problem.get('where', '?')}")
+            for line in str(problem.get("message", "")).splitlines():
+                lines.append(f"    {line}")
+            lines.append("")
+        return "\n".join(lines).rstrip()
+    return payload.get("error") or f"HTTP {response.status_code}"

elan_cli/config.py

@@ -0,0 +1,139 @@
+"""Where the CLI points, and where it keeps what it is given.
+
+THE DEVELOPER SUPPLIES ONE THING: the platform's URL. Everything else about
+signing in — the issuer, the client id, the audience — is ASKED FOR at
+`GET /v1/auth` rather than configured. Nobody can be expected to know a
+generated project id, and making them paste one is how a command line tool
+acquires a setup page.
+
+It also makes rotation a server-side change. Re-pointing at a new issuer, or
+replacing the CLI's own application, would otherwise mean every developer
+re-running a configure command before anything worked again.
+
+TWO KINDS OF THING, KEPT APART. What is written here is PUBLIC: a URL, and the
+public sign-in values the platform answered with. All of them appear in a
+discovery document or in every token the issuer mints, so they live in an
+ordinary file a developer can read, diff and check into a team's dotfiles.
+CREDENTIALS ARE NOT HERE — they go to the OS keyring, which is the difference
+between a laptop that is lost and a laptop that is lost along with a
+credential in plaintext under the user's home directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+#: The platform this CLI is built for.
+#:
+#: EMPTY UNTIL THERE IS A PRODUCTION ONE, and empty rather than pointed at
+#: non-prod. A client that ships aimed at a staging environment is a client
+#: that quietly deploys somebody's first agent to the wrong place — and unlike
+#: a missing default, that failure does not announce itself. When production
+#: exists this becomes its URL and `--api` becomes the override for everyone
+#: else, which is how `gh` and `stripe` work and what a developer expects.
+DEFAULT_API = ""
+
+
+def config_home() -> Path:
+    """`$ELAN_HOME`, else XDG, else `~/.config/elan`.
+
+    XDG rather than `~/.elan`, because a dotfile per tool is how home
+    directories became unreadable. `$ELAN_HOME` exists so a test — or a
+    developer with two platforms — can point elsewhere without touching the
+    real one.
+    """
+    if override := os.environ.get("ELAN_HOME"):
+        return Path(override)
+    base = os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config"
+    return Path(base) / "elan"
+
+
+class ConfigError(Exception):
+    """Phrased for whoever has to fix it, which is always the developer."""
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """One platform, as the CLI talks to it."""
+
+    #: The only thing a developer supplies, and one day not even this.
+    api: str
+    #: Answered by the platform at `GET /v1/auth` and cached here so `whoami`
+    #: and `deploy` do not need a round trip before every request. Empty until
+    #: the first `elan login`.
+    issuer: str = ""
+    client_id: str = ""
+    audience: str = ""
+    token_scope: str = ""
+    """The whole OAuth scope to ask for, ANSWERED RATHER THAN COMPOSED.
+
+    `audience` alone was not enough: Zitadel addresses a token through a scope,
+    so a client has to send `urn:zitadel:iam:org:project:id:<audience>:aud` and a
+    token missing it is well-formed, correctly signed and refused everywhere.
+    Four places here built that string from `audience`; this is the platform
+    handing over the finished one.
+
+    Empty against a platform that predates it, and `scopes()` then composes it —
+    which is why `audience` is still cached.
+    """
+    device_url: str = ""
+    """Where to approve a device sign-in — OUR page, not the issuer's.
+
+    ANSWERED BY THE PLATFORM rather than composed here, for the same reason
+    every other value on this object is: the CLI knows one URL and asks for the
+    rest. Empty against a platform that predates it, and `elan login` then
+    falls back to the issuer's own `verification_uri` — a sign-in on the wrong
+    page beats one that cannot start.
+    """
+
+    @property
+    def signed_in_possible(self) -> bool:
+        return bool(self.issuer and self.client_id)
+
+    @classmethod
+    def load(cls) -> Config:
+        path = config_home() / "config.json"
+        data: dict = {}
+        if path.is_file():
+            try:
+                data = json.loads(path.read_text())
+            except ValueError as exc:
+                raise ConfigError(f"{path} is not valid JSON: {exc}") from exc
+
+        api = os.environ.get("ELAN_API") or data.get("api") or DEFAULT_API
+        if not api:
+            raise ConfigError(
+                "this CLI does not know which platform to talk to.\n"
+                "  Pass it once — `elan login --api https://your-platform` —\n"
+                "  and it is remembered. There is no built-in default yet,\n"
+                "  deliberately: a client aimed at the wrong environment\n"
+                "  deploys somebody's first agent there without saying so."
+            )
+        return cls(api=api.rstrip("/"), issuer=data.get("issuer", ""),
+                   client_id=data.get("client_id", ""),
+                   audience=data.get("audience", ""),
+                   token_scope=data.get("token_scope", ""),
+                   device_url=data.get("device_url", ""))
+
+    def save(self) -> Path:
+        path = config_home() / "config.json"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps({
+            "api": self.api, "issuer": self.issuer,
+            "client_id": self.client_id, "audience": self.audience,
+            "token_scope": self.token_scope, "device_url": self.device_url,
+        }, indent=2, sort_keys=True) + "\n")
+        # 0600 even though nothing here is secret. It costs nothing, and the
+        # day somebody adds a field that IS secret the file is already right.
+        path.chmod(0o600)
+        return path
+
+    def with_auth(self, discovered: dict) -> Config:
+        return Config(api=self.api, issuer=discovered["issuer"].rstrip("/"),
+                      client_id=discovered["client_id"],
+                      audience=discovered.get("audience", ""),
+                      token_scope=discovered.get("token_scope", ""),
+                      device_url=discovered.get("device_url", ""))

elan_cli/deploy.py

@@ -0,0 +1,247 @@
+"""`elan deploy` and `elan status`.
+
+A DEPLOY IS PROJECT-SCOPED, NOT AGENT-SCOPED, because one build serves the
+whole repo. What moves to the new image is decided by what CHANGED: a diff
+under one agent's directory moves that agent, a shared-code diff moves them
+all, and a target nobody touched keeps the digest it is already running. So the
+useful output is not "deployed" — it is a table saying which of your agents
+moved and which did not.
+
+`--target` NARROWS THE ROLLOUT, NEVER THE BUILD. There is one image per
+project; building a subset of a repo is not a thing that exists.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from pathlib import Path
+
+from elan_cli.client import Api, ApiError
+from elan_cli.project import Project, ProjectError, find
+
+#: How often to ask the service how it is getting on. A build takes minutes, so
+#: this is about the developer not staring at nothing rather than about
+#: latency.
+POLL_SECONDS = 5.0
+
+#: States the service will not move out of.
+TERMINAL = {"succeeded", "failed", "refused"}
+
+
+def resolve_ref(project: Project, ref: str) -> str:
+    """Turn whatever the developer said into a 40-character sha.
+
+    RESOLVED HERE AND WRITTEN INTO THE FILE, which is what makes a deployment
+    reproducible from `elan.yaml` alone. Submitting a branch name would mean
+    the build resolved it later — so two deploys of "main" could build
+    different code while both claiming to be the same deployment, and a
+    rollback would have nothing exact to go back to.
+    """
+    try:
+        out = subprocess.run(["git", "rev-parse", f"{ref}^{{commit}}"],
+                             cwd=project.root, capture_output=True, text=True)
+    except OSError as exc:
+        raise ProjectError(f"cannot run git: {exc}") from exc
+    if out.returncode != 0:
+        raise ProjectError(
+            f"git cannot resolve {ref!r} in {project.root}:\n"
+            f"  {out.stderr.strip()}"
+        )
+    return out.stdout.strip()
+
+
+def write_ref(project: Project, sha: str) -> bool:
+    """Rewrite `source.ref` in place, as a text edit.
+
+    A TEXT EDIT FOR THE SAME REASON `add_target` IS ONE: this file is mostly
+    comments, and a parse-and-dump would delete every one of them on every
+    deploy. Returns whether anything changed, so a re-deploy of the same commit
+    does not produce a diff.
+    """
+    if project.spec.source.ref == sha:
+        return False
+    lines = project.spec_path.read_text().splitlines(keepends=True)
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("ref:"):
+            indent = line[:len(line) - len(line.lstrip())]
+            lines[i] = f'{indent}ref: "{sha}"\n'
+            project.spec_path.write_text("".join(lines))
+            return True
+    raise ProjectError(
+        f"{project.spec_path} has no `ref:` line under `source:` to rewrite."
+    )
+
+
+def on_a_remote(project: Project, sha: str) -> bool:
+    """Whether any remote-tracking branch contains this commit.
+
+    ── WHY THIS IS CHECKED AT ALL ───────────────────────────────────────────
+    THE BUILDER CLONES THE REMOTE. `resolve_ref` turns whatever you said into a
+    local sha and writes it into `elan.yaml`, which is what makes a deployment
+    reproducible — but a commit that exists only on your machine cannot be
+    cloned by anything. Submitted anyway, the build runs for a minute or two
+    and dies inside a Cloud Build log with
+
+        fatal: reference is not a tree: 56ee2b5c847d…
+
+    which names neither the cause nor the fix, and reaches the developer as
+    `BuildFailed … run elan logs to see why`. One `git branch -r --contains`
+    answers it before anything is submitted.
+
+    ── AND WHY IT READS LOCAL REMOTE-TRACKING REFS ──────────────────────────
+    `git ls-remote` would be authoritative and costs a network round trip on
+    every deploy — and cannot answer "is my commit an ancestor of theirs"
+    without objects we may not have. Remote-tracking refs answer it offline and
+    are wrong only in the recoverable direction: a ref that is stale because you
+    pushed from somewhere else says "not pushed" for something that is, and the
+    refusal names `git fetch`.
+    """
+    out = subprocess.run(["git", "branch", "-r", "--contains", sha],
+                         cwd=project.root, capture_output=True, text=True)
+    # A REPOSITORY WITH NO REMOTE AT ALL is not this check's business — it
+    # fails `git`'s own way, and refusing here would only duplicate that.
+    if out.returncode != 0:
+        return True
+    return bool(out.stdout.strip())
+
+
+def run(api: Api, *, ref: str = "HEAD", wait: bool = True,
+        start: Path | None = None, sleep=time.sleep) -> int:
+    project = find(start)
+    sha = resolve_ref(project, ref)
+
+    # BEFORE THE SPEC IS REWRITTEN, so a refused deploy leaves no diff behind.
+    if not on_a_remote(project, sha):
+        raise ProjectError(
+            f"{sha[:12]} is not on any remote branch, and the build clones the "
+            f"remote — so this would fail with `reference is not a tree` after "
+            f"a minute of building.\n"
+            f"  git push                 if the commit is only here\n"
+            f"  git fetch                if you pushed it from somewhere else, "
+            f"so this check can see it"
+        )
+
+    if write_ref(project, sha):
+        print(f"{project.spec_path.name}: source.ref -> {sha}")
+        # RE-READ, because everything below reports on the spec as submitted
+        # and the one in memory is now one edit behind.
+        project = find(start)
+
+    print(f"deploying {project.spec.tenant}/{project.spec.project} at {sha[:12]}")
+
+    try:
+        accepted = api.request(
+            "POST", f"/v1/projects/{project.spec.project}/deployments",
+            json={"spec_yaml": project.spec_path.read_text(), "ref": sha},
+        )
+    except ApiError as exc:
+        print(f"\n{exc}")
+        return 1
+
+    deployment_id = accepted["deployment_id"]
+    print(f"  {deployment_id}")
+    if not wait:
+        print(f"\n  elan status {deployment_id}")
+        return 0
+
+    return _watch(api, deployment_id, sleep=sleep)
+
+
+def _watch(api: Api, deployment_id: str, *, sleep=time.sleep) -> int:
+    """Follow the phases, printing each one ONCE.
+
+    A line per poll would scroll a ten-minute build off the screen and bury the
+    one phase that mattered; a spinner would hide which phase is slow. So a
+    phase prints when it is entered and not again.
+    """
+    seen: str | None = None
+    while True:
+        try:
+            status = api.request("GET", f"/v1/deployments/{deployment_id}")
+        except ApiError as exc:
+            print(f"\n{exc}")
+            return 1
+
+        phase = status.get("phase")
+        if phase and phase != seen:
+            print(f"  {phase}")
+            seen = phase
+
+        if str(status.get("state")) in TERMINAL:
+            return report(status)
+        sleep(POLL_SECONDS)
+
+
+def report(status: dict) -> int:
+    """What happened, in the shape somebody actually asks about."""
+    state = str(status.get("state"))
+    print()
+
+    if problems := status.get("problems"):
+        print(f"refused — {len(problems)} problem(s):\n")
+        for problem in problems:
+            print(f"  {problem.get('where', '?')}")
+            for line in str(problem.get("message", "")).splitlines():
+                print(f"    {line}")
+            print()
+        return 1
+
+    if state == "failed":
+        print(f"failed: {status.get('error') or 'no reason recorded'}")
+        if status.get("needs_teardown"):
+            # SAID OUT LOUD, because a half-provisioned deploy leaves cloud
+            # resources that cost money and that nothing will clean up on its
+            # own. Discovering it on an invoice is the alternative.
+            print("\n  This deploy provisioned something before it failed.")
+            print("  Those resources still exist and are still billed.")
+        return 1
+
+    digest = status.get("digest") or ""
+    if digest:
+        print(f"image {digest}")
+
+    _rollout(status.get("rollout") or {}, digest)
+    _scan(status.get("scan") or {})
+    return 0
+
+
+def _rollout(rollout: dict, digest: str) -> None:
+    """Which targets moved, and which kept what they were running.
+
+    THE SECOND COLUMN IS THE POINT. Every target in the project is listed,
+    including the ones that did not move — because "what is my agent running"
+    is the question, and a list of only the changed ones cannot answer it.
+    """
+    if not rollout:
+        return
+    print("\n  target                     digest")
+    for slug, target_digest in sorted(rollout.items()):
+        shown = str(target_digest).rsplit("@", 1)[-1][:19] or "-"
+        moved = "  <- new" if digest and target_digest == digest else ""
+        print(f"  {slug:<26} {shown}{moved}")
+
+
+def _scan(scan: dict) -> None:
+    """WHETHER IT WAS SCANNED, not only what was found. A tenant reading
+    nothing cannot tell a clean image from one nobody looked at."""
+    if not scan:
+        return
+    if scan.get("skipped"):
+        print(f"\n  not scanned: {scan.get('reason', 'no reason recorded')}")
+        return
+    findings = scan.get("findings")
+    if findings:
+        print(f"\n  scan: {findings}")
+
+
+def status(api: Api, deployment_id: str) -> int:
+    try:
+        payload = api.request("GET", f"/v1/deployments/{deployment_id}")
+    except ApiError as exc:
+        print(exc)
+        return 1
+    print(f"{payload['deployment_id']}  {payload.get('state')}  "
+          f"{payload.get('phase') or ''}".rstrip())
+    return report(payload)

elan_cli/destroy.py

@@ -0,0 +1,77 @@
+"""`elan destroy` — remove an agent or a project and everything it was using.
+
+WHAT SURVIVES AND WHY. The IMAGE is left alone: targets share one image per
+repo, so deleting it would take every sibling with it. Artifact Registry's
+keep-recent policy collects superseded digests on its own, and the last
+target's removal is what makes the image collectable.
+
+WHAT DOES NOT SURVIVE is the agent's database, and that is why this asks for
+the name rather than a yes. The platform snapshots it first — ADR-0038 — so
+the data is recoverable for ninety days, but the deployment is not, and the
+difference between an agent that is gone and one that was never meant to be
+is a slug somebody typed while looking at something else.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from elan_cli.client import Api, ApiError
+from elan_cli.project import find
+
+
+def run(api: Api, agent: str = "", *, whole_project: bool = False,
+        assume_yes: bool = False) -> int:
+    project = find().spec.project
+    what = project if whole_project else agent
+    if not what:
+        print("Name an agent, or pass --project to destroy the whole thing.",
+              file=sys.stderr)
+        return 2
+
+    print(f"This removes {what!r} and everything provisioned for it:")
+    if whole_project:
+        print("  every agent in the project, its databases, topics, secrets,")
+        print("  its egress allocation and its namespace.")
+    else:
+        print("  its database, its topics, its secrets and its IAM.")
+    print("\nThe database is snapshotted first and kept for ninety days.")
+    print("The image is left alone — its siblings are running it.")
+
+    if not assume_yes:
+        # THE NAME, NOT A y/N. A yes is a keystroke somebody makes while
+        # reading the next line; typing the name is the one confirmation that
+        # cannot be given to the wrong thing by accident.
+        typed = input(f"\nType {what!r} to confirm: ").strip()
+        if typed != what:
+            print("Nothing was destroyed.")
+            return 1
+
+    path = (f"/v1/projects/{project}/destroy" if whole_project
+            else f"/v1/agents/{agent}?project={project}")
+    method = "POST" if whole_project else "DELETE"
+    try:
+        result = api.request(method, path, json={"confirm": what})
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    print(f"\nremoved       {result.get('removed', 0)}")
+    if result.get("already_gone"):
+        print(f"already gone  {result['already_gone']}")
+    if result.get("commit"):
+        print(f"commit        {result['commit']}")
+
+    failed = result.get("failed") or []
+    if failed:
+        # LISTED, NOT SUMMARISED. Each one is a resource still standing and
+        # still billing, and the operator needs to know which.
+        print(f"\n{len(failed)} could not be removed and still exist:",
+              file=sys.stderr)
+        for item in failed:
+            print(f"  {item.get('kind')}  {item.get('id')}: "
+                  f"{item.get('error')}", file=sys.stderr)
+        print("\nRe-running is safe: what is already gone is skipped.",
+              file=sys.stderr)
+        return 1
+    return 0

elan_cli/doctor.py

@@ -0,0 +1,63 @@
+"""`elan doctor` — does the platform's record match what exists?
+
+GHOSTS ARE WHAT THIS FINDS: a register row whose resource is gone. That is the
+direction provisioning creates deliberately — rows are written BEFORE the
+thing they describe, so a crash between the two leaves a row describing
+nothing. ADR-0038 calls that the safe failure, and safe is not harmless: a
+ghost makes `elan destroy` report success for a resource that was never there.
+
+ORPHANS — resources with no row — are not here, and the omission is honest.
+Finding one means enumerating every provider and then deciding whose it is,
+and a Postgres role carries no label to decide by. That is an operator's sweep
+across the whole platform, not a question a tenant can be given a scoped
+answer to.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from elan_cli.client import Api, ApiError
+
+
+def run(api: Api) -> int:
+    try:
+        report = api.request("GET", "/v1/doctor")
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    checked = report.get("checked", 0)
+    ghosts = report.get("ghosts") or []
+    unknown = report.get("unknown") or []
+
+    print(f"checked {checked} recorded resource"
+          f"{'' if checked == 1 else 's'}")
+
+    if not ghosts and not unknown:
+        print("Everything the platform recorded still exists.")
+        return 0
+
+    if ghosts:
+        print(f"\n{len(ghosts)} recorded but ABSENT at the provider:")
+        for item in ghosts:
+            where = "/".join(x for x in (item.get("project"),
+                                         item.get("agent")) if x)
+            print(f"  {item.get('kind'):<16} {item.get('id')}"
+                  f"{'  (' + where + ')' if where else ''}")
+        print("\nThese are safe — nothing is running that should not be — but "
+              "a destroy will report success for them.")
+
+    if unknown:
+        # SAID SEPARATELY FROM THE GHOSTS. "We could not tell" and "it is
+        # gone" are different answers, and collapsing them would turn a
+        # temporary API failure into a resource somebody goes looking for.
+        print(f"\n{len(unknown)} could not be checked:")
+        for item in unknown:
+            print(f"  {item.get('kind'):<16} {item.get('id')}: "
+                  f"{item.get('detail')}")
+
+    # NOT A FAILURE EXIT. A ghost is a bookkeeping discrepancy, not a broken
+    # deployment, and a non-zero exit here would fail somebody's CI for a
+    # condition that needs a person rather than a rollback.
+    return 0