pr-watch

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Check, PullRequest } from '../types'
5
6// Watches the pull requests this session opens and the CI on their heads.
7// A successful `gh pr create` or `fj pr create` adds one; a timer then asks
8// the forge's own CLI for state and checks, so each CLI's login is the only
9// credential involved: GitHub through `gh pr view --json`, Forgejo through
10// `fj pr view` (state, head branch) and `fj actions tasks` (CI per commit).
11const prs = atom({ plugin: 'pr-watch', key: 'prs' } as const, [])
12const PANE = 'pr-watch'
13const TITLE = 'Pull requests'
14const TICK_MS = 20_000
15// A settled PR (CI finished or never reported) is re-asked this often, so a
16// later push that restarts CI is still seen.
17const SETTLED_MS = 5 * 60_000
18// How long a PR with no checks yet counts as waiting for CI to start.
19const WARMUP_MS = 10 * 60_000
20const GLYPH = { pending: '●', pass: '✓', fail: '✗', skip: '–' } as const
21
22type Engine = EngineInterface
23type Parsed = Pick<PullRequest, 'forge' | 'host' | 'repo' | 'number' | 'url'> & Partial<Pick<PullRequest, 'title' | 'head'>>
24
25const keyOf = (p: Pick<PullRequest, 'host' | 'repo' | 'number'>) => `${p.host}/${p.repo}#${p.number}`
26
27// The value of `--name value`, `--name=value` or `-n value` in a command line.
28export const flagOf = (command: string, ...names: string[]): string | undefined => {
29  for (const name of names) {
30    const found = command.match(new RegExp(`(?:^|\\s)${name}(?:=|\\s+)(['"]?)([^\\s'"]+)\\1`))
31    if (found) return found[2]
32  }
33  return undefined
34}
35
36// `host` and `owner/repo` from a remote URL in any of git's spellings.
37export const remoteRepo = (url: string): { host: string; repo: string } | undefined => {
38  const found = url.trim().match(/^(?:[a-z+]+:\/\/)?(?:[^@/\s]+@)?([^:/\s]+)(?::\d+)?[:/]([^/\s]+\/[^/\s]+?)(?:\.git)?\/?$/)
39  const [, host, repo] = found ?? []
40  return host && repo ? { host, repo } : undefined
41}
42
43// A PR URL on either forge: GitHub's `/pull/N`, Forgejo's `/pulls/N`.
44export const parseUrl = (text: string): Parsed | undefined => {
45  const found = text.match(/https?:\/\/([^/\s]+)\/([^/\s]+\/[^/\s]+)\/(pull|pulls)\/(\d+)/)
46  const [url, host, repo, kind, number] = found ?? []
47  if (!url || !host || !repo || !number) return undefined
48  return { forge: kind === 'pull' ? 'github' : 'forgejo', host, repo, number: Number(number), url }
49}
50
51const GH_CREATE = /\bgh\s+pr\s+create\b/
52const FJ_CREATE = /\bfj\b[^|;&\n]*\bpr\s+create\b/
53
54// A `gh pr create` prints the new PR's URL.
55export const parseGhCreate = (command: string, output: string): Parsed | undefined => {
56  if (!GH_CREATE.test(command)) return undefined
57  const pr = parseUrl(output)
58  return pr?.forge === 'github' ? { ...pr, head: flagOf(command, '--head', '-H') } : undefined
59}
60
61// A `fj pr create` prints `created pull request #N: <title>`, isolates and
62// all (see `plain`); the host and
63// repo come from its flags, or from `remote` when it inferred them.
64export const parseFjCreate = (
65  command: string,
66  output: string,
67  remote?: { host: string; repo: string },
68): Parsed | undefined => {
69  if (!FJ_CREATE.test(command)) return undefined
70  const created = plain(output).match(/created pull request #(\d+): ?(.*)/)
71  if (!created) return undefined
72  const host = flagOf(command, '-H', '--host') ?? remote?.host
73  const repo = flagOf(command, '-r', '--repo') ?? remote?.repo
74  if (!host || !repo) return undefined
75  const number = Number(created[1])
76  return {
77    forge: 'forgejo',
78    host,
79    repo,
80    number,
81    url: `https://${host}/${repo}/pulls/${number}`,
82    title: created[2]?.trim() || undefined,
83    head: flagOf(command, '--head'),
84  }
85}
86
87export const verdictOf = (checks: readonly Check[]): PullRequest['verdict'] =>
88  checks.length === 0
89    ? 'none'
90    : checks.some(c => c.state === 'fail')
91      ? 'fail'
92      : checks.some(c => c.state === 'pending')
93        ? 'pending'
94        : 'pass'
95
96type GhCheck = { __typename?: string; name?: string; context?: string; status?: string; conclusion?: string; state?: string }
97
98// `gh pr view --json title,state,headRefName,statusCheckRollup`: check runs
99// carry status + conclusion, legacy commit statuses carry context + state.
100export const parseGhView = (json: string): Pick<PullRequest, 'title' | 'head' | 'state' | 'checks'> => {
101  const v = JSON.parse(json) as { title?: string; state?: string; headRefName?: string; statusCheckRollup?: GhCheck[] }
102  const checks = (v.statusCheckRollup ?? []).map((c): Check => {
103    if (c.context !== undefined) {
104      const state = c.state === 'SUCCESS' ? 'pass' : c.state === 'PENDING' || c.state === 'EXPECTED' ? 'pending' : 'fail'
105      return { name: c.context, state }
106    }
107    const done = c.status === 'COMPLETED'
108    const state = !done
109      ? 'pending'
110      : c.conclusion === 'SUCCESS'
111        ? 'pass'
112        : c.conclusion === 'NEUTRAL' || c.conclusion === 'SKIPPED'
113          ? 'skip'
114          : 'fail'
115    return { name: c.name ?? '?', state }
116  })
117  return {
118    title: v.title,
119    head: v.headRefName,
120    state: v.state === 'MERGED' ? 'merged' : v.state === 'CLOSED' ? 'closed' : 'open',
121    checks,
122  }
123}
124
125// fj wraps every interpolated value in Unicode isolates (U+2068, U+2069).
126const plain = (text: string) => text.replace(/[⁦-⁩]/g, '').replace(/\u001b\[[0-9;]*m/g, '')
127
128// `fj pr view`: `<title> #N`, then `By <user> — <State> — +a -b`, then
129// "From `<head>` into `<base>`".
130export const parseFjView = (output: string): Pick<PullRequest, 'title' | 'head' | 'state'> => {
131  const lines = plain(output).split('\n')
132  const title = lines[0]?.replace(/\s+#\d+\s*$/, '').trim() || undefined
133  const state = lines[1]?.match(/\b(Open|Draft|Merged|Closed)\b/)?.[1]
134  const head = lines[2]?.match(/From `([^`]+)`/)?.[1]
135  return { title, head, state: state === 'Merged' ? 'merged' : state === 'Closed' ? 'closed' : 'open' }
136}
137
138export type Task = { id: number; sha: string; status: string; name: string; event: string }
139
140// `fj actions tasks`, newest first:
141// `#24 (c968e0637a) success validate 1m13s (pull_request): <commit title>`.
142export const parseFjTasks = (output: string): Task[] =>
143  plain(output)
144    .split('\n')
145    .flatMap(line => {
146      const [, id, sha, status, rest, event] = line.match(/^#(\d+) \(([0-9a-f]+)\) (\S+) (.+?) \(([\w-]+)\): /) ?? []
147      if (!id || !sha || !status || !rest || !event) return []
148      return [{ id: Number(id), sha, status, name: rest.replace(/\s+\S*\d+s$/, ''), event }]
149    })
150
151const taskState = (status: string): Check['state'] =>
152  status === 'success' ? 'pass' : status === 'skipped' ? 'skip' : status === 'failure' || status === 'cancelled' ? 'fail' : 'pending'
153
154// The newest task per workflow job on commit `sha`, as checks.
155export const checksForCommit = (tasks: readonly Task[], sha: string): Check[] => {
156  const seen = new Map<string, Check>()
157  for (const t of tasks) {
158    if (sha.startsWith(t.sha) && !seen.has(t.name)) seen.set(t.name, { name: t.name, state: taskState(t.status) })
159  }
160  return [...seen.values()]
161}
162
163const run = async ($: Engine, argv: string[]) => {
164  try {
165    const out = await $.process.run(argv, { timeoutMs: 20_000 })
166    return out.exitCode === 0 ? out.stdout : undefined
167  } catch {
168    return undefined
169  }
170}
171
172// The commit a branch points at, as last pushed (a jj bookmark is exported
173// to the same refs in a colocated repo).
174const shaOf = async ($: Engine, head: string) => {
175  for (const ref of [`refs/remotes/origin/${head}`, `refs/heads/${head}`]) {
176    const sha = (await run($, ['git', 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`]))?.trim()
177    if (sha) return sha
178  }
179  return undefined
180}
181
182type Fresh = Pick<PullRequest, 'title' | 'head' | 'state' | 'checks'>
183
184const askGitHub = async ($: Engine, pr: PullRequest): Promise<Fresh | undefined> => {
185  const json = await run($, ['gh', 'pr', 'view', pr.url, '--json', 'title,state,headRefName,statusCheckRollup'])
186  if (json === undefined) return undefined
187  try {
188    return parseGhView(json)
189  } catch {
190    return undefined
191  }
192}
193
194const askForgejo = async ($: Engine, pr: PullRequest): Promise<Fresh | undefined> => {
195  const view = await run($, ['fj', '-H', pr.host, 'pr', 'view', `${pr.repo}#${pr.number}`])
196  if (view === undefined) return undefined
197  const seen = parseFjView(view)
198  const head = seen.head ?? pr.head
199  const sha = head && (await shaOf($, head))
200  const tasks = sha ? await run($, ['fj', '-H', pr.host, 'actions', 'tasks', '-r', pr.repo]) : undefined
201  return { ...seen, head, checks: sha && tasks ? checksForCommit(parseFjTasks(tasks), sha) : pr.checks }
202}
203
204const isDue = (pr: PullRequest, now: number) => {
205  if (pr.state !== 'open') return false
206  const waiting = pr.verdict === 'pending' || (pr.verdict === 'none' && now - pr.addedAt < WARMUP_MS)
207  return waiting || now - pr.polledAt >= SETTLED_MS
208}
209
210// What changed between two polls of one PR that is worth a toast.
211export const newsOf = (before: PullRequest, after: PullRequest): string | undefined => {
212  const label = `PR #${after.number}`
213  if (before.state === 'open' && after.state !== 'open') return `${label} ${after.state}`
214  if (after.verdict === before.verdict) return undefined
215  if (after.verdict === 'pass') return `${label}: CI passed`
216  if (after.verdict === 'fail') {
217    const failed = after.checks.filter(c => c.state === 'fail').map(c => c.name)
218    return `${label}: CI failed (${failed.join(', ')})`
219  }
220  return undefined
221}
222
223let isPolling = false
224
225const poll = async ($: Engine, force = false) => {
226  if (isPolling) return
227  isPolling = true
228  try {
229    const now = await $.clock.now()
230    for (const pr of await read($, prs)) {
231      if (!force && !isDue(pr, now)) continue
232      const fresh = pr.forge === 'github' ? await askGitHub($, pr) : await askForgejo($, pr)
233      if (!fresh) continue
234      const after: PullRequest = {
235        ...pr,
236        ...fresh,
237        title: fresh.title ?? pr.title,
238        verdict: verdictOf(fresh.checks),
239        polledAt: now,
240      }
241      await update($, prs, list => list.map(p => (p.key === pr.key ? after : p)))
242      const news = newsOf(pr, after)
243      if (news) $.ui.toast(news, { timeoutMs: 8000 })
244    }
245  } finally {
246    isPolling = false
247  }
248}
249
250let ticker: { cancel: () => void } | undefined
251
252const ensureTicking = ($: Engine) => {
253  ticker ??= $.clock.every(TICK_MS, () => void poll($))
254}
255
256const track = async ($: Engine, found: Parsed) => {
257  const now = await $.clock.now()
258  const key = keyOf(found)
259  const fresh: PullRequest = { ...found, key, state: 'open', checks: [], verdict: 'none', addedAt: now, polledAt: 0 }
260  await update($, prs, list => [list.find(p => p.key === key) ?? fresh, ...list.filter(p => p.key !== key)])
261  void $.ui.open({ id: PANE, title: TITLE }).catch(() => undefined)
262  ensureTicking($)
263  await poll($)
264}
265
266// What a Bash call printed, from its record or from the text the model got.
267const outputOf = (ran: { result?: unknown; text?: string }) => {
268  const record = ran.result as { stdout?: unknown } | undefined
269  return [typeof record?.stdout === 'string' ? record.stdout : '', ran.text ?? ''].join('\n')
270}
271
272const remoteOf = async ($: Engine, command: string) => {
273  const url = await run($, ['git', 'remote', 'get-url', flagOf(command, '-R', '--remote') ?? 'origin'])
274  return url ? remoteRepo(url) : undefined
275}
276
277const describe = (list: readonly PullRequest[]) =>
278  list
279    .map(pr =>
280      [
281        `${pr.state === 'open' ? GLYPH[pr.verdict === 'none' ? 'pending' : pr.verdict] : pr.state} ${pr.repo}#${pr.number}${pr.title ? ` ${pr.title}` : ''}`,
282        ...pr.checks.map(c => `  ${GLYPH[c.state]} ${c.name}`),
283      ].join('\n'),
284    )
285    .join('\n')
286
287export const register: Register = on => {
288  on('session.start', async ($, e, next) => {
289    await $.command.register({
290      name: 'prs',
291      description: 'Show the pull requests this session watches and their CI',
292      argumentHint: '[add <url> | refresh | clear]',
293    })
294    if ((await read($, prs)).some(p => p.state === 'open')) ensureTicking($)
295    return next(e)
296  })
297
298  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
299    const ran = await next(e)
300    if (ran.deny !== undefined || ran.isError) return ran
301    const command = String(e.command ?? '')
302    if (!GH_CREATE.test(command) && !FJ_CREATE.test(command)) return ran
303    const output = outputOf(ran)
304    const needsRemote = FJ_CREATE.test(command) && !(flagOf(command, '-H', '--host') && flagOf(command, '-r', '--repo'))
305    const found =
306      parseGhCreate(command, output) ??
307      parseFjCreate(command, output, needsRemote ? await remoteOf($, command) : undefined)
308    if (found) await track($, found)
309    return ran
310  })
311
312  on('command.run', { command: 'prs' }, async ($, e) => {
313    const [verb = '', arg = ''] = e.args.trim().split(/\s+/)
314    if (verb === 'add') {
315      const found = parseUrl(arg)
316      if (!found) return { text: 'Usage: /prs add <PR URL>' }
317      await track($, found)
318      return { text: `Watching ${found.repo}#${found.number}.` }
319    }
320    if (verb === 'refresh') {
321      await poll($, true)
322    } else if (verb === 'clear') {
323      await update($, prs, list => list.filter(p => p.state === 'open'))
324      return { text: 'Cleared merged and closed pull requests.' }
325    } else if (verb !== '') {
326      return { text: 'Usage: /prs [add <url> | refresh | clear]' }
327    }
328    await $.ui.open({ id: PANE, title: TITLE })
329    const list = await read($, prs)
330    return { text: list.length === 0 ? 'No pull requests yet.' : describe(list) }
331  })
332
333  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
334    const { Box, Text } = $.ui.resolve(e)
335    const list = await read($, prs)
336    return (
337      <Box flexDirection="column">
338        {list.length === 0 && <Text dimColor>No pull requests yet.</Text>}
339        {list.map(pr => {
340          const isOpen = pr.state === 'open'
341          const verdict = pr.verdict === 'none' ? 'pending' : pr.verdict
342          const color = !isOpen ? undefined : verdict === 'pass' ? 'green' : verdict === 'fail' ? 'red' : 'yellow'
343          return (
344            <Box flexDirection="column" marginBottom={1}>
345              <Box>
346                <Text bold color={color} dimColor={!isOpen}>
347                  {isOpen ? GLYPH[verdict] : pr.state} #{pr.number}
348                </Text>
349                <Box flexShrink={1}>
350                  <Text dimColor={!isOpen} wrap="truncate-end">
351                    {' '}
352                    {pr.title ?? ''}
353                  </Text>
354                </Box>
355              </Box>
356              <Text dimColor wrap="truncate-end">
357                {'  '}
358                {pr.repo}
359                {isOpen && pr.checks.length === 0 ? ' · no checks yet' : ''}
360              </Text>
361              {isOpen &&
362                pr.checks.map(c => (
363                  <Text dimColor={c.state === 'pass' || c.state === 'skip'} wrap="truncate-end">
364                    {'  '}
365                    {GLYPH[c.state]} {c.name}
366                  </Text>
367                ))}
368            </Box>
369          )
370        })}
371      </Box>
372    )
373  })
374}
375

1// One CI check on a PR's head commit, reduced to the four states the pane
2// draws: `pending` covers queued, running and waiting alike.
3export type Check = {
4  name: string
5  state: 'pending' | 'pass' | 'fail' | 'skip'
6}
7
8// One pull request this session watches. `key` is `<host>/<repo>#<number>`.
9// `head` is the source branch, which Forgejo needs to find the commit its
10// tasks ran on. `verdict` is `none` until the forge reports a check. Times
11// are `$.clock.now()` milliseconds.
12export type PullRequest = {
13  key: string
14  forge: 'github' | 'forgejo'
15  host: string
16  repo: string
17  number: number
18  url: string
19  title?: string
20  head?: string
21  state: 'open' | 'merged' | 'closed'
22  checks: Check[]
23  verdict: 'none' | 'pending' | 'pass' | 'fail'
24  addedAt: number
25  polledAt: number
26}
27
28declare module 'claude-code' {
29  interface PluginState {
30    'pr-watch': { prs: PullRequest[] }
31  }
32}
33