zithub 0.1.0__tar.gz → 0.3.0__tar.gz

zithub-0.3.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: zithub
+Version: 0.3.0
+Summary: What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more
+Keywords: git,github,cli,pull-request,ci,gh
+Author: Ville Vainio
+Author-email: Ville Vainio <vivainio@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/vivainio/zithub
+Project-URL: Repository, https://github.com/vivainio/zithub
+Project-URL: Issues, https://github.com/vivainio/zithub/issues
+Description-Content-Type: text/markdown
+
+# zithub
+
+`zh` — what's up with this repo, right now, plus batched `gh` PR and release
+actions for AI agents. A standalone `gh`/`git` CLI: bare `zh` gives repo,
+branch, local, PR, and CI status in one shot (no separate status tool
+required), and the rest covers what plain `gh` can't already do in a single
+call — acting on PR review-comment threads (no `gh` subcommand exists for
+these at all), merging with a real preflight
+(draft/review-decision/unresolved-threads/CI, checked and merged in one
+call instead of chained separately), and release preflight/creation. The
+status/CI/PR/my/review/issues reporting is ported from
+[wazup](https://github.com/vivainio/wazup), so `zh` doesn't need wazup
+installed alongside it. It deliberately does *not* wrap `gh pr
+create/close/comment/review/edit`, since those are already one `gh` call
+each and an agent that already knows `gh` gains nothing from a second name
+for the same thing.
+
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) installed and
+authenticated (`gh auth login`).
+
+## Commands
+
+```
+zh                # prints help (bare zh does nothing)
+zh status         # repo, branch, local, PR, and CI status in one shot
+                  # (also recent branches/worktrees on the default branch)
+zh ci             # just the CI status for the current branch/PR
+zh pr             # current branch's PR: status, checks, and review comment
+                  # threads (unresolved by default; --all also shows resolved)
+zh my             # your open PRs across all repos, plus recent closed/merged
+zh my --this      # ...just for the current repo
+zh stats          # most active repos by recent PR+issue activity (--owner, --days, --limit)
+zh review         # PRs awaiting your review, updated in the last 7 days
+zh issues         # your open issues in this repo, or recent activity outside one
+zh gh <args...>   # gh <args...> as this repo owner's gh account (GH_TOKEN; no global switch)
+zh git <args...>  # git <args...>; over https, as this repo owner's gh account (same)
+
+zh board sync             # fetch your open PRs + activity (CI, review, comments) into a local sqlite db
+                          # (incremental: only new/updated PRs or unsettled CI; --full refetches all)
+zh board                  # list synced PRs per repo (biggest first), oldest activity first (--stale-days N)
+zh board focus            # grouped: fix CI, needs your reply, ready to merge, waiting on others
+                          # (each grouped per repo; bot comments never count as "needs your reply")
+zh board bots [add|rm X]  # extra logins treated as bots on this host, e.g. a CI service account
+zh board query "<SQL>"    # ad hoc read-only SQL against the synced db
+                          # (one board per GitHub site: $GH_HOST, else origin's host, else github.com)
+
+zh pr threads    # list review-comment threads (with the ids below)
+zh pr reply      # reply to a review-comment thread, optionally --resolve
+zh pr resolve    # mark thread(s) resolved, by id or --all
+zh pr unresolve  # reopen thread(s)
+
+zh plan          # draft reply/resolve/merge actions into ONE reviewable file
+                 # (context as comments, all actions commented out): zh plan > plan.md
+zh plan --apply plan.md [--dry-run]   # validate everything, then run it in order
+
+zh pr check      # target branch, and whether the PR references a ticket
+
+zh pr merge      # merge a PR
+zh pr ship       # merge + delete branch (same as `merge --delete-branch`)
+
+zh release                    # preflight, then commits + the gh command for each next version
+zh release patch/minor/major  # preflight, then just that one bumped version + gh command
+zh release create             # preflight, then actually create at an explicit version
+
+zh repos           # local checkouts zh has seen, most-recently-seen first
+zh install-skills  # install the zh Claude Code skill
+```
+
+Add `-w`/`--why` to `zh`, `zh ci`, or `zh pr` to drill into a failing check
+— prints the tail of the failing job's log, right up to the error, instead
+of just a pass/fail icon.
+
+`threads`/`reply`/`resolve`/`unresolve` exist because `gh` has no
+subcommand for review threads at all — they go through `gh api graphql`
+directly (`reviewThreads`, `resolveReviewThread`, `unresolveReviewThread`,
+`addPullRequestReviewThreadReply`). Run `zh pr threads` to see each
+thread's id, then act on it:
+
+```
+zh pr threads                       # unresolved threads on the current branch's PR
+zh pr reply T_kwDOA... -b "fixed in a1b2c3d" --resolve
+zh pr resolve --all --path src/     # resolve every unresolved thread under src/
+```
+
+`zh pr check` surfaces what you'd otherwise have to open the PR on the web
+(or find a local clone) to see: the base branch it's targeting (no
+judgment — just shown, since only you know whether it's the wrong one),
+its local checkout if `zh repos` has seen one for that branch — warning if
+that checkout is dirty, since switching branches or pulling there would be
+risky — and whether the title/body references a ticket at all: a GitHub
+issue ref (`#123`, `Fixes #123`), any URL (covers a Jira/Linear/etc. link),
+or a bare Jira-style key (`ABC-123`, flagged with a suggestion to link it
+directly). Exits non-zero if no ticket reference is found.
+
+Typically called with one or more PR URLs directly (an owner/repo parsed
+right out of the URL, so it works from anywhere — not just a checkout of
+that repo), rather than a bare number, which only resolves against the
+current directory's repo:
+
+```
+zh pr check                                          # current branch's PR
+zh pr check https://github.com/acme/widgets/pull/42
+zh pr check https://github.com/.../pull/42 https://github.com/.../pull/43   # a summary block per PR
+```
+
+`zh pr merge` (and `zh pr ship`, which is the same thing with
+`--delete-branch` on by default) bundles what would otherwise be a
+draft/review-decision/unresolved-thread/CI check spread across several
+calls into one preflight, then merges only if everything's clean:
+
+```
+zh pr merge                 # preflight, waiting on any pending checks, then squash-merge
+zh pr ship                  # same, plus delete the branch afterward
+zh pr merge --no-wait        # fail fast instead of polling pending checks
+zh pr merge --force          # skip the preflight and merge immediately
+zh pr merge --method rebase --keep-branch
+```
+
+`zh release` (bare, or `patch`/`minor`/`major`) checks: the active gh
+account matches the repo's owner (same convention `wazup` uses — a
+logged-in account whose login, or the org half of a `name_OrgName`
+corporate-SSO login, matches origin's owner; best-effort and never blocks
+the release if nothing matches), the current branch matches the release
+target, local HEAD matches `origin/<target>` exactly, and CI is green on
+that exact commit (falling back to the branch's latest runs if no run
+exists yet for the commit, and proceeding on judgement if none exist at
+all). A dirty worktree only warns — it isn't part of the release either
+way, since the tag points at HEAD.
+
+Past the preflight it's read-only: it never creates anything itself. It
+shows the commit log a release's notes get written from, and prints the
+exact `zh release create ...` command to run once notes are ready. That
+command skips its own preflight by default, so running it right after
+`zh release` doesn't redo the CI wait that was just run here.
+`patch`/`minor`/`major` fetch the latest release tag and compute one
+specific bump; bare `zh release` shows all three:
+
+```
+zh release                          # -> zh release create <next patch/minor/major> ...
+zh release patch                    # -> just the patch bump
+zh release patch --target release-2.0
+```
+
+`zh release create` is the one command that actually publishes — it
+requires release notes (`-n`/`--notes` or `-F`/`--notes-file` — one of
+them, always), and after creating the GitHub release it also polls for and
+waits on any workflow run(s) triggered by that release (e.g. a PyPI
+publish job), reporting success or failure instead of leaving that for the
+caller to check separately. A repo with no such workflow just proceeds —
+it's not treated as a failure. The preflight is opt-in via `--preflight`,
+for when you're calling it directly without a prior `zh release`:
+
+```
+zh release create v1.3.0 -n "$(cat notes.md)"
+zh release create v2.0.0-rc1 --prerelease --preflight   # check first, since there was no prior `zh release`
+```
+
+Every command above that needs `gh` also registers the checkout it ran in
+— path, repo, branch — into a local registry at
+`~/.local/share/zithub/repos.jsonl`, ported from wazup's own (a separate
+database, same design). `zh repos` lists what's been seen, letting an
+agent find a local checkout of a repo by name instead of guessing paths or
+re-cloning; two worktrees or clones of the same repo, at different paths,
+show up as separate entries with their own branch:
+
+```
+zh repos          # everything seen, most-recently-seen first
+zh repos zithub   # only checkouts whose repo name or path contains "zithub"
+```
+
+## Install
+
+```
+uv tool install zithub
+```
+
+## License
+
+MIT

