Add PR/MR review feature with URL resolution, cross-fork support, and TUI integration

Author: locchh

specs/20260329-205124-branch-compare/data-model.md

@@ -28,6 +28,28 @@ The complete result of comparing two remote tracking branches. Passed from `_Git
 | `unique_commits` | `list[CommitInfo]` | Commits in target but not base (reuses existing `CommitInfo` type) |
 | `conflicts` | `list[ConflictFile]` | Conflicting files; empty list = clean merge |
 | `shallow_warning` | `bool` | True if the clone is shallow and results may be incomplete |
+| `full_diff` | `str` | Full `git diff --no-color` output for export |
+| `full_log` | `str` | Full `git log --stat --no-color --date=iso` output for export |
+
+### `PRMetadata`
+
+Metadata resolved from a GitHub PR or GitLab MR URL via the provider REST API.
+
+| Field | Type | Description |
+|-------|------|-----------|
+| `provider` | `str` | `"github"` or `"gitlab"` |
+| `owner` | `str` | Base repo owner |
+| `repo` | `str` | Base repo name |
+| `number` | `int` | PR/MR number |
+| `title` | `str` | PR/MR title |
+| `state` | `str` | `open`, `closed`, or `merged` |
+| `author` | `str` | PR/MR author username |
+| `base` | `str` | Base branch name |
+| `head` | `str` | Head branch name |
+| `url` | `str` | Original PR/MR URL |
+| `head_clone_url` | `str` | Clone URL for the head repo (may be a fork) |
+| `head_owner` | `str` | Owner of the head repo (may differ from base for cross-fork PRs) |
+| `description` | `str` | PR/MR body text |
 
 ## Reused Existing Types
 
@@ -54,4 +76,15 @@ BranchComparison result displayed
     │
     ├─ user presses Export button → .txt written, notification shown
     └─ user presses Escape → screen dismissed, return to main view
+
+For PR/MR flow (TUI):
+
+```
+User enters PR number → _run_pr_resolve()
+    │
+    ▼ API call resolves base + head branch names + metadata
+    ├─ cross-fork: add pr-head remote, fetch branch
+    ▼ base/target inputs auto-filled → _run_comparison() triggered
+    ▼ BranchComparison result displayed with PR title + description header
+```
 ```

specs/20260329-205124-branch-compare/quickstart.md

@@ -1,6 +1,6 @@
 # Quickstart: Branch Comparison View
 
-## Using the Compare Screen
+## TUI — Compare Two Branches
 
 1. Load a repository as normal (`owner/repo` + Load).
 2. Press `c` to open the compare screen.
@@ -10,15 +10,42 @@
 6. The screen fetches remote refs and displays a scrollable result panel:
    - **Diff Summary** — total files/lines changed, per-file breakdown
    - **Commits** — commits in target not in base
-   - **Conflicts** — conflicting files with hunk detail, or "Clean merge"
-7. Press **Export** to save the result to a `.txt` file in your working directory.
+   - **Conflicts** — conflicting files listed, or "Clean merge"
+7. Press **Export** to save a detailed `.txt` report to your working directory.
 8. Press `Escape` to return to the main commit view.
 
+## TUI — Review a PR/MR
+
+1. Load the repository the PR targets.
+2. Press `c` to open the compare screen.
+3. In the **PR/MR number** input, type the PR number (e.g., `123`) — or paste a full URL.
+4. Press Enter or click **Fill branches** — base and target inputs auto-fill from the API.
+5. Comparison runs automatically; PR title and description appear at the top of results.
+6. Press **Export** to save the report (filename includes the PR number).
+
+## CLI — Compare Branches
+
+```bash
+uv run cex owner/repo --compare main feature/foo
+```
+
+Prints a summary to stdout and writes `compare-main-feature-foo-YYYYMMDD.txt`.
+
+## CLI — Review a PR/MR
+
+```bash
+uv run cex --pr https://github.com/owner/repo/pull/123
+```
+
+Resolves base/head from the GitHub/GitLab API, clones, compares, and writes
+`compare-owner-repo-pr123-YYYYMMDD.txt` with a PR metadata header.
+
 ## Notes
 
-- If the repo was loaded with `--depth N`, a shallow-clone warning may appear and some results may be incomplete.
-- Branch names with `/` (e.g., `feature/foo`) are supported — type them as-is without the `origin/` prefix.
-- The compare screen reuses the existing clone; no re-download occurs.
+- Branch names with `/` (e.g., `feature/foo`) are supported — type as-is without `origin/` prefix.
+- Cross-fork PRs are handled: the fork is added as a `pr-head` remote automatically.
+- Export includes full `git diff` patch and `git log --stat` output.
+- Set `GITHUB_TOKEN` / `GITLAB_TOKEN` env vars to avoid API rate limits.
 
 ## Development Setup
 

specs/20260329-205124-branch-compare/tasks.md

@@ -80,7 +80,11 @@
 
 - [X] T016 [P] Add input validation to `CompareScreen` in `app.py` — strip whitespace from branch names; show inline error if either field is empty when Compare is pressed; show `notify()` if `origin/<branch>` ref does not exist after fetch
 - [X] T017 [P] Add shallow-warning banner to `CompareScreen` results rendering in `app.py` — if `BranchComparison.shallow_warning` is True, prepend `"⚠ Shallow clone — commit log and conflict results may be incomplete"` at the top of the results panel
