pr-rocket 0.1.0__py3-none-any.whl

pr_rocket-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pr_rocket_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pr_rocket_cli/__main__.py,sha256=DdmndlQafjLKFGnWsMIhFkOOGVXt_TvxuZ3cnVPTbhQ,7978
+pr_rocket_cli/auth.py,sha256=M8LahyKFItErFQnfi3iKFF_bF74klB6vGKiRPsNZSkE,5841
+pr_rocket_cli/codex.py,sha256=sCr_a3p0GPvkc-FjMx0IBcmdIv_1U4_xKLROjgyN96A,8502
+pr_rocket_cli/git_changes.py,sha256=OxPed0QEzNXI-hDZlQp6V9_7QmXW4wrkxLvLe6VamFs,6433
+pr_rocket_cli/review.py,sha256=6pPhK3M_nhS-MnJffogUUmr2QToEnoqPLQ_shZof46g,7087
+pr_rocket-0.1.0.dist-info/METADATA,sha256=d8PzxuQ8TZhCfNkIMsvl0Wn3-HHirYqvRlGzxnRaUUc,5171
+pr_rocket-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+pr_rocket-0.1.0.dist-info/entry_points.txt,sha256=6tx2m1snAoZPvkLHGapNEN6ja01l5uRKXtlXdt0CYdQ,58
+pr_rocket-0.1.0.dist-info/RECORD,,

pr_rocket-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pr_rocket-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pr-rocket = pr_rocket_cli.__main__:main

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_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 ""

pr_rocket_cli/codex.py

