feat(PRO-545): review a GitHub PR by URL or number

[dastratakos]

Summary

Lets you point the CLI at a GitHub PR — --pr <number-or-url> on both stagereview prep and show — and review it instead of only your local branch diff. The base/head come from the PR itself (its commits are fetched into the local clone, leaving your working tree untouched) rather than the current branch's heuristic base detection, so you can review a teammate's PR without checking it out. The reviewed PR number is persisted on chapter_run so the PR header, CI checks, reviews, and merge controls resolve the targeted PR rather than whatever branch happens to be checked out.

Changes

• Add --pr to prep/show, resolving a PR ref (number, #123, or github.com URL) to local base/head SHAs via gh + git fetch pull/N/head, validating same-repo and surfacing actionable errors.
• Add scope.ts (resolveDiffScope) to unify local-ref and PR scope resolution, and consolidate the per-command diff options into a single object.
• Add a nullable prNumber column to chapter_run (migration 0005) and thread it through ingestion and the /pull-request route so getPullRequest loads the targeted PR.
• Extract a shared ghErrorMessage helper; document --pr in the README and the stage-chapters skill.

Testing

• pnpm typecheck && pnpm lint && pnpm test — all green (307 tests), including new unit tests for the PR-ref parser and a route test proving the prNumber column round-trips and is forwarded to gh.
• Manual end-to-end smoke test: stagereview prep --pr 62 resolved and fetched PR feat(PRO-544): add write capability to the PR header #62, and the validation/error paths (--pr + other flags, invalid ref, nonexistent PR) all surfaced the expected messages.

---

---

Summary by cubic

Review a GitHub PR by number or URL with --pr on stagereview prep and show, with parsing locked to github.com. Implements Linear PRO-545.

• New Features

  • --pr <number-or-url> on prep/show; accepts a number, #123, or a GitHub PR URL; validates same-repo, uses gh to resolve base/head, and fetches refs/pull/<N>/head.
  • Persist prNumber on chapter_run and forward it to /pull-request; getPullRequest targets gh pr view <N> so the UI matches the selected PR. Also honored when showing a complete chapters file by recording only the PR number (no fetch), ensuring the PR header resolves correctly.
  • Hardened PR URL parsing and shared origin validation via parsePullRequestRef, preventing look‑alike hosts and keeping both PR-resolution paths consistent.

• Migration

  • Run CLI DB migrations (adds prNumber to chapter_run).
  • Requires gh installed and authenticated with a github.com origin; --pr cannot be combined with positional refs, --base, --compare, or --ref.

^{Written for commit d71f48c. Summary will update on new commits.}

[stage-review]

Ready to review this PR? Stage has broken it down into 6 individual chapters for you:

	Title
1	Add prNumber column to chapter_run table
2	Implement GitHub PR reference parsing and fetching
3	Unify diff scope resolution logic
4	Integrate PR resolution into prep and show
5	Persist and forward prNumber through API
6	Update documentation and skills for PR support

_{Chapters generated by Stage for commit d71f48c on Jun 7, 2026 7:12pm UTC.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a3d4ebe. Configure here.}

[cubic-dev-ai]

cubic analysis

1 issue found across 21 files

Linked issue analysis

Linked issue: PRO-545: Open a review directly from a PR URL or number

Status	Acceptance criteria	Notes
✅	Add a --pr option to prep and show that accepts a bare number, #N, or a github.com PR URL	CLI wiring, docs, and tests show the option is present and parsed. The option is added in index.ts, README and skill docs updated, and parse tests exercise URL/number parsing.
✅	Parse and validate PR references (number or github.com URL) and reject look-alike hosts or cross-repo URLs	PR-ref parser enforces github.com host boundaries and verifies owner/repo matches the current repo, throwing actionable errors for invalid refs or different repositories.
✅	Resolve PR to local base/head SHAs by calling gh and fetching the PR head (refs/pull/N/head), surfacing actionable gh/git error messages	Implementation loads PR metadata via gh, fetches the PR head and base branch into the local clone, and surfaces errors using a ghErrorMessage helper for actionable diagnostics.
✅	Use the PR's base/head (not local branch heuristics) for computing the diff while leaving the working tree untouched	The new resolveDiffScope path calls resolvePullRequestRefs and then uses resolved SHAs to compute the committed comparison; runPrep/show are updated to use this unified scope so the diff is based on the PR's endpoints.
✅	Persist the targeted PR number on chapter_run and thread it through ingestion and the /pull-request route so UI loads the selected PR instead of the checked-out branch	DB migration and schema add prNumber to chapter_run, insert flows record it, and the pull-request route forwards prNumber to getPullRequest; a test verifies the prNumber is forwarded to gh.
✅	Disallow combining --pr with positional refs, --base, --compare, or --ref, and document the feature	CLI input is validated so --pr cannot be combined with other ref selectors; docs show usage and constraints.

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>