zithub-0.3.0/README.md

@@ -0,0 +1,179 @@
+# zithub
+
+`zh` — what's up with this repo, right now, plus batched `gh` PR and release
+actions for AI agents. A standalone `gh`/`git` CLI: bare `zh` gives repo,
+branch, local, PR, and CI status in one shot (no separate status tool
+required), and the rest covers what plain `gh` can't already do in a single
+call — acting on PR review-comment threads (no `gh` subcommand exists for
+these at all), merging with a real preflight
+(draft/review-decision/unresolved-threads/CI, checked and merged in one
+call instead of chained separately), and release preflight/creation. The
+status/CI/PR/my/review/issues reporting is ported from
+[wazup](https://github.com/vivainio/wazup), so `zh` doesn't need wazup
+installed alongside it. It deliberately does *not* wrap `gh pr
+create/close/comment/review/edit`, since those are already one `gh` call
+each and an agent that already knows `gh` gains nothing from a second name
+for the same thing.
+
+Requires the [GitHub CLI](https://cli.github.com/) (`gh`) installed and
+authenticated (`gh auth login`).
+
+## Commands
+
+```
+zh                # prints help (bare zh does nothing)
+zh status         # repo, branch, local, PR, and CI status in one shot
+                  # (also recent branches/worktrees on the default branch)
+zh ci             # just the CI status for the current branch/PR
+zh pr             # current branch's PR: status, checks, and review comment
+                  # threads (unresolved by default; --all also shows resolved)
+zh my             # your open PRs across all repos, plus recent closed/merged
+zh my --this      # ...just for the current repo
+zh stats          # most active repos by recent PR+issue activity (--owner, --days, --limit)
+zh review         # PRs awaiting your review, updated in the last 7 days
+zh issues         # your open issues in this repo, or recent activity outside one
+zh gh <args...>   # gh <args...> as this repo owner's gh account (GH_TOKEN; no global switch)
+zh git <args...>  # git <args...>; over https, as this repo owner's gh account (same)
+
+zh board sync             # fetch your open PRs + activity (CI, review, comments) into a local sqlite db
+                          # (incremental: only new/updated PRs or unsettled CI; --full refetches all)
+zh board                  # list synced PRs per repo (biggest first), oldest activity first (--stale-days N)
+zh board focus            # grouped: fix CI, needs your reply, ready to merge, waiting on others
+                          # (each grouped per repo; bot comments never count as "needs your reply")
+zh board bots [add|rm X]  # extra logins treated as bots on this host, e.g. a CI service account
+zh board query "<SQL>"    # ad hoc read-only SQL against the synced db
+                          # (one board per GitHub site: $GH_HOST, else origin's host, else github.com)
+
+zh pr threads    # list review-comment threads (with the ids below)
+zh pr reply      # reply to a review-comment thread, optionally --resolve
+zh pr resolve    # mark thread(s) resolved, by id or --all
+zh pr unresolve  # reopen thread(s)
+
+zh plan          # draft reply/resolve/merge actions into ONE reviewable file
+                 # (context as comments, all actions commented out): zh plan > plan.md
+zh plan --apply plan.md [--dry-run]   # validate everything, then run it in order
+
+zh pr check      # target branch, and whether the PR references a ticket
+
+zh pr merge      # merge a PR
+zh pr ship       # merge + delete branch (same as `merge --delete-branch`)
+
+zh release                    # preflight, then commits + the gh command for each next version
+zh release patch/minor/major  # preflight, then just that one bumped version + gh command
+zh release create             # preflight, then actually create at an explicit version
+
+zh repos           # local checkouts zh has seen, most-recently-seen first
+zh install-skills  # install the zh Claude Code skill
+```
+
+Add `-w`/`--why` to `zh`, `zh ci`, or `zh pr` to drill into a failing check
+— prints the tail of the failing job's log, right up to the error, instead
+of just a pass/fail icon.
+
+`threads`/`reply`/`resolve`/`unresolve` exist because `gh` has no
+subcommand for review threads at all — they go through `gh api graphql`
+directly (`reviewThreads`, `resolveReviewThread`, `unresolveReviewThread`,
+`addPullRequestReviewThreadReply`). Run `zh pr threads` to see each
+thread's id, then act on it:
+
+```
+zh pr threads                       # unresolved threads on the current branch's PR
+zh pr reply T_kwDOA... -b "fixed in a1b2c3d" --resolve
+zh pr resolve --all --path src/     # resolve every unresolved thread under src/
+```
+
+`zh pr check` surfaces what you'd otherwise have to open the PR on the web
+(or find a local clone) to see: the base branch it's targeting (no
+judgment — just shown, since only you know whether it's the wrong one),
+its local checkout if `zh repos` has seen one for that branch — warning if
+that checkout is dirty, since switching branches or pulling there would be
+risky — and whether the title/body references a ticket at all: a GitHub
+issue ref (`#123`, `Fixes #123`), any URL (covers a Jira/Linear/etc. link),
+or a bare Jira-style key (`ABC-123`, flagged with a suggestion to link it
+directly). Exits non-zero if no ticket reference is found.
+
+Typically called with one or more PR URLs directly (an owner/repo parsed
+right out of the URL, so it works from anywhere — not just a checkout of
+that repo), rather than a bare number, which only resolves against the
+current directory's repo:
+
+```
+zh pr check                                          # current branch's PR
+zh pr check https://github.com/acme/widgets/pull/42
+zh pr check https://github.com/.../pull/42 https://github.com/.../pull/43   # a summary block per PR
+```
+
+`zh pr merge` (and `zh pr ship`, which is the same thing with
+`--delete-branch` on by default) bundles what would otherwise be a
+draft/review-decision/unresolved-thread/CI check spread across several
+calls into one preflight, then merges only if everything's clean:
+
+```
+zh pr merge                 # preflight, waiting on any pending checks, then squash-merge
+zh pr ship                  # same, plus delete the branch afterward
+zh pr merge --no-wait        # fail fast instead of polling pending checks
+zh pr merge --force          # skip the preflight and merge immediately
+zh pr merge --method rebase --keep-branch
+```
+
+`zh release` (bare, or `patch`/`minor`/`major`) checks: the active gh
+account matches the repo's owner (same convention `wazup` uses — a
+logged-in account whose login, or the org half of a `name_OrgName`
+corporate-SSO login, matches origin's owner; best-effort and never blocks
+the release if nothing matches), the current branch matches the release
+target, local HEAD matches `origin/<target>` exactly, and CI is green on
+that exact commit (falling back to the branch's latest runs if no run
+exists yet for the commit, and proceeding on judgement if none exist at
+all). A dirty worktree only warns — it isn't part of the release either
+way, since the tag points at HEAD.
+
+Past the preflight it's read-only: it never creates anything itself. It
+shows the commit log a release's notes get written from, and prints the
+exact `zh release create ...` command to run once notes are ready. That
+command skips its own preflight by default, so running it right after
+`zh release` doesn't redo the CI wait that was just run here.
+`patch`/`minor`/`major` fetch the latest release tag and compute one
+specific bump; bare `zh release` shows all three:
+
+```
+zh release                          # -> zh release create <next patch/minor/major> ...
+zh release patch                    # -> just the patch bump
+zh release patch --target release-2.0
+```
+
+`zh release create` is the one command that actually publishes — it
+requires release notes (`-n`/`--notes` or `-F`/`--notes-file` — one of
+them, always), and after creating the GitHub release it also polls for and
+waits on any workflow run(s) triggered by that release (e.g. a PyPI
+publish job), reporting success or failure instead of leaving that for the
+caller to check separately. A repo with no such workflow just proceeds —
+it's not treated as a failure. The preflight is opt-in via `--preflight`,
+for when you're calling it directly without a prior `zh release`:
+
+```
+zh release create v1.3.0 -n "$(cat notes.md)"
+zh release create v2.0.0-rc1 --prerelease --preflight   # check first, since there was no prior `zh release`
+```
+
+Every command above that needs `gh` also registers the checkout it ran in
+— path, repo, branch — into a local registry at
+`~/.local/share/zithub/repos.jsonl`, ported from wazup's own (a separate
+database, same design). `zh repos` lists what's been seen, letting an
+agent find a local checkout of a repo by name instead of guessing paths or
+re-cloning; two worktrees or clones of the same repo, at different paths,
+show up as separate entries with their own branch:
+
+```
+zh repos          # everything seen, most-recently-seen first
+zh repos zithub   # only checkouts whose repo name or path contains "zithub"
+```
+
+## Install
+
+```
+uv tool install zithub
+```
+
+## License
+
+MIT

