# pi-pr

A [pi coding agent](https://github.com/earendil-works/pi) extension that shows
the current branch's GitHub pull request in the footer: a lifecycle letter and a
clickable `#n` link, the diff stat (`+42-10`), the CI status, a conflict alarm
when the PR can't merge cleanly, and the review verdict. Merged and closed PRs
collapse to just the letter and number (plus a red CI dot if CI broke).


```
approved:          model (branch)  …  O #123 +42-10 ●✓
changes requested: model (branch)  …  O #123 +42-10 ●✗
review pending:    model (branch)  …  O #123 +42-10 ●
conflict:          model (branch)  …  O #123 +42-10 ●‼✗
draft:             model (branch)  …  D #123 +42-10 ●
merged (ok):       model (branch)  …  M #123
merged (ci broke): model (branch)  …  M #123 ●
closed:            model (branch)  …  C #123
                                      ^^^^^^ ^^^^^^^ ^^^
                                      link   diffstat indicators
```

## What it does

On session start (and every poll interval after) it runs `gh pr view` for the
current branch and renders the result via `ctx.ui.setStatus("pi-pr", …)`, which
coexists with pi's built-in footer. It also fires a one-off refresh right after
the agent runs a `gh pr create` bash command, so a freshly opened PR appears in
the footer without waiting for the next poll tick.

- **lifecycle letter + `#n`** — a letter describing lifecycle (`D` draft, `O`
  open, `M` merged, `C` closed) followed by the PR number, together wrapped in
  an OSC 8 hyperlink to the PR URL and colored by lifecycle: draft = dim,
  open = default text, closed = red, merged = purple. Merged uses a raw
  256-color purple tuned to the terminal background (from `COLORFGBG`): a bright
  lilac on dark, a deeper purple on light — since no theme token is purple.
- **diff stat** — for active PRs only, additions (`+42`, green) and deletions
  (`-10`, red) from the PR. Hidden when the PR has no changes, and dropped for
  merged/closed PRs.
- **`●` CI** — aggregated check rollup: success = green, failure = red,
  running = yellow, none = dim. For active PRs it is always rendered (`none` dim
  so its position stays stable). Merged and closed PRs are terminal states, so
  the CI dot shows **only** when CI failed (red) and is hidden otherwise.
- **`‼` conflict** — red, shown **only** for active PRs with merge conflicts
  (`clean`/`unknown` merge states, and terminal states, render nothing).
- **review verdict** — shown **only** for active PRs when a decision exists: `✓`
  green when approved, `✗` red when changes are requested.
  `review_required`/`none` render nothing.

Glyphs keep a fixed order: CI, then conflict, then review verdict. On active
PRs only `●` always shows; the conflict and review glyphs appear/disappear with
state. Merged and closed PRs show at most the CI dot, and only when broken.

When there is no PR for the branch, the directory is not a
GitHub repo, `gh` is missing or unauthenticated, or any error occurs, the
extension is silent: it clears its status and shows nothing.

## Requirements

- The [`gh`](https://cli.github.com/) CLI, authenticated (`gh auth login`).
- A terminal that supports OSC 8 hyperlinks for the clickable `#n` (plain text
  otherwise — no breakage).

## Command

- **`/pr`** — open the current branch's PR in the browser (`gh pr view --web`)
  and force an immediate status refresh.

## Flags

- `pi-pr-interval` (default `30`) — poll interval in seconds. Floored at 5s to
  avoid abuse and API rate limits. (Registered as a string flag because pi flags
  are boolean or string only; the value is parsed as a number at use.)

## Notes

- Polling uses a fixed `setInterval` with an overlap guard, so a slow `gh` call
  never piles up. A branch switch is reflected within one interval; `/pr` forces
  an immediate refresh.

## Development

```bash
pnpm install
pnpm test
pnpm typecheck
pnpm check
```

To test changes manually:

```bash
pi -e packages/pi-pr/src/index.ts
```