prhub 0.1.0__py3-none-any.whl

prhub/__init__.py

@@ -0,0 +1,2 @@
+"""prhub: one GitHub poller for many coding agents."""
+__version__ = "0.1.0"

prhub/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

prhub/cli.py

@@ -0,0 +1,426 @@
+"""prhub CLI. Everything except `daemon` reads local files only and never calls GitHub."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+
+from . import __version__, commits, store
+from .conditions import CONDITIONS, evaluate, is_done, one_line
+from .refs import RefResolver
+
+EXIT_MET, EXIT_TIMEOUT, EXIT_IMPOSSIBLE, EXIT_NO_DAEMON = 0, 1, 3, 4
+
+
+def caller() -> str:
+    """Who is waiting, recorded with each watch: PRHUB_CALLER, else a terminal-multiplexer pane id, else "cli"."""
+    for var in ("PRHUB_CALLER", "HERDR_PANE_ID", "TMUX_PANE"):
+        if os.environ.get(var):
+            return os.environ[var]
+    return "cli"
+
+
+def resolver(cfg: dict) -> RefResolver:
+    from .refs import index_clones
+    cache = store.home() / "repos.json"
+    repos = store.read_json(cache)
+    if not repos or time.time() - cache.stat().st_mtime > 6 * 3600:
+        repos = index_clones(cfg["clone_roots"])
+        store.write_json(cache, repos)
+    return RefResolver(cfg.get("aliases") or {}, repos)
+
+
+def _record(ref):
+    rec = store.read_pr(ref)
+    return rec, (rec or {}).get("summary")
+
+
+def _commit_record(ref, fresh: bool):
+    """The commit's record, asking the daemon for a poll (<= 90 s) when there is none yet or `fresh`."""
+    store.add_commit_watch(ref, by=caller())
+    rec = store.read_commit(ref)
+    if rec is None or fresh:
+        store.nudge()
+        start = time.time()
+        while time.time() < start + 90:
+            rec = store.read_commit(ref)
+            if rec and rec["fetched_at"] >= start - 1:
+                break
+            time.sleep(2)
+    return rec
+
+
+def cmd_state_commit(a, cfg) -> int:
+    ref = commits.resolve(a.pr, resolver(cfg))
+    rec = _commit_record(ref, a.fresh)
+    if rec is None:
+        print(f"{ref}: no data yet (is `prhub daemon` running? see `prhub status`)", file=sys.stderr)
+        return EXIT_NO_DAEMON
+    if rec.get("missing"):
+        print(f"{ref}: GitHub has no such commit (typo, or not pushed yet)", file=sys.stderr)
+        return 2
+    s = rec["summary"]
+    if a.json:
+        state, failed = commits.rollup(s, a.workflow)
+        print(json.dumps({"ref": rec["ref"], "fetched_at": rec["fetched_at"], "checks": state, "failing": failed, **s}))
+    else:
+        print(commits.one_line(rec["ref"], s, a.workflow) + f"  ({int(time.time() - rec['fetched_at'])}s old)")
+    return 0
+
+
+def cmd_wait_commit(a, cfg) -> int:
+    ref = commits.resolve(a.pr, resolver(cfg))
+    conds = [c.strip() for c in a.until.split(",")]
+    for c in conds:
+        if c not in commits.CONDITIONS:
+            print(f"unknown condition '{c}' for a commit (use: {', '.join(commits.CONDITIONS)})", file=sys.stderr)
+            return 2
+    if not store.daemon_healthy():
+        print("prhub daemon is not polling (see `prhub status`); start it with `prhub install-launchd` (macOS) or `prhub install-systemd` (Linux)",
+              file=sys.stderr)
+        return EXIT_NO_DAEMON
+    store.add_commit_watch(ref, by=caller())
+    store.nudge()
+    start = time.time()
+    baseline = None
+    last_line = None
+    next_touch = start + 1800
+    while time.time() < start + a.timeout:
+        rec = store.read_commit(ref)
+        if rec and rec["fetched_at"] >= start - 1:
+            if rec.get("missing"):
+                print(f"{ref}: GitHub has no such commit (typo, or not pushed yet)", file=sys.stderr)
+                return 2
+            s = rec["summary"]
+            baseline = baseline or s
+            line = commits.one_line(rec["ref"], s, a.workflow)
+            for c in conds:
+                met, dead = commits.evaluate(c, s, baseline, a.env, a.workflow)
+                if met:
+                    print(f"{c}: {line}")
+                    return EXIT_MET
+                if dead:
+                    print(f"cannot reach {c} ({dead}): {line}")
+                    return EXIT_IMPOSSIBLE
+            last_line = line
+        if time.time() > next_touch:  # a long wait keeps its commit watch from expiring
+            store.add_commit_watch(ref)
+            next_touch = time.time() + 1800
+        if not store.daemon_healthy(max_age=max(300, 3 * store.daemon_state().get("interval", 60))):
+            print("prhub daemon stopped polling while waiting", file=sys.stderr)
+            return EXIT_NO_DAEMON
+        time.sleep(a.poll)
+    print("timeout: " + (last_line or f"{ref}: no fresh data"))
+    return EXIT_TIMEOUT
+
+
+def cmd_state(a, cfg) -> int:
+    if commits.is_commit_text(a.pr):
+        return cmd_state_commit(a, cfg)
+    ref = resolver(cfg).resolve(a.pr)
+    store.add_watch(ref)
+    rec, s = _record(ref)
+    if rec is None or a.fresh:
+        store.nudge()
+        deadline = time.time() + 90
+        start = time.time()
+        while time.time() < deadline:
+            rec, s = _record(ref)
+            if rec and rec["fetched_at"] >= start - 1:
+                break
+            time.sleep(2)
+    if rec is None:
+        print(f"{ref}: no data yet (is `prhub daemon` running? see `prhub status`)", file=sys.stderr)
+        return EXIT_NO_DAEMON
+    if a.json:
+        print(json.dumps({"ref": rec["ref"], "fetched_at": rec["fetched_at"], **s, "failing": rec.get("failing", [])}))
+    else:
+        age = int(time.time() - rec["fetched_at"])
+        print(one_line(rec["ref"], s, rec.get("failing")) + f"  ({age}s old)")
+    return 0
+
+
+def cmd_wait(a, cfg) -> int:
+    if commits.is_commit_text(a.pr):
+        return cmd_wait_commit(a, cfg)
+    ref = resolver(cfg).resolve(a.pr)
+    conds = [c.strip() for c in a.until.split(",")]
+    for c in conds:
+        if c not in CONDITIONS:
+            print(f"unknown condition '{c}' (use: {', '.join(CONDITIONS)})", file=sys.stderr)
+            return 2
+    if not store.daemon_healthy():
+        print("prhub daemon is not polling (see `prhub status`); start it with `prhub install-launchd` (macOS) or `prhub install-systemd` (Linux)",
+              file=sys.stderr)
+        return EXIT_NO_DAEMON
+    store.add_watch(ref, by=caller())
+    store.nudge()
+    start = time.time()
+    deadline = start + a.timeout
+    merge_states = cfg["done"]["merge_states"]
+    baseline = None
+    last_line = None
+    while time.time() < deadline:
+        rec, s = _record(ref)
+        if rec and rec["fetched_at"] >= start - 1:  # only judge data fetched after we started waiting
+            if baseline is None:
+                baseline = s
+            for c in conds:
+                met, impossible = evaluate(c, s, baseline, merge_states)
+                if met:
+                    print(f"{c}: " + one_line(rec["ref"], s, rec.get("failing")))
+                    return EXIT_MET
+                if impossible:
+                    print(f"cannot reach {c}: " + one_line(rec["ref"], s, rec.get("failing")))
+                    return EXIT_IMPOSSIBLE
+            last_line = one_line(rec["ref"], s, rec.get("failing"))
+        if not store.daemon_healthy(max_age=max(300, 3 * store.daemon_state().get("interval", 60))):
+            print("prhub daemon stopped polling while waiting", file=sys.stderr)
+            return EXIT_NO_DAEMON
+        time.sleep(a.poll)
+    print("timeout: " + (last_line or f"{ref}: no fresh data"))
+    return EXIT_TIMEOUT
+
+
+def cmd_watch(a, cfg) -> int:
+    r = resolver(cfg)
+    for p in a.pr:
+        ref = r.resolve(p)
+        store.add_watch(ref)
+        print(f"watching {ref}")
+    store.nudge()
+    return 0
+
+
+def cmd_unwatch(a, cfg) -> int:
+    r = resolver(cfg)
+    w = store.watches()
+    for p in a.pr:
+        w.pop(str(r.resolve(p)), None)
+    store.save_watches(w)
+    return 0
+
+
+def cmd_list(a, cfg) -> int:
+    merge_states = cfg["done"]["merge_states"]
+    rows = []
+    for rec in store.all_prs():
+        s = rec.get("summary") or {}
+        if a.ready and not is_done(s, merge_states):
+            continue
+        if not a.all and s.get("state") != "OPEN":
+            continue
+        rows.append(rec)
+    if a.json:
+        print(json.dumps([{"ref": r["ref"], **r["summary"], "failing": r.get("failing", [])} for r in rows]))
+    else:
+        for r in rows:
+            print(one_line(r["ref"], r["summary"], r.get("failing")) + f"  {r['summary'].get('title', '')[:60]}")
+    return 0
+
+
+def cmd_status(a, cfg) -> int:
+    d = store.daemon_state()
+    healthy = store.daemon_healthy()
+    print(f"prhub {__version__}  home {store.home()}")
+    if not d:
+        print("daemon: never ran")
+        return EXIT_NO_DAEMON
+    age = int(time.time() - d.get("last_poll", 0))
+    rate = d.get("rate") or {}
+    if until := store.rate_limited_until(d):
+        print(f"daemon: PAUSED by the GitHub rate limit until {time.strftime('%H:%M', time.localtime(until))} "
+              f"(pid {d.get('pid')}, alive). `prhub wait` keeps waiting and resumes by itself. Do not poll GitHub "
+              f"by hand meanwhile: your calls hit the same exhausted limit.")
+    print(f"daemon: {'healthy' if healthy else 'NOT polling'} pid {d.get('pid')}  last poll {age}s ago  "
+          f"interval {d.get('interval')}s  tracked {d.get('tracked')}  "
+          f"github budget {rate.get('remaining', '?')} left (reset {rate.get('resetAt', '?')})")
+    if d.get("last_error"):
+        print(f"last error: {d['last_error']}")
+    print(f"watches: {len(store.watches())}  PR files: {len(store.all_prs())}  "
+          f"commits watched: {len(store.commit_watches())}")
+    return 0 if healthy else EXIT_NO_DAEMON
+
+
+def cmd_daemon(a, cfg) -> int:
+    from .daemon import Daemon
+    Daemon().run(once=a.once)
+    return 0
+
+
+# --- Claude Code PreToolUse hook: send agents to `prhub wait` instead of their own GitHub polling loops ---
+
+# A command word starts the line or follows ; & | ( { or a shell keyword, so quoted mentions
+# (a grep pattern, a heredoc of notes) do not count. An `rtk` / `rtk proxy` wrapper is seen through.
+CMD = r"(?:^|[;&|({]|\b(?:then|do|while|until|if|xargs|time)\b|!)\s*(?:rtk\s+(?:proxy\s+)?)?"
+# A loop only polls if it sleeps: `sleep` must be a command, so `time.sleep(…)` in a python -c, a `for`
+# inside a script string or a file called watch.json do not count.
+LOOP = re.compile(r"(?:^|[;&|({]|\bdo\b)\s*(while|until|for)\b[\s\S]*" + CMD + r"sleep\b|"
+                  + CMD + r"watch\s+-n\b", re.M)
+GH_READ = re.compile(CMD + r"gh\s+(pr\s+(checks|view|status|list)|run\s+(view|list)|api)\b", re.M)
+GH_WATCH = re.compile(CMD + r"(gh\s+(pr\s+checks\b[^\n|;&]*--watch|run\s+watch)\b|"
+                      r"watch\b[^\n|;&]*\bgh\s+(pr|run|api)\b)", re.M)
+
+
+def hook_verdict(command: str) -> str | None:
+    """A reason to refuse `command`, or None to let it run."""
+    if "PRHUB_ALLOW=1" in command:
+        return None
+    if GH_WATCH.search(command) or (LOOP.search(command) and GH_READ.search(command)):
+        return ("Don't poll GitHub in a loop: every agent shares one rate limit. prhub already watches PRs "
+                "for you, at no API cost per agent:\n"
+                "  prhub wait <pr> --until done|green|checks|merged|review|change [--timeout 3600]\n"
+                "  prhub wait <owner/repo@sha> --until checks|green|deployed [--env production] [--workflow NAME]\n"
+                "  prhub state <pr>      (current state, instant)\n"
+                "  prhub list --ready    (your PRs ready to merge)\n"
+                "<pr> can be a URL, owner/repo#N, a nickname like 'backend #2814', or a number in this repo. "
+                "Run it in the background (or ScheduleWakeup) if you need to keep working. "
+                "One-off reads like `gh pr view` without a loop are fine.")
+    return None
+
+
+def cmd_hook(a, cfg) -> int:
+    try:
+        data = json.load(sys.stdin)
+    except ValueError:
+        return 0
+    if data.get("tool_name") != "Bash" or not store.daemon_healthy():  # fail open if prhub isn't running
+        return 0
+    reason = hook_verdict((data.get("tool_input") or {}).get("command") or "")
+    if reason:
+        print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",
+                                                 "permissionDecision": "deny",
+                                                 "permissionDecisionReason": reason}}))
+    return 0
+
+
+PLIST = """<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.prhub.daemon</string>
+  <key>ProgramArguments</key><array><string>{exe}</string><string>daemon</string></array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>ProcessType</key><string>Background</string>
+  <key>EnvironmentVariables</key><dict><key>PATH</key><string>{path}</string></dict>
+  <key>StandardOutPath</key><string>{log}</string>
+  <key>StandardErrorPath</key><string>{log}</string>
+</dict></plist>
+"""
+
+UNIT = """[Unit]
+Description=prhub: one GitHub poller for many coding agents
+After=network-online.target
+
+[Service]
+ExecStart={exe} daemon
+Restart=always
+RestartSec=30
+Environment=PATH={path}
+Nice=10
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _service_path(exe: str) -> str:
+    """PATH for the service: wherever `gh` and prhub live, then the usual system directories."""
+    dirs = [os.path.dirname(shutil.which("gh") or ""), os.path.dirname(exe),
+            "/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]
+    return ":".join(dict.fromkeys(d for d in dirs if d))
+
+
+def _exe() -> str:
+    return shutil.which("prhub") or os.path.abspath(sys.argv[0])
+
+
+def cmd_install_launchd(a, cfg) -> int:
+    exe = _exe()
+    plist = os.path.expanduser("~/Library/LaunchAgents/dev.prhub.daemon.plist")
+    log = str(store.home() / "daemon.log")
+    os.makedirs(os.path.dirname(plist), exist_ok=True)
+    with open(plist, "w") as f:
+        f.write(PLIST.format(exe=exe, path=_service_path(exe), log=log))
+    uid = os.getuid()
+    subprocess.run(["launchctl", "bootout", f"gui/{uid}/dev.prhub.daemon"], capture_output=True)
+    r = subprocess.run(["launchctl", "bootstrap", f"gui/{uid}", plist], capture_output=True, text=True)
+    print(f"installed {plist} (log {log})" if r.returncode == 0 else f"launchctl: {r.stderr.strip()}")
+    return r.returncode
+
+
+def cmd_install_systemd(a, cfg) -> int:
+    exe = _exe()
+    unit = os.path.expanduser("~/.config/systemd/user/prhub.service")
+    os.makedirs(os.path.dirname(unit), exist_ok=True)
+    with open(unit, "w") as f:
+        f.write(UNIT.format(exe=exe, path=_service_path(exe)))
+    for cmd in (["systemctl", "--user", "daemon-reload"], ["systemctl", "--user", "enable", "--now", "prhub.service"]):
+        r = subprocess.run(cmd, capture_output=True, text=True)
+        if r.returncode:
+            print(f"{' '.join(cmd)}: {r.stderr.strip()}", file=sys.stderr)
+            return r.returncode
+    print(f"installed {unit}; logs: journalctl --user -u prhub. To keep it running while you are logged out: "
+          "loginctl enable-linger $USER")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="prhub", description="One GitHub poller for many coding agents.")
+    p.add_argument("--version", action="version", version=f"prhub {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    target = "a PR (URL, owner/repo#N, 'nick #N', N) or a commit (owner/repo@sha, 'nick@sha', @sha, commit URL)"
+
+    s = sub.add_parser("state", help="current state of a PR or commit (local, instant)")
+    s.add_argument("pr", help=target)
+    s.add_argument("--json", action="store_true")
+    s.add_argument("--fresh", action="store_true", help="ask the daemon for a poll first (<= 90 s)")
+    s.add_argument("--workflow", help="commits: only runs/statuses whose name contains this")
+
+    w = sub.add_parser("wait", help="block until a PR or commit reaches a condition")
+    w.add_argument("pr", help=target)
+    w.add_argument("--until", required=True, help="PR: " + ", ".join(CONDITIONS) + "; commit: "
+                   + ", ".join(commits.CONDITIONS) + " (comma = any)")
+    w.add_argument("--env", default="production", help="commits, deployed: environment name, or 'any'")
+    w.add_argument("--workflow", help="commits, checks/green: only runs/statuses whose name contains this")
+    w.add_argument("--timeout", type=int, default=3600, help="seconds (default 3600)")
+    w.add_argument("--poll", type=float, default=3.0, help="seconds between local reads (default 3)")
+
+    sw = sub.add_parser("watch", help="track PRs the discovery search does not find")
+    sw.add_argument("pr", nargs="+")
+    su = sub.add_parser("unwatch", help="stop tracking PRs")
+    su.add_argument("pr", nargs="+")
+
+    sl = sub.add_parser("list", help="tracked PRs")
+    sl.add_argument("--ready", action="store_true", help="only PRs that meet `done`")
+    sl.add_argument("--all", action="store_true", help="include merged/closed")
+    sl.add_argument("--json", action="store_true")
+
+    sub.add_parser("status", help="daemon health and GitHub budget")
+    sd = sub.add_parser("daemon", help="run the poller (usually under launchd or systemd)")
+    sd.add_argument("--once", action="store_true", help="poll once and exit")
+    sh = sub.add_parser("hook", help="agent hook that refuses GitHub polling loops")
+    sh.add_argument("agent", choices=["claude"])
+    sub.add_parser("install-launchd", help="run the daemon at login (macOS)")
+    sub.add_parser("install-systemd", help="run the daemon as a systemd user service (Linux)")
+    return p
+
+
+HANDLERS = {"state": cmd_state, "wait": cmd_wait, "watch": cmd_watch, "unwatch": cmd_unwatch, "list": cmd_list,
+            "status": cmd_status, "daemon": cmd_daemon, "hook": cmd_hook,
+            "install-launchd": cmd_install_launchd, "install-systemd": cmd_install_systemd}
+
+
+def main(argv: list[str] | None = None) -> int:
+    a = build_parser().parse_args(argv)
+    cfg = store.load_config()
+    try:
+        return HANDLERS[a.cmd](a, cfg)
+    except ValueError as e:
+        print(f"prhub: {e}", file=sys.stderr)
+        return 2

prhub/commits.py

@@ -0,0 +1,207 @@
+"""Watch one commit's CI and deployments, in any repo: `owner/repo@sha`.
+
+Generic on purpose. Workflow names, default branches (main, develop…) and deploy styles differ per repo, so:
+- CI is every check suite that actually ran something on the commit, minus cron runs (a scheduled workflow attaches
+  to whatever the branch head is, so it says nothing about this commit) and minus apps that never start a run
+  (cursor, classroom, cloudflare… leave a suite QUEUED forever with zero runs).
+- "deployed to <env>" comes from GitHub Deployments, which both deploy-on-merge and nightly-release repos record,
+  plus commit statuses named like `deployed/<env>`. A deploy of a LATER commit counts when that commit contains this
+  one (the daemon asks GitHub's compare API once per new deployment), because a cancelled or batched deploy means
+  your own commit may never be deployed by itself.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+
+from .refs import RefResolver, remote_of
+
+URL_RE = re.compile(r"github\.com/([\w.-]+)/([\w.-]+)/commit/([0-9a-fA-F]{7,40})")
+FULL_RE = re.compile(r"^([\w.-]+)/([\w.-]+)@([0-9a-fA-F]{7,40})$")
+NICK_RE = re.compile(r"^([\w .-]+?)\s*@\s*([0-9a-fA-F]{7,40})$")
+HERE_RE = re.compile(r"^@([0-9a-fA-F]{7,40})$")
+
+OK = {"SUCCESS", "SKIPPED", "NEUTRAL"}
+CONDITIONS = ("checks", "green", "deployed", "change")
+
+
+@dataclass(frozen=True, order=True)
+class CommitRef:
+    owner: str
+    repo: str
+    sha: str  # as given (may be abbreviated); records also carry the full oid
+
+    def __str__(self) -> str:
+        return f"{self.owner}/{self.repo}@{self.sha}"
+
+    @property
+    def slug(self) -> str:
+        return f"{self.owner}__{self.repo}__{self.sha}"
+
+
+def is_commit_text(text: str) -> bool:
+    t = text.strip()
+    return bool(URL_RE.search(t) or FULL_RE.match(t) or NICK_RE.match(t) or HERE_RE.match(t))
+
+
+def resolve(text: str, resolver: RefResolver | None = None, cwd: str | None = None) -> CommitRef:
+    t = text.strip()
+    if m := URL_RE.search(t):
+        return CommitRef(m.group(1), m.group(2), m.group(3).lower())
+    if m := FULL_RE.match(t):
+        return CommitRef(m.group(1), m.group(2), m.group(3).lower())
+    if m := HERE_RE.match(t):
+        r = remote_of(cwd or os.getcwd())
+        if not r:
+            raise ValueError(f"'{t}' names a commit in this checkout, but the current directory is not a GitHub clone")
+        return CommitRef(r[0], r[1], m.group(1).lower())
+    if m := NICK_RE.match(t):
+        repo = (resolver or RefResolver())._repo_for(m.group(1))
+        if repo:
+            owner, name = repo.split("/", 1)
+            return CommitRef(owner, name, m.group(2).lower())
+        raise ValueError(f"unknown repo nickname '{m.group(1)}': add it to [aliases] in the prhub config")
+    raise ValueError(f"cannot read '{t}' as a commit (try owner/repo@sha or a commit URL)")
+
+
+COMMIT_FIELDS = """
+  object(expression: %s) { ... on Commit { oid committedDate
+    status { contexts { context state targetUrl } }
+    checkSuites(first: 50) { nodes { app { slug } status conclusion checkRuns(first: 0) { totalCount }
+      workflowRun { event url workflow { name } } } } } }
+  deployments(last: 30) { nodes { commitOid environment createdAt latestStatus { state } } }
+"""
+
+
+def alias_query(refs: list[CommitRef]) -> str:
+    parts = [f"c{i}: repository(owner: {json.dumps(r.owner)}, name: {json.dumps(r.repo)}) {{"
+             + COMMIT_FIELDS % json.dumps(r.sha) + "}" for i, r in enumerate(refs)]
+    return "query { rateLimit { cost remaining resetAt }\n" + "\n".join(parts) + "\n}"
+
+
+def summarize(repo_node: dict) -> dict | None:
+    """Flatten one aliased repository node. None when the commit does not exist (typo, or not pushed yet)."""
+    obj = (repo_node or {}).get("object") or {}
+    if not obj.get("oid"):
+        return None
+    oid = obj["oid"]
+    runs = []
+    for s in ((obj.get("checkSuites") or {}).get("nodes") or []):
+        if not s or not ((s.get("checkRuns") or {}).get("totalCount") or 0):
+            continue  # an app that never started a run on this commit
+        wr = s.get("workflowRun") or {}
+        if wr.get("event") == "schedule":
+            continue  # cron runs land on the branch head; they are not about this commit
+        runs.append({"name": ((wr.get("workflow") or {}).get("name")) or (s.get("app") or {}).get("slug") or "?",
+                     "event": wr.get("event"), "status": s.get("status"), "conclusion": s.get("conclusion"),
+                     "url": wr.get("url")})
+    statuses = [{"name": c.get("context"), "state": c.get("state"), "url": c.get("targetUrl")}
+                for c in (((obj.get("status") or {}).get("contexts")) or []) if c]
+    envs: dict[str, dict] = {}
+    for d in ((repo_node.get("deployments") or {}).get("nodes") or []):  # oldest first
+        if not d:
+            continue
+        st = (d.get("latestStatus") or {}).get("state") or "PENDING"
+        e = envs.setdefault(d.get("environment") or "?", {"this": None, "last_success": None})
+        if d.get("commitOid") == oid:
+            e["this"] = st
+        if st == "SUCCESS":
+            e["last_success"] = {"sha": d.get("commitOid"), "at": d.get("createdAt")}
+    return {"oid": oid, "committed": obj.get("committedDate"), "runs": runs, "statuses": statuses, "envs": envs}
+
+
+def needs_containment(s: dict) -> list[tuple[str, str]]:
+    """(env, deployed sha) pairs where a successful deploy of ANOTHER commit happened after this one was made,
+    so whether it contains this commit has to be asked."""
+    out = []
+    for env, e in (s.get("envs") or {}).items():
+        ls = e.get("last_success")
+        if ls and ls["sha"] != s["oid"] and (ls.get("at") or "") >= (s.get("committed") or ""):
+            out.append((env, ls["sha"]))
+    return out
+
+
+def rollup(s: dict, workflow: str | None = None) -> tuple[str | None, list[str]]:
+    """(PENDING | SUCCESS | FAILURE | None when nothing ran yet, names of failed runs/statuses). `workflow` keeps only
+    runs and statuses whose name contains it (case-insensitive)."""
+    w = (workflow or "").lower()
+    runs = [r for r in s["runs"] if w in (r["name"] or "").lower()]
+    statuses = [x for x in s["statuses"] if w in (x["name"] or "").lower()]
+    if not runs and not statuses:
+        return None, []
+    # A run CANCELLED because a newer run of the same workflow replaced it (re-run, concurrency group) is not a
+    # failure when a sibling of that name passed; with no passing sibling it still is.
+    passed = {r["name"] for r in runs if r["status"] == "COMPLETED" and (r["conclusion"] or "") in OK}
+    failed = ([r["name"] for r in runs if r["status"] == "COMPLETED" and (r["conclusion"] or "") not in OK
+               and not (r["conclusion"] == "CANCELLED" and r["name"] in passed)]
+              + [x["name"] for x in statuses if x["state"] in ("FAILURE", "ERROR")])
+    pending = (any(r["status"] != "COMPLETED" for r in runs)
+               or any(x["state"] in ("PENDING", "EXPECTED") for x in statuses))
+    return ("PENDING" if pending else "FAILURE" if failed else "SUCCESS"), failed
+
+
+def deploy_state(s: dict, env: str) -> tuple[bool, str | None]:
+    """(live in `env`, failure text or None). `env` "any" accepts every environment."""
+    names = [n for n in (s.get("envs") or {}) if env == "any" or n.lower() == env.lower()]
+    failure = None
+    for n in names:
+        e = s["envs"][n]
+        if e.get("this") == "SUCCESS" or e.get("live"):
+            return True, None
+        if e.get("this") in ("FAILURE", "ERROR"):
+            failure = f"the {n} deployment of this commit {e['this']}"
+    for x in s.get("statuses") or []:  # e.g. a `deployed/production` commit status
+        name = (x["name"] or "").lower()
+        if "deploy" in name and (env == "any" or env.lower() in name):
+            if x["state"] == "SUCCESS":
+                return True, None
+            if x["state"] in ("FAILURE", "ERROR"):
+                failure = f"status {x['name']}={x['state']}"
+    return False, failure
+
+
+def fingerprint(s: dict) -> tuple:
+    return (tuple((r["name"], r["status"], r["conclusion"]) for r in s["runs"]),
+            tuple((x["name"], x["state"]) for x in s["statuses"]),
+            tuple(sorted((k, v.get("this"), bool(v.get("live")), (v.get("last_success") or {}).get("sha"))
+                         for k, v in (s.get("envs") or {}).items())))
+
+
+def evaluate(cond: str, s: dict, baseline: dict | None, env: str = "production",
+             workflow: str | None = None) -> tuple[bool, str | None]:
+    """(met, reason it can no longer be met or None)."""
+    if cond == "change":
+        return baseline is not None and fingerprint(s) != fingerprint(baseline), None
+    state, failed = rollup(s, workflow)
+    if cond == "checks":
+        return state in ("SUCCESS", "FAILURE"), None
+    if cond == "green":
+        return state == "SUCCESS", (f"failed: {', '.join(failed)}" if state == "FAILURE" else None)
+    if cond == "deployed":
+        live, failure = deploy_state(s, env)
+        return live, (None if live else failure)
+    raise ValueError(f"unknown condition '{cond}' for a commit (use: {', '.join(CONDITIONS)})")
+
+
+def one_line(ref: str, s: dict, workflow: str | None = None) -> str:
+    state, failed = rollup(s, workflow)
+    bits = [f"{ref} ({s['oid'][:10]})", f"checks={state or 'none yet'}"]
+    shown = [r for r in s["runs"] if (workflow or "").lower() in (r["name"] or "").lower()]
+    if shown:
+        bits.append("runs: " + ", ".join(f"{r['name']}={r['conclusion'] or r['status']}" for r in shown[:8])
+                    + (f" (+{len(shown) - 8})" if len(shown) > 8 else ""))
+    if failed:
+        bits.append("failing: " + ", ".join(failed[:6]))
+    deps = []
+    for env, e in sorted((s.get("envs") or {}).items()):
+        if e.get("this") == "SUCCESS" or e.get("live"):
+            via = "" if e.get("this") == "SUCCESS" else f" via {(e.get('last_success') or {}).get('sha', '')[:8]}"
+            deps.append(f"{env}=live{via}")
+        elif e.get("this"):
+            deps.append(f"{env}={e['this']}")
+        elif e.get("live") is False:
+            deps.append(f"{env}=not yet")
+    bits.append("deploys: " + (", ".join(deps) if deps else "none recorded for this commit"))
+    return "  ".join(bits)