{zithub-0.1.0 → zithub-0.3.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "zithub"
-version = "0.1.0"
-description = "Batched gh CLI actions for PR workflows: merge preflight, review-thread reply/resolve, and more in one call"
+version = "0.3.0"
+description = "What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -52,3 +52,7 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true

{zithub-0.1.0 → zithub-0.3.0}/pyproject.toml.orig

@@ -1,7 +1,7 @@
 [project]
 name = "zithub"
-version = "0.1.0"
-description = "Batched gh CLI actions for PR workflows: merge preflight, review-thread reply/resolve, and more in one call"
+version = "0.3.0"
+description = "What's up with this repo, right now, plus batched gh PR/release actions: status, CI, merge preflight, review-thread reply/resolve, and more"
 readme = "README.md"
 authors = [
     { name = "Ville Vainio", email = "vivainio@gmail.com" }
@@ -44,3 +44,7 @@ dev = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+default = true

zithub-0.3.0/src/zithub/board.py

@@ -0,0 +1,241 @@
+"""Local sqlite cache of your open PRs, synced from GitHub by `zh board
+sync` and read by `zh board` / `zh board query`.
+
+A cache rather than a live view: `gh` round trips (one `gh pr view` per
+open PR) are too slow to do on every `zh board` invocation, so sync is a
+separate, explicit step, and stagnation ("no activity in N days") is
+computed against whatever was last synced, not against live data.
+
+Kept as an actual sqlite file (not zithub's usual JSONL registry format)
+specifically so it can be queried directly — `zh board query "<SQL>"`,
+or any other sqlite client pointed at the file — rather than only through
+whatever views this module thinks to expose.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+from dataclasses import dataclass
+
+from . import gh
+
+
+class BoardError(Exception):
+    """Raised for bad input to this module (e.g. a non-SELECT query)."""
+
+
+def _data_dir() -> str:
+    base = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return os.path.join(base, "zithub")
+
+
+def db_path(host: str) -> str:
+    """One db per GitHub site (github.com, a GHES host, ...), since "your
+    open PRs" — and which login is "you" — differ per site."""
+    return os.path.join(_data_dir(), "boards", f"{host}.sqlite")
+
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS prs (
+    repo TEXT NOT NULL,
+    number INTEGER NOT NULL,
+    title TEXT NOT NULL,
+    url TEXT NOT NULL,
+    is_draft INTEGER NOT NULL,
+    review_decision TEXT NOT NULL,
+    ci_state TEXT NOT NULL,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    comment_count INTEGER NOT NULL,
+    last_comment_at TEXT,
+    last_comment_author TEXT,
+    last_activity_at TEXT NOT NULL,
+    synced_at TEXT NOT NULL,
+    PRIMARY KEY (repo, number)
+);
+CREATE TABLE IF NOT EXISTS meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS bots (
+    login TEXT PRIMARY KEY
+);
+"""
+
+
+# Bump when what a synced row *means* changes (not just its columns), so
+# rows cached under the old meaning get dropped and refetched by the next
+# (otherwise incremental) sync. 1: last_comment_* skip bot comments and
+# titles are HTML-unescaped.
+_CACHE_VERSION = 1
+
+
+def _connect(host: str) -> sqlite3.Connection:
+    path = db_path(host)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    conn = sqlite3.connect(path)
+    conn.row_factory = sqlite3.Row
+    conn.executescript(_SCHEMA)
+    if conn.execute("PRAGMA user_version").fetchone()[0] < _CACHE_VERSION:
+        with conn:
+            conn.execute("DELETE FROM prs")
+            conn.execute(f"PRAGMA user_version = {_CACHE_VERSION}")
+    return conn
+
+
+def sync(
+    host: str, prs: list[gh.BoardPr], synced_at: str, login: str | None = None
+) -> None:
+    """Replace the table's contents with exactly `prs` — the scope is
+    "your currently-open PRs", so a PR merged/closed since the last sync
+    should simply disappear rather than linger as a stale row."""
+    prune(host, {(p.repo, p.number) for p in prs})
+    upsert(host, prs, synced_at)
+    if login:
+        set_login(host, login)
+
+
+def cached_versions(host: str) -> dict[tuple[str, int], tuple[str, str]]:
+    """(repo, number) -> (updated_at, ci_state) for every cached PR — what
+    `zh board sync` compares against to skip PRs that haven't changed."""
+    with _connect(host) as conn:
+        return {
+            (r["repo"], r["number"]): (r["updated_at"], r["ci_state"])
+            for r in conn.execute("SELECT repo, number, updated_at, ci_state FROM prs")
+        }
+
+
+def prune(host: str, keep: set[tuple[str, int]]) -> None:
+    """Drop every cached PR not in `keep` (i.e. merged/closed since the
+    last sync)."""
+    with _connect(host) as conn:
+        stale = [
+            (r["repo"], r["number"])
+            for r in conn.execute("SELECT repo, number FROM prs")
+            if (r["repo"], r["number"]) not in keep
+        ]
+        conn.executemany("DELETE FROM prs WHERE repo = ? AND number = ?", stale)
+
+
+def upsert(host: str, prs: list[gh.BoardPr], synced_at: str) -> None:
+    """Insert or refresh `prs` — committed per call, so a sync that fails
+    partway keeps every batch it already fetched."""
+    rows = [
+        (
+            p.repo,
+            p.number,
+            p.title,
+            p.url,
+            int(p.is_draft),
+            p.review_decision,
+            p.ci_state,
+            p.created_at,
+            p.updated_at,
+            p.comment_count,
+            p.last_comment_at,
+            p.last_comment_author,
+            max(p.updated_at, p.last_comment_at or ""),
+            synced_at,
+        )
+        for p in prs
+    ]
+    with _connect(host) as conn:
+        conn.executemany("INSERT OR REPLACE INTO prs VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?)", rows)
+
+
+def set_login(host: str, login: str) -> None:
+    """Stash your active gh login so `zh board focus` can tell "you last
+    commented" from "someone else did" without its own gh call."""
+    with _connect(host) as conn:
+        conn.execute(
+            "INSERT INTO meta VALUES ('login', ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+            (login,),
+        )
+
+
+def get_login(host: str) -> str | None:
+    with _connect(host) as conn:
+        row = conn.execute("SELECT value FROM meta WHERE key = 'login'").fetchone()
+        return row["value"] if row else None
+
+
+def bot_logins(host: str) -> set[str]:
+    """Logins (lowercase) `zh board sync` treats as bots on this host, on
+    top of gh's built-in list — org machine users like a CI account."""
+    with _connect(host) as conn:
+        return {r["login"] for r in conn.execute("SELECT login FROM bots")}
+
+
+def add_bots(host: str, logins: list[str]) -> None:
+    with _connect(host) as conn:
+        conn.executemany("INSERT OR IGNORE INTO bots VALUES (?)", [(login.lower(),) for login in logins])
+        _mark_all_for_refetch(conn)
+
+
+def remove_bots(host: str, logins: list[str]) -> None:
+    with _connect(host) as conn:
+        conn.executemany("DELETE FROM bots WHERE login = ?", [(login.lower(),) for login in logins])
+        _mark_all_for_refetch(conn)
+
+
+def _mark_all_for_refetch(conn: sqlite3.Connection) -> None:
+    """Each row's last-comment fields were picked with the old bot list, so
+    blank the updated_at that cached_versions() hands to sync — every row
+    then looks changed and gets refetched, while still showing meanwhile."""
+    conn.execute("UPDATE prs SET updated_at = ''")
+
+
+@dataclass
+class BoardRow:
+    repo: str
+    number: int
+    title: str
+    url: str
+    is_draft: bool
+    review_decision: str
+    ci_state: str
+    last_activity_at: str
+    comment_count: int
+    last_comment_author: str | None
+
+
+def list_board(host: str) -> list[BoardRow]:
+    """Every synced PR, oldest activity first — so a stagnated PR sorts to
+    the top without needing a separate "stale" query."""
+    with _connect(host) as conn:
+        cur = conn.execute(
+            "SELECT repo, number, title, url, is_draft, review_decision, ci_state, "
+            "last_activity_at, comment_count, last_comment_author "
+            "FROM prs ORDER BY last_activity_at ASC"
+        )
+        return [
+            BoardRow(
+                repo=r["repo"],
+                number=r["number"],
+                title=r["title"],
+                url=r["url"],
+                is_draft=bool(r["is_draft"]),
+                review_decision=r["review_decision"],
+                ci_state=r["ci_state"],
+                last_activity_at=r["last_activity_at"],
+                comment_count=r["comment_count"],
+                last_comment_author=r["last_comment_author"],
+            )
+            for r in cur.fetchall()
+        ]
+
+
+def run_query(host: str, sql: str) -> tuple[list[str], list[tuple]]:
+    """Runs a read-only `SELECT`/`WITH` query against the board db and
+    returns (column names, rows). Anything else (INSERT/UPDATE/DELETE/etc,
+    including via a stacked statement) is rejected — this is meant for ad
+    hoc lookups against the synced snapshot, not for editing it."""
+    stripped = sql.strip()
+    if not stripped or not stripped.lstrip().upper().startswith(("SELECT", "WITH")):
+        raise BoardError("only SELECT/WITH queries are allowed")
+    with _connect(host) as conn:
+        conn.execute("PRAGMA query_only = ON")
+        cur = conn.execute(stripped)
+        columns = [d[0] for d in cur.description] if cur.description else []
+        return columns, cur.fetchall()