cav-review

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { ReviewSummary } from '../types'
5
6// cav review keeps its notes in <renders>/<video>.review.json. This plugin asks Claude Code
7// to watch that folder and reads the newest file when it changes: a band above the prompt
8// shows the open notes and links to the page, a toast says when the reviewer presses "Send to
9// agent", and (option `wake`) a turn starts that reads the notes with `cav review wait`.
10
11const summary = atom({ plugin: 'cav-review', key: 'summary' } as const, null)
12const hidden = atom({ plugin: 'cav-review', key: 'hidden' } as const, false)
13const announced = atom({ plugin: 'cav-review', key: 'announced' } as const, null)
14
15// What `cav review export --json` prints (the fields the band uses).
16type Export = {
17  video: string
18  reviewFile: string
19  notes?: { status: string; onOlderRender?: boolean }[] | null
20  sends?: { n: number; comments: string[]; deliveredAt?: string }[] | null
21  server?: { url: string } | null
22}
23
24function summarize(x: Export): ReviewSummary {
25  const notes = x.notes ?? []
26  const open = notes.filter(n => n.status === 'open')
27  const pending = (x.sends ?? []).find(s => !s.deliveredAt)
28  return {
29    video: x.video,
30    file: x.reviewFile,
31    open: open.length,
32    resolved: notes.length - open.length,
33    olderOpen: open.filter(n => n.onOlderRender).length,
34    pending: pending ? { n: pending.n, notes: pending.comments.length } : null,
35    // Surfaces link only https: and http://localhost; the review server answers both names.
36    url: x.server?.url ? x.server.url.replace('//127.0.0.1:', '//localhost:') : null,
37  }
38}
39
40function wakePrompt(s: ReviewSummary): string {
41  return (
42    `The reviewer pressed "Send to agent" in cav review: ${s.pending?.notes ?? 0} note(s) on ${s.video}. ` +
43    `Run \`cav review wait ${s.video} --timeout 10s\` to read them (it prints each note's frame, text, drawing and snapshot path, ` +
44    `and marks the send received), look at each snapshot, fix the notes, re-render to the same file, then resolve each with ` +
45    `\`cav review resolve <id> --note "what changed"\`.`
46  )
47}
48
49// Reads the newest review file and updates the band. Nothing polls: this runs when the
50// session starts, when Claude Code reports a change to a watched file, and around turns.
51async function refresh($: EngineInterface, folder: string, wake: boolean) {
52  // cav finds the newest review file and reads it, so the format lives in one place.
53  const r = await $.process.run(['cav', 'review', 'export', '--json', '--dir', folder], { timeoutMs: 15000 })
54  let x: Export | null = null
55  if (r.exitCode === 0) {
56    try {
57      x = JSON.parse(r.stdout)
58    } catch {
59      return
60    }
61  }
62  if (x === null || !x.reviewFile) {
63    if ((await read($, summary)) !== null) await update($, summary, () => null)
64    return
65  }
66  const s = summarize(x)
67  const before = await read($, summary)
68  if (JSON.stringify(before) !== JSON.stringify(s)) await update($, summary, () => s)
69
70  if (s.pending) {
71    const key = `${s.file}#${s.pending.n}`
72    if ((await read($, announced)) !== key) {
73      await update($, announced, () => key)
74      await update($, hidden, () => false)
75      $.ui.toast(`cav review: the reviewer sent ${s.pending.notes} note(s) on ${s.video}`, { timeoutMs: 8000 })
76      if (wake) await $.prompt.submit({ text: wakePrompt(s) })
77    }
78  }
79}
80
81export const register: Register = (on, options) => {
82  const folder = typeof options.folder === 'string' && options.folder !== '' ? options.folder : 'renders'
83  const wake = options.wake !== false
84
85  // Ask Claude Code to watch the renders folder and the review files in it.
86  on('classic.SessionStart', async ($, e, next) => {
87    const result = await next(e)
88    const base = `${e.cwd}/${folder}`
89    const paths = [base]
90    try {
91      for (const f of await $.fs.list(folder)) {
92        if (f.kind === 'file' && f.name.endsWith('.review.json')) paths.push(`${base}/${f.name}`)
93      }
94    } catch {
95      // the folder appears later; watching it catches that
96    }
97    return { ...result, watchPaths: [...(result.watchPaths ?? []), ...paths] }
98  }).catch(($, e, next) => next(e))
99
100  on('classic.FileChanged', async ($, e, next) => {
101    if (e.file_path.endsWith('.review.json') || e.file_path.endsWith(`/${folder}`)) await refresh($, folder, wake)
102    return next(e)
103  }).catch(($, e, next) => next(e))
104
105  on('session.start', async ($, e, next) => {
106    await refresh($, folder, wake)
107    return next(e)
108  })
109
110  // A failure here must never hold up the person's prompt.
111  on('prompt.submit', async ($, e, next) => {
112    refresh($, folder, wake).catch(() => {})
113    return next(e)
114  }).catch(($, e, next) => next(e))
115
116  on('turn.complete', async ($, e, next) => {
117    refresh($, folder, wake).catch(() => {})
118    return next(e)
119  }).catch(($, e, next) => next(e))
120
121  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
122    const s = await read($, summary)
123    if (s === null || e.props.hasSurvey || (await read($, hidden)) || (s.open === 0 && !s.pending)) {
124      return next(e)
125    }
126    const { Box, Button, Link, Text } = $.ui.resolve(e)
127    const name = s.video.split('/').pop()
128    return (
129      <Box flexDirection="row" gap={1} flexWrap="wrap">
130        <Text bold>cav review</Text>
131        <Text>
132          {name}: {s.open} open note{s.open === 1 ? '' : 's'}
133          {s.olderOpen > 0 ? ` (${s.olderOpen} on an older render)` : ''}
134        </Text>
135        {s.pending ? (
136          <Text color="yellow">
137            send #{s.pending.n} waiting: {s.pending.notes} note{s.pending.notes === 1 ? '' : 's'}
138          </Text>
139        ) : null}
140        {s.url ? <Link href={s.url} label="open the page" /> : null}
141        {s.pending ? (
142          <Button key="handle" label="Handle notes" onPress={() => $.prompt.submit({ text: wakePrompt(s) })} />
143        ) : null}
144        <Button key="hide" label="Hide" onPress={() => update($, hidden, () => true)} />
145      </Box>
146    )
147  })
148}
149

1// What the band draws: the newest review file in the renders folder.
2export type ReviewSummary = {
3  video: string // the render's path, as cav review recorded it
4  file: string // the review file
5  open: number // open notes
6  resolved: number
7  olderOpen: number // open notes made on an older render
8  pending: { n: number; notes: number } | null // a send no agent has picked up
9  url: string | null // the running review page, when cav review serves it
10}
11
12declare module 'claude-code' {
13  interface PluginState {
14    'cav-review': {
15      summary: ReviewSummary | null
16      hidden: boolean
17      // The last send announced, so a send wakes the session once.
18      announced: string | null
19    }
20  }
21}
22