-- [ ] T018 Manual validation per `specs/20260329-205124-branch-compare/quickstart.md` against at least one real repository — confirm all three sections render correctly and export file matches screen content
+- [X] T018 Manual validation per `specs/20260329-205124-branch-compare/quickstart.md` against at least one real repository — confirmed all sections render correctly and export matches screen content
+- [X] T019 Enhanced `_write_export()` to produce detailed report: full `git diff` patch, full `git log --stat`, changed files with +/- counts, PR metadata header when available
+- [X] T020 Added `--compare BASE TARGET` CLI flag to `main()` — clones repo, compares branches, prints summary, writes `.txt` without launching TUI
+- [X] T021 Fixed `filter=blob:none` partial clone: switched to `git diff --name-status` for file list (tree-only), fetch blobs on demand before `--shortstat` and full diff
+- [X] T022 Added PR/MR review: `--pr <URL>` CLI flag + PR number input in TUI; resolves base/head via GitHub/GitLab API; handles cross-fork PRs via `pr-head` remote; export filename encodes PR number; PR title + description shown in TUI and export
 
 ---
 

specs/20260329-233618-pr-review/tasks.md

@@ -0,0 +1,48 @@
+# Tasks: PR/MR Review from URL
+
+**Input**: Design documents from `/specs/20260329-233618-pr-review/`
+**Prerequisites**: spec.md ✓
+
+**Structure**: All code lives in `app.py` (single-file architecture per constitution).
+
+---
+
+## Phase 1: Core Types & URL Resolution
+
+- [X] T001 Add `PRMetadata` NamedTuple to Types section of `app.py` — fields: `provider`, `owner`, `repo`, `number`, `title`, `state`, `author`, `base`, `head`, `url`, `head_clone_url`, `head_owner`, `description`
+- [X] T002 Implement `_resolve_pr_url(url) -> PRMetadata` in `app.py` — parses GitHub PR URLs (`github.com/.../pull/N`) and GitLab MR URLs (`gitlab.com/.../merge_requests/N`); calls provider REST API to fetch base/head branch names, title, state, author, description; raises `ValueError` for unsupported URL formats
+
+---
+
+## Phase 2: CLI `--pr` Flag
+
+- [X] T003 Implement `_add_fork_remote(tmpdir, fork_url, branch)` helper in `app.py` — adds `pr-head` remote pointing at the fork and fetches the given branch with `--filter=blob:none`
+- [X] T004 Implement `_pr_review(url, provider_key, depth)` async function in `app.py` — resolves PR metadata, clones base repo, adds fork remote for cross-fork PRs, calls `compare_branches(base, head_ref)`, writes export via `_write_export(result, pr_meta=pr)`, prints summary to stdout
+- [X] T005 Add `--pr URL` argument to `main()` argparse in `app.py` — takes priority over `--compare`; `owner/repo` positional arg optional (inferred from URL)
+- [X] T006 Update `_write_export()` to accept optional `pr_meta` — when present: use `compare-{owner}-{repo}-pr{N}-{YYYYMMDD}.txt` filename; prepend PR metadata header (URL, title, author, state, description) before diff sections
+
+---
+
+## Phase 3: TUI Integration
+
+- [X] T007 Pass `owner`, `repo`, `provider` to `CompareScreen.__init__()` from `action_compare()` in `CommitExplorer`
+- [X] T008 Add PR/MR number input row to `CompareScreen.compose()` — `Input` with placeholder "PR/MR number (e.g. 123)" + "Fill branches" `Button`; placed above existing branch inputs
+- [X] T009 Implement `_build_pr_url(number)` method on `CompareScreen` — constructs full GitHub/GitLab URL from loaded repo context; raises `ValueError` if repo not loaded or provider unsupported
+- [X] T010 Implement `_run_pr_resolve()` `@work` method on `CompareScreen` — resolves PR URL, adds fork remote if cross-fork, auto-fills base/target inputs, triggers `_run_comparison()`; stores `pr_meta` in `self._last_pr`
+- [X] T011 Update `_render_comparison()` to show PR header when `self._last_pr` is set — display title, author, state, and up to 20 lines of description (truncated with "… see export" notice)
+- [X] T012 Update `on_export_pressed()` to pass `pr_meta=self._last_pr` to `_write_export()` so export filename includes PR number
+
+---
+
+## Phase 4: Cross-Fork PR Support
+
+- [X] T013 Detect cross-fork PRs in `_pr_review()` — compare `pr.head_owner` vs `pr.owner`; if different, call `_add_fork_remote()` and set `head_ref = "pr-head/<branch>"`
+- [X] T014 Detect cross-fork PRs in `CompareScreen._run_pr_resolve()` — same logic; set target input to `pr-head/<branch>` so `_run_comparison()` uses the correct ref
+- [X] T015 Update `compare_branches()` ref resolution — handle pre-qualified refs (`pr-head/...`) without adding `origin/` prefix; update blob fetch to use correct remote per ref
+
+---
+
+## Validation
+
+- [X] T016 CLI: tested with `cex --pr https://github.com/anthropics/claude-code/pull/40594` (cross-fork PR) — 7 files changed, correct diff and commit log in export
+- [X] T017 TUI: tested with PR number input `40586` on `anthropics/claude-code` — base/target auto-filled, comparison runs, PR title shown in results