@@ -0,0 +1,212 @@
+"""``pr-rocket codex``: let PR Rocket review your PRs on your own ChatGPT/Codex subscription.
+
+``connect`` signs you in to ChatGPT in the browser (the Codex CLI's own OAuth
+client, PKCE, callback on ``localhost:1455``) and uploads the resulting tokens
+to PR Rocket. It is a separate sign-in from ``codex login``, so PR Rocket's
+token refreshes never log your local Codex out. ``disconnect`` deletes them
+from PR Rocket; you can also sign the session out from your ChatGPT settings.
+"""
+
+import asyncio
+import base64
+import hashlib
+import json
+import secrets
+import webbrowser
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from pr_rocket_cli.auth import NotSignedInError
+
+CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"  # the public Codex CLI client; its redirect is pinned to this URI
+REDIRECT_URI = "http://localhost:1455/auth/callback"
+AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize"
+TOKEN_URL = "https://auth.openai.com/oauth/token"
+_AUTH_CLAIM = "https://api.openai.com/auth"
+LOGIN_TIMEOUT_S = 300
+
+CONSENT = """\
+PR Rocket will store a ChatGPT sign-in for your account (encrypted) and use it for its
+work on pull requests YOU author (reviews, summaries, titles), on your own ChatGPT/Codex
+plan and its Codex limits. When the plan can't serve a request, PR Rocket's own API
+account does. Run `pr-rocket codex disconnect` at any time to delete it."""
+
+
+class CodexError(RuntimeError):
+    """Connecting failed; the message says why."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class Pkce:
+    verifier: str
+    challenge: str
+    state: str
+
+
+def new_pkce() -> Pkce:
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=")
+    return Pkce(verifier=verifier, challenge=challenge, state=secrets.token_urlsafe(24))
+
+
+def authorization_url(pkce: Pkce) -> str:
+    params = {
+        "response_type": "code",
+        "client_id": CLIENT_ID,
+        "redirect_uri": REDIRECT_URI,
+        "scope": "openid profile email offline_access",
+        "state": pkce.state,
+        "code_challenge": pkce.challenge,
+        "code_challenge_method": "S256",
+        "id_token_add_organizations": "true",
+        "codex_cli_simplified_flow": "true",
+    }
+    return f"{AUTHORIZE_URL}?{urlencode(params)}"
+
+
+def account_id(id_token: str) -> str:
+    """The ChatGPT account id in an id_token's claims (unverified; the server only reads it as a hint)."""
+    parts = id_token.split(".")
+    if len(parts) != 3:
+        return ""
+    try:
+        claims = json.loads(base64.urlsafe_b64decode(parts[1] + "=" * (-len(parts[1]) % 4)))
+    except ValueError:
+        return ""
+    auth = claims.get(_AUTH_CLAIM) if isinstance(claims, dict) else None
+    return str(auth.get("chatgpt_account_id") or "") if isinstance(auth, dict) else ""
+
+
+class CallbackListener:
+    """The OAuth callback on localhost:1455, bound on creation so it is listening before the browser opens."""
+
+    def __init__(self, state: str) -> None:
+        self.result: dict[str, str] = {}
+        result = self.result
+
+        class Callback(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                url = urlparse(self.path)
+                query = {k: v[0] for k, v in parse_qs(url.query).items()}
+                # Only a callback carrying our state counts; anything else (a stale tab, a forged link) is ignored.
+                ours = url.path == "/auth/callback" and query.get("state") == state
+                ok = ours and "code" in query
+                if ok:
+                    result["code"] = query["code"]
+                elif ours:
+                    result["error"] = query.get("error_description") or query.get("error") or "the sign-in was refused"
+                self.send_response(200 if ok else 400)
+                self.send_header("Content-Type", "text/plain; charset=utf-8")
+                self.end_headers()
+                self.wfile.write(b"Signed in. You can close this tab." if ok else b"Sign-in failed; see your terminal.")
+
+            def log_message(self, format: str, *args: object) -> None:
+                return None
+
+        try:
+            self.server = HTTPServer(("127.0.0.1", 1455), Callback)
+        except OSError as exc:
+            raise CodexError(f"port 1455 is busy ({exc}); finish or cancel any other `codex login` first") from exc
+        self.server.timeout = 1
+
+    def wait(self, timeout_s: float = LOGIN_TIMEOUT_S) -> str:
+        """Serve until the callback delivers a code (or an error, or the timeout), then close."""
+        try:
+            for _ in range(int(timeout_s)):
+                if self.result:
+                    break
+                self.server.handle_request()
+        finally:
+            self.server.server_close()
+        if "code" not in self.result:
+            raise CodexError(self.result.get("error", "timed out waiting for the browser sign-in"))
+        return self.result["code"]
+
+
+def wait_for_code(state: str, *, timeout_s: float = LOGIN_TIMEOUT_S) -> str:
+    """Listen on localhost:1455 until the callback delivers a code for `state`."""
+    return CallbackListener(state).wait(timeout_s)
+
+
+async def exchange_code(code: str, pkce: Pkce, *, http: httpx.AsyncClient) -> dict:
+    """Trade the authorization code for {access_token, refresh_token, account_id}."""
+    form = {
+        "grant_type": "authorization_code",
+        "code": code,
+        "code_verifier": pkce.verifier,
+        "redirect_uri": REDIRECT_URI,
+        "client_id": CLIENT_ID,
+    }
+    response = await http.post(TOKEN_URL, data=form)
+    if response.status_code != 200:
+        raise CodexError(f"ChatGPT refused the sign-in ({response.status_code})")
+    data = response.json()
+    tokens = {
+        "access_token": str(data.get("access_token") or ""),
+        "refresh_token": str(data.get("refresh_token") or ""),
+        "account_id": account_id(str(data.get("id_token") or "")),
+    }
+    if not all(tokens.values()):
+        raise CodexError("ChatGPT's answer was missing a token or the account id")
+    return tokens
+
+
+async def _call(http: httpx.AsyncClient, method: str, server: str, key: str, body: dict | None = None) -> dict:
+    response = await http.request(
+        method, f"{server}/api/cli/codex-token", headers={"Authorization": f"Bearer {key}"}, json=body
+    )
+    if response.status_code in (401, 403):
+        raise NotSignedInError(_error(response) or "the server refused your key")
+    if response.status_code != 200:
+        raise CodexError(_error(response) or f"the server answered {response.status_code}")
+    return response.json()
+
+
+def _error(response: httpx.Response) -> str:
+    try:
+        return str(response.json().get("error", ""))
+    except ValueError:
+        return ""
+
+
+async def connect(
+    server: str,
+    key: str,
+    *,
+    http: httpx.AsyncClient,
+    open_browser: Callable[[str], object] = webbrowser.open,
+    get_code: Callable[[Pkce], Awaitable[str]] | None = None,
+) -> dict:
+    """Sign in to ChatGPT, upload the tokens, and return the server's status for them."""
+    pkce = new_pkce()
+    url = authorization_url(pkce)
+    listener = CallbackListener(pkce.state) if get_code is None else None  # listening before the browser redirects
+    print(f"Opening your browser to sign in to ChatGPT. If it doesn't open, visit:\n{url}")
+    open_browser(url)
+    if get_code is not None:
+        code = await get_code(pkce)
+    else:
+        assert listener is not None
+        code = await asyncio.to_thread(listener.wait)
+    tokens = await exchange_code(code, pkce, http=http)
+    return await _call(http, "PUT", server, key, {**tokens, "consent": True})
+
+
+async def status(server: str, key: str, *, http: httpx.AsyncClient) -> dict:
+    return await _call(http, "GET", server, key)
+
+
+async def disconnect(server: str, key: str, *, http: httpx.AsyncClient) -> dict:
+    return await _call(http, "DELETE", server, key)
+
+
+def describe(view: dict) -> str:
+    if not view.get("connected"):
+        return "Not connected: PR Rocket reviews your PRs on its own API account."
+    plan = f" ({view['plan_type']} plan)" if view.get("plan_type") else ""
+    state = "" if view.get("status") == "active" else " Its sign-in stopped working; run `pr-rocket codex connect`."
+    return f"Connected to ChatGPT account {view.get('account_id', '')}{plan}.{state}"

pr_rocket_cli/git_changes.py

@@ -0,0 +1,155 @@
+"""What changed locally: the GitHub repo, the commit the work forked from, and the changed files' contents.
+
+The base is ``git merge-base HEAD origin/<default branch>``: always a pushed
+commit, whatever the local branch looks like (unpushed commits, uncommitted
+edits, behind main). Every file that differs between that commit and the
+working tree is sent whole, including untracked files; the server computes
+the diff itself.
+"""
+
+import errno
+import os
+import re
+import stat
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+MAX_FILE_BYTES = 1_000_000
+MAX_UPLOAD_CHARS = 4_000_000  # the server's limit on all file content in one review
+# github.com as the whole host: at the start, after "//" (https/ssh URLs) or after "user@" (scp-style).
+_GITHUB_REMOTE = re.compile(r"(?:^|//|@)(?:[^/@\s]+@)?github\.com[:/](?P<repo>[^/\s]+/[^/\s]+?)(?:\.git)?/?$")
+
+
+class GitError(RuntimeError):
+    """Not a reviewable checkout; the message says what to fix."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class LocalChange:
+    repo: str
+    base_ref: str
+    base_sha: str
+    files: dict[str, str | None]  # path -> content, None when deleted
+    skipped: dict[str, str] = field(default_factory=dict)  # path -> why it wasn't sent
+
+    def upload(self) -> dict:
+        return {"repo": self.repo, "base_sha": self.base_sha, "files": self.files}
+
+
+def _git(repo_dir: Path, *args: str) -> str:
+    # surrogateescape: -z output carries pathnames as raw bytes, which needn't be UTF-8.
+    result = subprocess.run(
+        ["git", *args], cwd=repo_dir, capture_output=True, text=True, errors="surrogateescape", check=False
+    )
+    if result.returncode != 0:
+        raise GitError(f"git {' '.join(args)}: {result.stderr.strip() or 'failed'}")
+    return result.stdout
+
+
+def github_repo(remote_url: str) -> str:
+    """owner/name from a GitHub remote URL (https, ssh or scp-style)."""
+    match = _GITHUB_REMOTE.search(remote_url.strip())
+    if not match:
+        raise GitError(f"origin ({remote_url.strip()}) is not a GitHub repository")
+    return match.group("repo")
+
+
+def _default_base_ref(repo_dir: Path) -> str:
+    try:
+        return _git(repo_dir, "symbolic-ref", "--short", "refs/remotes/origin/HEAD").strip()
+    except GitError:
+        for candidate in ("origin/main", "origin/master"):
+            try:
+                _git(repo_dir, "rev-parse", "--verify", "--quiet", candidate)
+                return candidate
+            except GitError:
+                continue
+    raise GitError("can't find origin's default branch; pass --base (e.g. origin/main)")
+
+
+def _changed_paths(repo_dir: Path, base_sha: str) -> dict[str, bool]:
+    """path -> still exists, for every path that differs from `base_sha` in the working tree."""
+    raw = _git(repo_dir, "diff", "--name-status", "-z", "--no-renames", base_sha)
+    fields = [f for f in raw.split("\0") if f]
+    changed = {path: status != "D" for status, path in zip(fields[::2], fields[1::2], strict=True)}
+    untracked = _git(repo_dir, "ls-files", "--others", "--exclude-standard", "-z")
+    changed.update({path: True for path in untracked.split("\0") if path})
+    return changed
+
+
+def _read_regular_file(path: Path) -> tuple[bytes | None, str]:
+    """The bytes of `path` if it's a regular file of at most MAX_FILE_BYTES, else (None, why).
+
+    Opened with O_NOFOLLOW and checked on the open descriptor, so a symlink swapped in
+    after a check can't make us read (and upload) a file outside the checkout; O_NONBLOCK
+    keeps a FIFO from blocking the open.
+    """
+    try:
+        fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
+    except OSError as exc:
+        return None, "symlink" if exc.errno == errno.ELOOP else f"unreadable ({exc.strerror or exc})"
+    with os.fdopen(fd, "rb") as handle:
+        info = os.fstat(handle.fileno())
+        if not stat.S_ISREG(info.st_mode):
+            return None, "not a regular file"
+        if info.st_size > MAX_FILE_BYTES:
+            return None, f"over {MAX_FILE_BYTES // 1_000_000} MB"
+        try:
+            data = handle.read(MAX_FILE_BYTES + 1)
+        except OSError as exc:
+            return None, f"unreadable ({exc.strerror or exc})"
+    if len(data) > MAX_FILE_BYTES:
+        return None, f"over {MAX_FILE_BYTES // 1_000_000} MB"
+    return data, ""
+
+
+def _read_text(path: Path) -> tuple[str | None, str]:
+    """(content, "") or (None, why it can't be sent)."""
+    if path.is_symlink():
+        return None, "symlink"
+    if path.is_dir():
+        return None, "submodule"
+    data, why = _read_regular_file(path)
+    if data is None:
+        return None, why
+    if b"\0" in data:
+        return None, "binary"
+    try:
+        return data.decode(), ""
+    except UnicodeDecodeError:
+        return None, "binary"
+
+
+def _has_surrogates(text: str) -> bool:
+    """Whether `text` holds undecodable bytes smuggled in by surrogateescape (they can't be uploaded as JSON)."""
+    return any("\udc80" <= char <= "\udcff" for char in text)
+
+
+def collect_change(repo_dir: Path, *, base_ref: str = "") -> LocalChange:
+    """Everything a review of `repo_dir`'s local changes needs, read from git and the working tree."""
+    root = Path(_git(repo_dir, "rev-parse", "--show-toplevel").strip())
+    repo = github_repo(_git(root, "remote", "get-url", "origin"))
+    base_ref = base_ref or _default_base_ref(root)
+    base_sha = _git(root, "merge-base", "HEAD", base_ref).strip()
+    files: dict[str, str | None] = {}
+    skipped: dict[str, str] = {}
+    for rel_path, exists in sorted(_changed_paths(root, base_sha).items()):
+        if _has_surrogates(rel_path):
+            skipped[rel_path.encode("utf-8", "surrogateescape").decode("utf-8", "replace")] = "non-UTF-8 path"
+            continue
+        if not exists:
+            files[rel_path] = None
+            continue
+        content, why = _read_text(root / rel_path)
+        if content is None:
+            skipped[rel_path] = why
+        else:
+            files[rel_path] = content
+    total = sum(len(content or "") for content in files.values())
+    if total > MAX_UPLOAD_CHARS:
+        raise GitError(
+            f"{len(files)} changed files hold {total:,} characters; the limit is {MAX_UPLOAD_CHARS:,}."
+            " Review a smaller change, or pass --base to compare against something closer."
+        )
+    return LocalChange(repo=repo, base_ref=base_ref, base_sha=base_sha, files=files, skipped=skipped)

pr_rocket_cli/review.py

@@ -0,0 +1,173 @@
+"""Upload a local change to PR Rocket and wait for the review's findings."""
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+
+import httpx
+
+from pr_rocket_cli.auth import NotSignedInError
+from pr_rocket_cli.git_changes import LocalChange
+
+POLL_INTERVAL_S = 3.0
+TIMEOUT_S = 20 * 60
+# How long polls may keep missing the review before it counts as lost. While PR Rocket deploys,
+# the old and new server both answer for a minute or two and only one of them has the review,
+# and the load balancer may briefly answer 502/503 itself.
+LOST_AFTER_S = 60.0
+_TRANSIENT_STATUSES = frozenset({404, 502, 503, 504})
+# How long to wait for a review slot when the server says the caller is at their limit (429 + Retry-After):
+# long enough for a running review to finish, short of the hourly limit, which says to come back much later.
+MAX_SLOT_WAIT_S = 5 * 60
+
+OnStage = Callable[[str], Awaitable[None]]
+
+
+class ReviewError(RuntimeError):
+    """The server refused or failed the review; the message is the server's."""
+
+
+class RepoNotEnabledError(ReviewError):
+    """PR Rocket doesn't review this repo (the App isn't installed there, or its code review is off)."""
+
+
+def _body(response: httpx.Response) -> dict:
+    try:
+        body = response.json()
+    except ValueError:
+        return {}
+    return body if isinstance(body, dict) else {}
+
+
+def _error(response: httpx.Response) -> str:
+    return str(_body(response).get("error") or response.text or f"HTTP {response.status_code}")
+
+
+def _check(response: httpx.Response) -> dict:
+    if response.status_code == 401:
+        raise NotSignedInError(f"{_error(response)}")
+    if response.status_code == 403 and _body(response).get("reason") == "not_enabled":
+        raise RepoNotEnabledError(_error(response))
+    if response.status_code >= 400:
+        raise ReviewError(_error(response))
+    return response.json()
+
+
+async def check_access(repo: str, *, server: str, token: str, http: httpx.AsyncClient) -> None:
+    """Raise before anything is uploaded when the caller may not review `repo`.
+
+    A server from before this check answers 404 (it takes "access" for a review id); the upload then decides.
+    """
+    try:
+        response = await http.get(
+            f"{server}/api/local-review/access", params={"repo": repo}, headers={"Authorization": f"Bearer {token}"}
+        )
+    except httpx.TransportError as exc:
+        raise ReviewError(f"can't reach PR Rocket at {server} ({exc.__class__.__name__}); try again later") from exc
+    if response.status_code != 404:
+        _check(response)
+
+
+async def _poll(http: httpx.AsyncClient, url: str, *, headers: dict[str, str]) -> httpx.Response | None:
+    """The poll's response, or None when it never got one (connection refused or reset, timed out)."""
+    try:
+        return await http.get(url, headers=headers)
+    except httpx.TransportError:
+        return None
+
+
+def _retry_after_s(response: httpx.Response) -> float | None:
+    try:
+        return float(response.headers.get("Retry-After", ""))
+    except ValueError:
+        return None
+
+
+async def _start(
+    change: LocalChange, *, server: str, headers: dict, http: httpx.AsyncClient, on_stage: OnStage | None, sleep
+) -> dict:
+    """Upload the change; at the caller's limit (429), wait as long as the server says when that fits MAX_SLOT_WAIT_S."""
+    waited = 0.0
+    while True:
+        response = await http.post(f"{server}/api/local-review", json=change.upload(), headers=headers)
+        retry_after = _retry_after_s(response) if response.status_code == 429 else None
+        if retry_after is None or waited + retry_after > MAX_SLOT_WAIT_S:
+            return _check(response)
+        if on_stage:
+            await on_stage(f"waiting {retry_after:.0f}s for a review slot ({_error(response)})")
+        await sleep(retry_after)
+        waited += retry_after
+
+
+async def run_review(
+    change: LocalChange,
+    *,
+    server: str,
+    token: str,
+    http: httpx.AsyncClient,
+    on_stage: OnStage | None = None,
+    sleep=asyncio.sleep,
+    clock=time.monotonic,
+) -> dict:
+    """The review result: {status, findings, summary[, reason]}.
+
+    Time spent waiting counts the sleeps between polls and how long each poll took
+    (one that times out can take a minute).
+    """
+    headers = {"Authorization": f"Bearer {token}"}
+    job = await _start(change, server=server, headers=headers, http=http, on_stage=on_stage, sleep=sleep)
+    stage = ""
+    waited = 0.0
+    missing_since: float | None = None
+    while job["status"] not in ("done", "error"):
+        if waited > TIMEOUT_S:
+            raise ReviewError("the review is taking too long; try again later")
+        await sleep(POLL_INTERVAL_S)
+        waited += POLL_INTERVAL_S
+        polled_at, started = waited, clock()
+        response = await _poll(http, f"{server}/api/local-review/{job['id']}", headers=headers)
+        waited += clock() - started
+        if response is None or response.status_code in _TRANSIENT_STATUSES:
+            missing_since = polled_at if missing_since is None else missing_since
+            if waited - missing_since < LOST_AFTER_S:
+                continue
+            if response is not None and response.status_code == 404:
+                raise ReviewError("the server lost the review (it probably restarted); run it again")
+            raise ReviewError("PR Rocket is not answering; run the review again later")
+        missing_since = None
+        job = _check(response)
+        if on_stage and job.get("stage") and job["stage"] != stage:
+            stage = job["stage"]
+            await on_stage(stage)
+    if job["status"] == "error":
+        raise ReviewError(job.get("error") or "the review failed")
+    return job["result"]
+
+
+def format_result(result: dict, change: LocalChange) -> str:
+    """Findings for a terminal: one block per finding, worst first."""
+    lines: list[str] = []
+    if change.skipped:
+        skipped = ", ".join(f"{path} ({why})" for path, why in change.skipped.items())
+        lines += [f"Not reviewed: {skipped}", ""]
+    findings = result.get("findings") or []
+    if not findings:
+        lines.append("No findings.")
+    for finding in findings:
+        lines.append(f"{finding['file']}:{finding['line']}  {finding['severity']} ({finding['category']})")
+        lines.append(f"  {finding['description']}")
+        if finding.get("suggested_fix"):
+            lines.append(f"  Fix: {finding['suggested_fix']}")
+        if finding.get("suggestion"):
+            lines += ["  Suggested code:", *(f"    {code}" for code in finding["suggestion"].splitlines())]
+        lines.append("")
+    if result.get("summary"):
+        lines.append(result["summary"])
+    if files := result.get("unverified_files"):
+        lines += ["", f"Not fully reviewed (the review ran out of budget): {', '.join(files)}"]
+    if unverified := result.get("unverified_findings"):
+        lines += [
+            "",
+            f"Not shown: {unverified} finding(s) the review ran out of budget to verify. Review a smaller change.",
+        ]
+    return "\n".join(lines).rstrip() + "\n"