pr-rocket 0.1.0__tar.gz

pr_rocket-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/
+
+# Build artifacts
+node_modules/
+
+# Frontend build output (vite emits into public/ with emptyOutDir=true;
+# CI rebuilds on deploy via `just fe-build`). Anchored to repo root — an
+# unanchored `public/` also matches frontend/src/apps/public/, which broke
+# Cloud Build's source upload (gcloud reuses .gitignore for gcloudignore).
+/public/
+
+# Secrets
+.env
+.dev.vars
+*.pem
+admin-auth.json
+deploy/k8s/secret.yaml
+
+# Native runtime local state (git checkout cache)
+data/
+
+# uv (lock file is tracked — don't ignore it)
+
+# Testing
+.pytest_cache/
+.hypothesis/
+.coverage
+htmlcov/
+frontend/test-results/
+frontend/playwright/.cache/
+playwright-report/
+*.trace
+*.har
+*.webm
+
+# IDE / tools
+.cache/
+.ruff_cache/
+.mypy_cache/
+.claude/worktrees/
+.playwright-cli/
+.playwright/
+.codex/
+.serena/
+
+# Misc
+error.log
+*.png
+PR Rocket.zip
+.vite/

pr_rocket-0.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: pr-rocket
+Version: 0.1.0
+Summary: Review local changes with PR Rocket before opening a pull request
+Project-URL: Homepage, https://pr-rocket.pydantic.dev
+Author: Pydantic Services Inc.
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28
+Description-Content-Type: text/markdown
+
+# pr-rocket CLI
+
+Get PR Rocket's code review of your local changes before you open a pull request.
+
+```
+uv tool install 'git+https://github.com/pydantic/pr-rocket#subdirectory=cli'
+pr-rocket login     # approve the sign-in in your browser
+pr-rocket review
+```
+
+`review` sends every file that differs from where your branch forked from
+`origin`'s default branch (`git merge-base HEAD origin/<default>`): unpushed
+commits, staged, unstaged and untracked files. That base is always a pushed
+commit, so it works from any local branch. Use `--base REF` to review against
+something else. The review takes a few minutes. Findings are printed worst first,
+and the command exits 1 when there are any. Nothing is posted to GitHub.
+
+Binary files, symlinks, submodules and files over 1 MB are not sent, and one
+review uploads at most 4,000,000 characters in total.
+
+`pr-rocket review [PATH]` reviews the checkout containing `PATH` (default `.`).
+Exit codes: 0 no findings, 1 findings, 2 an error or nothing reviewable (every
+changed file was skipped), 3 PR Rocket doesn't review this repo (it isn't
+installed there, or the repo's code review is off). The CLI asks the server
+about the repo first, so in that case nothing is uploaded. `pr-rocket logout`
+forgets the saved key.
+
+## Coding agents
+
+Agents can run the CLI in a shell. `--json` prints the result as JSON:
+
+```
+pr-rocket review --json
+```
+
+Run `pr-rocket login` once in a terminal, or give the agent's environment `PR_ROCKET_TOKEN`.
+An agent can also run `pr-rocket login --no-browser` and hand you the link it prints to approve.
+An agent that gets exit code 3 should skip the review: the repo isn't one PR Rocket reviews.
+
+## Access
+
+`pr-rocket login` signs in through your browser. It prints a code such as
+`BCDF-GHJK` and opens Ground Control's sign-in page, which shows the same code and
+this machine's name. Approve it there (signing in with GitHub first if you need
+to), and the CLI collects a new key, named after the machine, that lasts 90 days.
+The code expires after 10 minutes. On a machine without a browser (over SSH, in a
+container), open the printed link on any device instead; `--no-browser` only prints it.
+
+The key is saved in `$XDG_CONFIG_HOME/pr-rocket/credentials.json` (default
+`~/.config`, mode 0600). `PR_ROCKET_TOKEN` overrides the saved key, for CI and
+agents. You can see and revoke keys in Ground Control under **CLI keys** at any time.
+
+You can also make a key by hand in Ground Control under **CLI keys** (choosing
+30 days, 90 days or a year) and pipe it in (`echo prk_... | pr-rocket login`), or
+paste it with `pr-rocket login --paste`.
+
+A key acts as you. To review a repo you need three things:
+- approved Ground Control access;
+- GitHub read access to the repo;
+- PR Rocket installed on the repo, with **Code review** on in its Ground Control settings.
+
+Each person can have two reviews running at a time, and 50 per hour.
+
+Set `PR_ROCKET_URL` (or pass `--server`, before the subcommand: `pr-rocket --server URL review`) to use another PR Rocket instance.
+
+## Your own Codex plan
+
+```
+pr-rocket codex connect      # sign in to ChatGPT in the browser, then upload the sign-in
+pr-rocket codex status
+pr-rocket codex disconnect   # delete it from PR Rocket
+```
+
+`connect` lets PR Rocket do its work on the pull requests you author (reviews,
+summaries, titles), and the `pr-rocket review` runs you start, on your own
+ChatGPT/Codex plan instead of its API account.
+A request your plan can't serve (its usage limit, a model it doesn't offer, a
+sign-in that stopped working) goes to the API account instead, and a usage
+limit pauses your plan for 15 minutes. It's a separate ChatGPT sign-in from `codex
+login` (same browser flow, callback on `localhost:1455`), so it never logs your
+local Codex out. PR Rocket stores the tokens encrypted, and `disconnect`
+deletes them. It asks for your consent first; `--yes` skips the prompt.
+
+Run `pr-rocket login` first: the CLI key says whose PRs the plan is for. Approve
+the ChatGPT sign-in in a browser on the same machine, since it calls back to that
+machine's `localhost:1455`; `connect` gives up after 5 minutes without it.
+
+## Development
+
+`just cli-check` from the repo root formats, lints, type-checks and tests this package.
+
+## Releasing
+
+The CLI is published to PyPI as `pr-rocket` by `.github/workflows/publish-cli.yml`, with
+PyPI trusted publishing (no stored token). Bump `version` in `cli/pyproject.toml`, merge,
+then tag that commit on main: `git tag cli-v<version> && git push origin cli-v<version>`.
+The workflow checks the tag matches the version, runs the tests, builds and publishes.

pr_rocket-0.1.0/README.md

@@ -0,0 +1,97 @@
+# pr-rocket CLI
+
+Get PR Rocket's code review of your local changes before you open a pull request.
+
+```
+uv tool install 'git+https://github.com/pydantic/pr-rocket#subdirectory=cli'
+pr-rocket login     # approve the sign-in in your browser
+pr-rocket review
+```
+
+`review` sends every file that differs from where your branch forked from
+`origin`'s default branch (`git merge-base HEAD origin/<default>`): unpushed
+commits, staged, unstaged and untracked files. That base is always a pushed
+commit, so it works from any local branch. Use `--base REF` to review against
+something else. The review takes a few minutes. Findings are printed worst first,
+and the command exits 1 when there are any. Nothing is posted to GitHub.
+
+Binary files, symlinks, submodules and files over 1 MB are not sent, and one
+review uploads at most 4,000,000 characters in total.
+
+`pr-rocket review [PATH]` reviews the checkout containing `PATH` (default `.`).
+Exit codes: 0 no findings, 1 findings, 2 an error or nothing reviewable (every
+changed file was skipped), 3 PR Rocket doesn't review this repo (it isn't
+installed there, or the repo's code review is off). The CLI asks the server
+about the repo first, so in that case nothing is uploaded. `pr-rocket logout`
+forgets the saved key.
+
+## Coding agents
+
+Agents can run the CLI in a shell. `--json` prints the result as JSON:
+
+```
+pr-rocket review --json
+```
+
+Run `pr-rocket login` once in a terminal, or give the agent's environment `PR_ROCKET_TOKEN`.
+An agent can also run `pr-rocket login --no-browser` and hand you the link it prints to approve.
+An agent that gets exit code 3 should skip the review: the repo isn't one PR Rocket reviews.
+
+## Access
+
+`pr-rocket login` signs in through your browser. It prints a code such as
+`BCDF-GHJK` and opens Ground Control's sign-in page, which shows the same code and
+this machine's name. Approve it there (signing in with GitHub first if you need
+to), and the CLI collects a new key, named after the machine, that lasts 90 days.
+The code expires after 10 minutes. On a machine without a browser (over SSH, in a
+container), open the printed link on any device instead; `--no-browser` only prints it.
+
+The key is saved in `$XDG_CONFIG_HOME/pr-rocket/credentials.json` (default
+`~/.config`, mode 0600). `PR_ROCKET_TOKEN` overrides the saved key, for CI and
+agents. You can see and revoke keys in Ground Control under **CLI keys** at any time.
+
+You can also make a key by hand in Ground Control under **CLI keys** (choosing
+30 days, 90 days or a year) and pipe it in (`echo prk_... | pr-rocket login`), or
+paste it with `pr-rocket login --paste`.
+
+A key acts as you. To review a repo you need three things:
+- approved Ground Control access;
+- GitHub read access to the repo;
+- PR Rocket installed on the repo, with **Code review** on in its Ground Control settings.
+
+Each person can have two reviews running at a time, and 50 per hour.
+
+Set `PR_ROCKET_URL` (or pass `--server`, before the subcommand: `pr-rocket --server URL review`) to use another PR Rocket instance.
+
+## Your own Codex plan
+
+```
+pr-rocket codex connect      # sign in to ChatGPT in the browser, then upload the sign-in
+pr-rocket codex status
+pr-rocket codex disconnect   # delete it from PR Rocket
+```
+
+`connect` lets PR Rocket do its work on the pull requests you author (reviews,
+summaries, titles), and the `pr-rocket review` runs you start, on your own
+ChatGPT/Codex plan instead of its API account.
+A request your plan can't serve (its usage limit, a model it doesn't offer, a
+sign-in that stopped working) goes to the API account instead, and a usage
+limit pauses your plan for 15 minutes. It's a separate ChatGPT sign-in from `codex
+login` (same browser flow, callback on `localhost:1455`), so it never logs your
+local Codex out. PR Rocket stores the tokens encrypted, and `disconnect`
+deletes them. It asks for your consent first; `--yes` skips the prompt.
+
+Run `pr-rocket login` first: the CLI key says whose PRs the plan is for. Approve
+the ChatGPT sign-in in a browser on the same machine, since it calls back to that
+machine's `localhost:1455`; `connect` gives up after 5 minutes without it.
+
+## Development
+
+`just cli-check` from the repo root formats, lints, type-checks and tests this package.
+
+## Releasing
+
+The CLI is published to PyPI as `pr-rocket` by `.github/workflows/publish-cli.yml`, with
+PyPI trusted publishing (no stored token). Bump `version` in `cli/pyproject.toml`, merge,
+then tag that commit on main: `git tag cli-v<version> && git push origin cli-v<version>`.
+The workflow checks the tag matches the version, runs the tests, builds and publishes.

pr_rocket-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+# The PyPI name, so `uvx pr-rocket ...` runs the `pr-rocket` script below. The server
+# (repo root) is never published.
+name = "pr-rocket"
+version = "0.1.0"
+description = "Review local changes with PR Rocket before opening a pull request"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Pydantic Services Inc." }]
+classifiers = [
+    "Environment :: Console",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "httpx>=0.28",
+]
+
+[project.urls]
+Homepage = "https://pr-rocket.pydantic.dev"
+
+[project.scripts]
+pr-rocket = "pr_rocket_cli.__main__:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pr_rocket_cli"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120

pr_rocket-0.1.0/src/pr_rocket_cli/__main__.py

@@ -0,0 +1,178 @@
+"""pr-rocket: review local changes with PR Rocket before opening a pull request.
+
+pr-rocket login               sign in through your browser (or pipe in a key from Ground Control)
+pr-rocket review [PATH]       review every local change against where the branch forked
+pr-rocket logout
+pr-rocket codex connect       review your own PRs and changes on your ChatGPT/Codex plan
+pr-rocket codex status | disconnect
+
+`review` exits 0 with no findings, 1 with findings, 2 on an error, and 3 when PR Rocket
+doesn't review the repo (not installed there, or code review is off); nothing is uploaded then.
+"""
+
+import argparse
+import asyncio
+import getpass
+import json
+import os
+import socket
+import sys
+import webbrowser
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+import httpx
+
+from pr_rocket_cli import codex
+from pr_rocket_cli.auth import KeyStore, NotSignedInError, key_for, login, start_browser_login, wait_for_approval
+from pr_rocket_cli.git_changes import GitError, collect_change
+from pr_rocket_cli.review import RepoNotEnabledError, ReviewError, check_access, format_result, run_review
+
+DEFAULT_SERVER = "https://pr-rocket.pydantic.dev"
+# `review` exits 0 (no findings), 1 (findings), 2 (an error) or this: PR Rocket doesn't review the repo.
+EXIT_NOT_ENABLED = 3
+
+
+def _version() -> str:
+    try:
+        return version("pr-rocket")
+    except PackageNotFoundError:  # running from a source tree that was never installed
+        return "unknown"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pr-rocket", description=__doc__, formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_version()}")
+    parser.add_argument("--server", default=os.environ.get("PR_ROCKET_URL", DEFAULT_SERVER), help="PR Rocket URL")
+    commands = parser.add_subparsers(dest="command", required=True)
+    login_cmd = commands.add_parser(
+        "login", help="sign in through your browser; a key piped on stdin is saved instead (for scripts)"
+    )
+    login_cmd.add_argument("--no-browser", action="store_true", help="print the sign-in link instead of opening it")
+    login_cmd.add_argument("--paste", action="store_true", help="paste a key made in Ground Control instead")
+    commands.add_parser("logout", help="forget the saved key")
+    review = commands.add_parser("review", help="review local changes")
+    review.add_argument("path", nargs="?", default=".", help="directory inside the checkout (default: .)")
+    review.add_argument("--base", default="", help="ref the work branched from (default: origin's default branch)")
+    review.add_argument("--json", action="store_true", help="print the raw result as JSON")
+    codex_cmd = commands.add_parser("codex", help="use your own ChatGPT/Codex plan for reviews of your PRs")
+    codex_cmd.add_argument("action", choices=("connect", "status", "disconnect"))
+    codex_cmd.add_argument("--yes", action="store_true", help="agree to the consent prompt without asking")
+    return parser
+
+
+async def _review(args: argparse.Namespace, store: KeyStore) -> int:
+    key = key_for(args.server, store=store)
+    change = collect_change(Path(args.path).expanduser(), base_ref=args.base)
+    if not change.files:
+        if change.skipped:
+            skipped = ", ".join(f"{path} ({why})" for path, why in change.skipped.items())
+            print(f"Nothing reviewable against {change.base_ref}; every changed file was skipped: {skipped}")
+            return 2
+        print(f"No changes against {change.base_ref} ({change.base_sha[:12]}).")
+        return 0
+
+    async def on_stage(stage: str) -> None:
+        print(f"  {stage}…", file=sys.stderr)
+
+    async with httpx.AsyncClient(timeout=60) as http:
+        await check_access(change.repo, server=args.server, token=key, http=http)
+        print(
+            f"Reviewing {len(change.files)} changed file(s) in {change.repo} against {change.base_ref}…",
+            file=sys.stderr,
+        )
+        result = await run_review(change, server=args.server, token=key, http=http, on_stage=on_stage)
+    print(json.dumps(result, indent=2) if args.json else format_result(result, change))
+    return 1 if result.get("findings") else 0
+
+
+def _piped_key() -> str:
+    """A key piped on stdin (`echo prk_... | pr-rocket login`), as before browser sign-in; "" when stdin is a
+    terminal or empty (e.g. /dev/null, as agents' shells give), which means sign in through the browser."""
+    if sys.stdin is None or sys.stdin.isatty():
+        return ""
+    return sys.stdin.readline().strip()
+
+
+def _can_open_browser() -> bool:
+    if os.environ.get("SSH_CONNECTION") or os.environ.get("SSH_TTY"):
+        return False  # the browser would open on the wrong machine, or a text browser would take over the terminal
+    return sys.platform in ("darwin", "win32") or bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+
+
+async def _browser_login(args: argparse.Namespace, store: KeyStore, http: httpx.AsyncClient) -> str:
+    pending = await start_browser_login(args.server, name=socket.gethostname(), http=http)
+    print(
+        f"\nSign in to PR Rocket in your browser and check it shows this code:\n\n    {pending.user_code}\n",
+        file=sys.stderr,
+    )
+    opened = False
+    if not args.no_browser and _can_open_browser():
+        try:
+            opened = webbrowser.open(pending.url)
+        except webbrowser.Error:
+            opened = False
+    print(f"{'If the browser did not open, go to' if opened else 'Open'}:\n    {pending.url}\n", file=sys.stderr)
+    print("Waiting for approval… (Ctrl-C to cancel)", file=sys.stderr)
+    return await wait_for_approval(args.server, pending, http=http, store=store)
+
+
+async def _login(args: argparse.Namespace, store: KeyStore) -> int:
+    key = _piped_key()
+    if args.paste and not key:
+        print(f"Create a key under CLI keys in Ground Control: {args.server}/ground-control", file=sys.stderr)
+        key = getpass.getpass("Paste the key: ")
+    async with httpx.AsyncClient(timeout=60) as http:
+        who = await login(args.server, key, http=http, store=store) if key else await _browser_login(args, store, http)
+    print(f"Signed in as {who}.")
+    return 0
+
+
+async def _codex(args: argparse.Namespace, store: KeyStore) -> int:
+    key = key_for(args.server, store=store)
+    if args.action == "connect":
+        print(codex.CONSENT, file=sys.stderr)
+        if not args.yes and input("Continue? [y/N] ").strip().lower() not in ("y", "yes"):
+            return 1
+    async with httpx.AsyncClient(timeout=60) as http:
+        if args.action == "connect":
+            view = await codex.connect(args.server, key, http=http)
+        elif args.action == "disconnect":
+            view = await codex.disconnect(args.server, key, http=http)
+        else:
+            view = await codex.status(args.server, key, http=http)
+    print(codex.describe(view))
+    return 0
+
+
+def _run(args: argparse.Namespace, store: KeyStore):
+    if args.command == "login":
+        return _login(args, store)
+    return _codex(args, store) if args.command == "codex" else _review(args, store)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    store = KeyStore()
+    if args.command == "logout":
+        store.save(args.server, None)
+        return 0
+    try:
+        return asyncio.run(_run(args, store))
+    except RepoNotEnabledError as exc:
+        print(f"pr-rocket: {exc}. Nothing was reviewed.", file=sys.stderr)
+        return EXIT_NOT_ENABLED
+    except (NotSignedInError, GitError, ReviewError, codex.CodexError) as exc:
+        print(f"pr-rocket: {exc}", file=sys.stderr)
+        return 2
+    except httpx.TransportError as exc:
+        print(f"pr-rocket: couldn't reach {args.server} ({exc})", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pr_rocket-0.1.0/src/pr_rocket_cli/auth.py

@@ -0,0 +1,148 @@
+"""Your PR Rocket CLI key, saved by ``pr-rocket login``.
+
+``pr-rocket login`` signs in through the browser: the server gives a short code, the person
+approves it on Ground Control's sign-in page, and the CLI collects a fresh key (an OAuth 2.0
+device authorization grant). A key made by hand in Ground Control can be pasted or piped instead.
+``PR_ROCKET_TOKEN`` takes precedence over a saved key (for CI and agents).
+Saved keys live in ``~/.config/pr-rocket/credentials.json`` (mode 0600),
+one per server URL.
+"""
+
+import asyncio
+import json
+import os
+from collections.abc import Awaitable, Callable, Mapping
+from pathlib import Path
+
+import httpx
+
+TOKEN_ENV = "PR_ROCKET_TOKEN"
+
+
+class NotSignedInError(RuntimeError):
+    """No usable key; the message says what to do."""
+
+
+def credentials_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "pr-rocket" / "credentials.json"
+
+
+class KeyStore:
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = path or credentials_path()
+
+    def _all(self) -> dict:
+        try:
+            return json.loads(self.path.read_text())
+        except (FileNotFoundError, ValueError):
+            return {}
+
+    def load(self, server: str) -> str | None:
+        entry = self._all().get(server)
+        return str(entry["key"]) if isinstance(entry, dict) and entry.get("key") else None
+
+    def save(self, server: str, key: str | None) -> None:
+        entries = self._all()
+        if key is None:
+            entries.pop(server, None)
+        else:
+            entries[server] = {"key": key}
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as handle:
+            json.dump(entries, handle, indent=2)
+
+
+def key_for(server: str, *, store: KeyStore, environ: Mapping[str, str] = os.environ) -> str:
+    key = environ.get(TOKEN_ENV) or store.load(server)
+    if not key:
+        raise NotSignedInError("not signed in: run `pr-rocket login` (or set PR_ROCKET_TOKEN)")
+    return key
+
+
+async def check_key(server: str, key: str, *, http: httpx.AsyncClient) -> str:
+    """The GitHub login `key` belongs to; raises NotSignedInError when the server refuses it."""
+    response = await http.get(f"{server}/api/local-review/me", headers={"Authorization": f"Bearer {key}"})
+    if response.status_code in (401, 403):
+        try:
+            reason = response.json().get("error", "")
+        except ValueError:
+            reason = ""
+        raise NotSignedInError(reason or "the server refused that key")
+    response.raise_for_status()
+    return str(response.json().get("login", ""))
+
+
+async def login(server: str, key: str, *, http: httpx.AsyncClient, store: KeyStore) -> str:
+    """Check `key` with the server, save it, and return who it belongs to."""
+    key = key.strip()
+    if not key.startswith("prk_"):
+        raise NotSignedInError("that isn't a PR Rocket key (they start with prk_)")
+    who = await check_key(server, key, http=http)
+    store.save(server, key)
+    return who
+
+
+class BrowserLogin:
+    """A sign-in started with the server, waiting for the person to approve it in a browser."""
+
+    def __init__(self, started: dict) -> None:
+        self.device_code = str(started["device_code"])
+        self.user_code = str(started["user_code"])
+        self.url = str(started.get("verification_uri_complete") or started["verification_uri"])
+        self.expires_in = int(started.get("expires_in", 600))
+        self.interval = max(1, int(started.get("interval", 3)))
+
+
+async def start_browser_login(server: str, *, name: str, http: httpx.AsyncClient) -> BrowserLogin:
+    """Ask the server for a sign-in code for this machine."""
+    response = await http.post(f"{server}/api/cli/login", json={"name": name})
+    if response.status_code != 200:
+        raise NotSignedInError(_error_of(response) or f"the server couldn't start a sign-in ({response.status_code})")
+    return BrowserLogin(response.json())
+
+
+async def wait_for_approval(
+    server: str,
+    pending: BrowserLogin,
+    *,
+    http: httpx.AsyncClient,
+    store: KeyStore,
+    sleep: Callable[[float], Awaitable[object]] = asyncio.sleep,
+) -> str:
+    """Poll until the sign-in is approved, then check and save the new key; returns who it belongs to."""
+    waited = 0.0
+    while waited < pending.expires_in:
+        await sleep(pending.interval)
+        waited += pending.interval
+        response = await http.post(f"{server}/api/cli/login/token", json={"device_code": pending.device_code})
+        if response.status_code != 200:
+            raise NotSignedInError(_error_of(response) or f"sign-in failed ({response.status_code})")
+        status = response.json().get("status")
+        if status == "approved":
+            return await _save_new_key(server, str(response.json()["key"]), http=http, store=store)
+        if status == "denied":
+            raise NotSignedInError("the sign-in was denied in the browser")
+        if status == "expired":
+            break
+    raise NotSignedInError("the sign-in expired before it was approved; run `pr-rocket login` again")
+
+
+async def _save_new_key(server: str, key: str, *, http: httpx.AsyncClient, store: KeyStore) -> str:
+    """Save a key the server just minted before anything else can fail: it is handed out only once."""
+    store.save(server, key)
+    try:
+        return await check_key(server, key, http=http)
+    except NotSignedInError:
+        store.save(server, None)
+        raise
+    except httpx.HTTPError:
+        return "your account (the key is saved; the server didn't answer who it belongs to)"
+
+
+def _error_of(response: httpx.Response) -> str:
+    try:
+        return str(response.json().get("error", ""))
+    except ValueError:
+        return ""