git-workflow

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Desk, DeskItem } from '../types'
5import {
6  bareGoAhead, deskTarget, isOpen, itemsOf, mentions, pollHeaders, projectOf, recentClosed,
7  statusLine, transitions, unclosed, waiting, wordOf,
8} from './desk'
9import type { StateFile } from './desk'
10
11const shown = atom({ plugin: 'git-workflow', key: 'items' } as const, [] as DeskItem[])
12const deskAtom = atom({ plugin: 'git-workflow', key: 'desk' } as const, null as Desk | null)
13
14const POLL_MS = 4000
15// a file untouched for this long holds no live request
16const STALE_FILE_MS = 26 * 3600 * 1000
17const COLOR = { PR: 'magenta', ISSUE: 'green' } as const
18// only what the user typed is guarded: a notification or a peer saying "ok" is not an answer
19const TYPED = ['composer', 'bridge']
20const STATUS_COLOR: Record<string, string> = { 'needs-input': 'yellow', running: 'cyan' }
21const LAUNCH = 'Apri il git desk con la skill git-desk e collega questa chat.'
22const APP_SESSIONS = 'Library/Application Support/Claude/claude-code-sessions'
23
24const files: Record<string, StateFile> = {}
25const memo: {
26  before: Record<string, string> | null; polling: boolean; etag: string | null; base: string | null
27  closed: Record<string, number> | null
28} = { before: null, polling: false, etag: null, base: null, closed: null }
29
30/** The requests closed with ✕, kept in the plugin's store so a restart does not bring them back. */
31async function closedIds($: EngineInterface, nowMs: number) {
32  if (!memo.closed) {
33    const stored = await $.store.get('closed')
34    memo.closed = recentClosed((stored ?? {}) as Record<string, number>, nowMs, STALE_FILE_MS)
35  }
36  return memo.closed
37}
38
39async function stateDir($: EngineInterface) {
40  const configured = await $.env.get('GIT_WORKFLOW_STATE_DIR')
41  if (configured) return configured
42  const home = await $.env.get('HOME')
43  return home ? `${home}/.local/state/git-workflow` : null
44}
45
46async function readFiles($: EngineInterface, now: number) {
47  const dir = await stateDir($)
48  if (!dir || !(await $.fs.exists(dir))) return
49  for (const entry of await $.fs.list(dir)) {
50    if (entry.kind !== 'file' || !/^[^.].*__.*\.json$/.test(entry.name)) continue
51    if (now - entry.mtimeMs > STALE_FILE_MS) { delete files[entry.name]; continue }
52    if (files[entry.name]?.mtime === entry.mtimeMs) continue
53    try {
54      files[entry.name] = { mtime: entry.mtimeMs, state: JSON.parse(await $.fs.read(`${dir}/${entry.name}`)) }
55    } catch {
56      // a file mid-write: the next poll reads it whole
57    }
58  }
59}
60
61async function getJSON($: EngineInterface, url: string, etag?: string | null) {
62  const got = await $.http.fetch(url, { headers: pollHeaders(etag) })
63  if (got.status === 304) return { data: null, etag: etag ?? null }
64  if (!got.ok) throw new Error(`${url}: HTTP ${got.status}`)
65  return { data: JSON.parse(got.text), etag: got.headers?.etag ?? got.headers?.ETag ?? null }
66}
67
68/** The desk this chat drives, if it answers. */
69async function readDesk($: EngineInterface, session: string, nowSec: number) {
70  const target = deskTarget(files, session, nowSec)
71  const known = await read($, deskAtom)
72  if (!target) {
73    if (known) await update($, deskAtom, () => null)
74    return
75  }
76  const base = `http://127.0.0.1:${target.port}`
77  if (memo.base !== base) Object.assign(memo, { base, etag: null })
78  const fresh = { base, repo: target.repo, attached: target.attached }
79  if (!known || known.base !== fresh.base || known.attached !== fresh.attached)
80    await update($, deskAtom, () => fresh)
81  try {
82    memo.etag = (await getJSON($, `${base}/api/todo`, memo.etag)).etag
83  } catch {
84    // a desk that stopped answering: its registration outlives it until it says it stopped
85    await update($, deskAtom, () => null)
86    memo.etag = null
87  }
88}
89
90// a poll that fails is the next poll's to repeat: nothing waits on it
91const repoll = ($: EngineInterface) => { poll($).catch(() => undefined) }
92
93async function poll($: EngineInterface) {
94  if (memo.polling) return
95  memo.polling = true
96  try {
97    const now = await $.clock.now()
98    await readFiles($, now)
99    const session = await $.session.id()
100    const nowSec = now / 1000
101    const attached = Object.values(files).some(f => mentions(f.state, session))
102    const closed = await closedIds($, now)
103    const all: DeskItem[] = []
104    for (const [name, file] of Object.entries(files)) {
105      const repo = name.replace(/\.json$/, '').replace('__', '/')
106      for (const item of itemsOf(repo, file.state, nowSec))
107        if (!attached || item.session === session) all.push(item)
108    }
109    const items = unclosed(all, closed)
110    if (memo.before) for (const line of transitions(memo.before, items)) $.ui.toast(line, { timeoutMs: 8000 })
111    memo.before = Object.fromEntries(items.map(i => [i.key, i.status]))
112    const open = items.filter(isOpen)
113    await update($, shown, () => open)
114    await readDesk($, session, nowSec)
115    $.ui.status(statusLine(open))
116  } finally {
117    memo.polling = false
118  }
119}
120
121/** The page in the Browser pane where the host has one; otherwise its link. */
122async function openDesk($: EngineInterface, desk: Desk) {
123  const url = `${desk.base}/`
124  try {
125    const got = await $.mcp.call('Claude_Browser', 'preview_start', { url })
126    if (!got.isError) return `Desk di ${desk.repo}: lo apro nel Browser pane.`
127  } catch {
128    // no Browser pane on this host: the link instead
129  }
130  return `Desk di ${desk.repo}: ${url}`
131}
132
133async function closeRow($: EngineInterface, item: DeskItem) {
134  const now = await $.clock.now()
135  const closed = { ...recentClosed(await closedIds($, now), now, STALE_FILE_MS), [item.id]: now }
136  memo.closed = closed
137  await $.store.set('closed', closed)
138  const open = (await read($, shown)).filter(i => i.id !== item.id)
139  await update($, shown, () => open)
140  $.ui.status(statusLine(open))
141}
142
143/** The desktop app's session that runs the loop, by the CLI session id the ledger keeps. */
144async function appSession($: EngineInterface, cliSession: string) {
145  const home = await $.env.get('HOME')
146  if (!home) return null
147  const found = await $.process.run(['grep', '-rlF', '--include=local_*.json', cliSession, `${home}/${APP_SESSIONS}`])
148  for (const path of found.stdout.split('\n').filter(Boolean)) {
149    try {
150      const record = JSON.parse(await $.fs.read(path)) as { sessionId?: string; cliSessionId?: string }
151      if (record.cliSessionId === cliSession && record.sessionId) return record.sessionId
152    } catch {
153      // a record mid-write: the next candidate
154    }
155  }
156  return null
157}
158
159async function gotoChat($: EngineInterface, item: DeskItem) {
160  try {
161    const local = await appSession($, item.session)
162    if (local) {
163      const got = await $.process.run(['open', `claude://claude.ai/epitaxy/${local}`])
164      if (got.exitCode === 0) return
165    }
166  } catch {
167    // no desktop app on this host: the resume command instead
168  }
169  $.ui.toast(`La chat di ${item.label}: claude --resume ${item.session}`, { timeoutMs: 15000 })
170}
171
172export const register: Register = on => {
173  on('session.start', async ($, e, next) => {
174    const result = await next(e)
175    await $.command.register({ name: 'desk', description: 'Open the git desk of this chat in the Browser pane' })
176    await $.tool.register({
177      name: 'desk_open',
178      description: 'Call it right after launching the git desk server: it answers this chat\'s session id ' +
179        'to attach with, and the desk page to open now in the Browser pane.',
180    })
181    await poll($).catch(() => undefined)
182    $.clock.every(POLL_MS, () => repoll($))
183    return result
184  })
185
186  on('command.run', { command: 'desk' }, async $ => {
187    const desk = await read($, deskAtom)
188    if (!desk) return { text: 'Nessun desk aperto: lo avvio in questa chat.', context: [LAUNCH] }
189    return { text: await openDesk($, desk) }
190  })
191
192  on('tool.call', { tool: 'mcp__git-workflow__desk_open' }, async $ => {
193    const session = await $.session.id()
194    const attach = ` This chat's session id is ${session}: pass it as --session to chatdesk.py.`
195    await poll($).catch(() => undefined)
196    const desk = await read($, deskAtom)
197    if (!desk) {
198      return { result: 'No desk answers yet: its server is still binding the port. Call this tool again in a ' +
199        'second.' + attach }
200    }
201    return { result: `The desk of ${desk.repo} is up: open ${desk.base}/ in the Browser pane now ` +
202      '(preview_start with that url), also while its triage runs, which the page shows at the bottom; a host ' +
203      'without one gets the link.' + attach }
204  })
205
206  on('prompt.submit', async ($, e, next) => {
207    if (!TYPED.includes(e.origin?.kind ?? '') || !bareGoAhead(e.text)) return next(e)
208    const loops = waiting(await read($, shown))
209    const repos = loops.map(i => i.repo)
210    const name = (i: DeskItem) => `${i.tag} ${projectOf(i.repo, repos)} ${i.label}`
211    if (loops.length > 1) {
212      return { drop: `Aspettano una risposta in più d'uno: ${loops.map(name).join(', ')}. Scrivi a quale va (es. "pr vai").` }
213    }
214    if (loops.length === 1) {
215      const only = loops[0]!
216      const note = `desk: the one desk request waiting for an answer is ${only.tag} ${only.label} (${only.repo}): this message answers it.`
217      return next({ ...e, context: [...(e.context ?? []), note] })
218    }
219    return next(e)
220  })
221
222  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
223    const items = await read($, shown)
224    if (e.props.hasSurvey || !items.length) return next(e)
225    const session = await $.session.id()
226    const { Box, Text, Button } = $.ui.resolve(e)
227    const repos = items.map(i => i.repo)
228    const rows = [...items].sort((a, b) =>
229      Number(b.status === 'needs-input') - Number(a.status === 'needs-input') || a.at.localeCompare(b.at))
230    return (
231      <Box flexDirection="column">
232        {rows.slice(0, Math.max(1, e.props.maxRows - 1)).map(item => (
233          <Box key={item.key} flexDirection="row" gap={1}>
234            <Box flexDirection="row" flexGrow={1} flexShrink={1} minWidth={0} overflow="hidden">
235              <Box flexShrink={0}><Text color={COLOR[item.tag]} bold>● {item.tag === 'PR' ? 'PR   ' : 'ISSUE'} </Text></Box>
236              <Box flexShrink={1} minWidth={0}>
237                <Text wrap="truncate-end">{`${projectOf(item.repo, repos)} · ${item.label} · `}</Text></Box>
238              <Box flexShrink={0}>
239                <Text wrap="truncate-end" color={STATUS_COLOR[item.status]} bold={item.status === 'needs-input'}>
240                  {wordOf(item.status)}{item.at ? ` dalle ${item.at}` : ''}</Text></Box>
241              {item.report ? <Box flexShrink={1} flexGrow={1} minWidth={0}>
242                <Text dimColor wrap="truncate-end"> · {item.report}</Text></Box> : null}
243            </Box>
244            {item.session && item.session !== session ? <Box flexShrink={0}>
245              <Button key={`goto-${item.key}`} plain onPress={() => { void gotoChat($, item) }}>↗</Button></Box> : null}
246            <Box flexShrink={0}>
247              <Button key={`close-${item.key}`} role="dismiss" plain dimColor
248                onPress={() => { void closeRow($, item) }}>✕</Button></Box>
249          </Box>
250        ))}
251      </Box>
252    )
253  })
254}
255

1import type { DeskItem, Tag } from '../types'
2
3type Raw = {
4  id?: string
5  desk?: string
6  session?: string
7  kind?: string
8  status?: string
9  label?: string
10  via?: string
11  n?: number | null
12  payload?: { flow?: string; ns?: number[] }
13  at?: string
14  epoch?: number
15  taken_at?: string
16  taken_epoch?: number
17  running_at?: string
18  running_epoch?: number
19  closed_at?: string
20  report?: string
21}
22
23// deskstate.py's budgets: past them the desk itself reads the record as stale
24const BUDGET: Record<string, number> = {
25  preparing: 1800, queued: 1800, taken: 3600, running: 3600, 'needs-input': 86400,
26}
27const CLOSED = ['done', 'failed']
28const ISSUE_KINDS = ['issue-analyze', 'close']
29const ISSUE_FLOWS = ['issue-loop', 'issue-triage']
30
31export const OPEN = Object.keys(BUDGET)
32// a loop's numbers past these are on the desk, not in a one-line row
33const MAX_NS = 3
34const HHMM = /^(\d{2}:\d{2}):\d{2}$/
35
36export function tagOf(raw: Raw): Tag {
37  const flow = raw.payload?.flow ?? ''
38  return ISSUE_KINDS.includes(raw.kind ?? '') || ISSUE_FLOWS.includes(flow) ? 'ISSUE' : 'PR'
39}
40
41function startOf(raw: Raw): number {
42  if (raw.status === 'taken') return raw.taken_epoch ?? raw.epoch ?? 0
43  if (raw.status === 'running') return raw.running_epoch ?? raw.epoch ?? 0
44  return raw.epoch ?? 0
45}
46
47function labelOf(raw: Raw): string {
48  const flow = raw.payload?.flow
49  const ns = raw.payload?.ns ?? []
50  const shown = ns.slice(0, MAX_NS).map(n => `#${n}`).join(' ')
51  if (flow) return ns.length ? `${flow} ${shown}${ns.length > MAX_NS ? ` +${ns.length - MAX_NS}` : ''}` : flow
52  return raw.n != null ? `${raw.kind} #${raw.n}` : raw.label ?? raw.kind ?? '?'
53}
54
55function atOf(raw: Raw): string {
56  const at = raw.status === 'running' ? raw.running_at ?? raw.at
57    : raw.status === 'taken' ? raw.taken_at ?? raw.at
58    : CLOSED.includes(raw.status ?? '') ? raw.closed_at ?? raw.at : raw.at
59  return (at ?? '').replace(HHMM, '$1')
60}
61
62/** `2026-10-07 17:24`, the desk's local start, in epoch seconds; 0 when unreadable. */
63export const sinceEpoch = (since: string | undefined) => (Date.parse((since ?? '').replace(' ', 'T')) / 1000) || 0
64
65/** The chat-routed requests of one desk state file, live or just closed, of a desk still up:
66 *  a request of a desk since closed, or of one before the running desk, is gone with it. */
67export function itemsOf(repo: string, state: unknown, nowSec: number): DeskItem[] {
68  const s = state as { requests?: Record<string, Raw>; desks?: Record<string, DeskMark> } | null
69  const ledger = s?.requests ?? {}
70  const out: DeskItem[] = []
71  for (const [key, raw] of Object.entries(ledger)) {
72    if (!raw || raw.via !== 'chat-session') continue
73    const mark = s?.desks?.[raw.desk ?? 'pr']
74    if (!mark || mark.stopped || (raw.epoch ?? startOf(raw)) < sinceEpoch(mark.since)) continue
75    const status = raw.status ?? ''
76    const budget = BUDGET[status]
77    if (budget !== undefined && nowSec - startOf(raw) > budget) continue
78    if (budget === undefined && !CLOSED.includes(status)) continue
79    out.push({
80      key: `${repo} ${key}`, id: raw.id ?? `${repo} ${key} ${raw.epoch ?? 0}`, repo, session: raw.session ?? '', tag: tagOf(raw),
81      label: labelOf(raw), status, at: atOf(raw), report: raw.report ?? '',
82    })
83  }
84  return out
85}
86
87export const isOpen = (item: DeskItem) => OPEN.includes(item.status)
88
89/** The mod's poll is never somebody using the desk: it neither keeps it alive nor refreshes it. */
90export function pollHeaders(etag: string | null | undefined): Record<string, string> {
91  const headers: Record<string, string> = etag ? { 'If-None-Match': etag } : {}
92  headers['X-Git-Workflow-Background'] = '1'
93  return headers
94}
95
96/** A repository by its short name, unless another one in view shares it. */
97export function projectOf(repo: string, all: string[] = []): string {
98  const short = repo.split('/').pop() ?? repo
99  return all.some(other => other !== repo && other.split('/').pop() === short) ? repo : short
100}
101
102/** A request closed with ✕ stays closed, whatever it does next. */
103export const unclosed = (items: DeskItem[], closed: Record<string, number> = {}) =>
104  items.filter(i => !(i.id in closed))
105
106/** The closed requests worth remembering: past this age none of them can show again. */
107export const recentClosed = (closed: Record<string, number>, nowMs: number, keepMs: number) =>
108  Object.fromEntries(Object.entries(closed).filter(([, at]) => nowMs - at < keepMs))
109
110export function mentions(state: unknown, session: string): boolean {
111  const s = state as { chats?: Record<string, unknown>; requests?: Record<string, Raw> } | null
112  if (!s || !session) return false
113  if (s.chats && session in s.chats) return true
114  return Object.values(s.requests ?? {}).some(r => r?.session === session)
115}
116
117const WORD: Record<string, string> = {
118  preparing: 'il desk prepara', queued: 'in coda', taken: 'in chat ora',
119  running: 'in background', 'needs-input': 'aspetta te',
120  done: 'finito', failed: 'non riuscito',
121}
122
123export const wordOf = (status: string) => WORD[status] ?? status
124
125const short = (text: string, max: number) =>
126  text.length > max ? `${text.slice(0, max - 1)}…` : text
127
128/** One line per transition worth a toast: a loop now waits for you, or closed. */
129export function transitions(before: Record<string, string>, items: DeskItem[]): string[] {
130  const out: string[] = []
131  const repos = items.map(i => i.repo)
132  for (const item of items) {
133    const was = before[item.key]
134    if (was === undefined || was === item.status) continue
135    if (item.status === 'needs-input' || CLOSED.includes(item.status)) {
136      const report = item.report ? `: ${short(item.report, 80)}` : ''
137      out.push(`${item.tag} ${projectOf(item.repo, repos)} · ${item.label} ${wordOf(item.status)}${report}`)
138    }
139  }
140  return out
141}
142
143/** `PR ⏳1 ⏸1 · ISSUE ⏳1`: the loops at work and the ones waiting for you, per kind. */
144export function statusLine(items: DeskItem[]): string | undefined {
145  const open = items.filter(isOpen)
146  const parts: string[] = []
147  for (const tag of ['PR', 'ISSUE'] as const) {
148    const mine = open.filter(i => i.tag === tag)
149    const wait = mine.filter(i => i.status === 'needs-input').length
150    const busy = mine.length - wait
151    const words = [busy ? `⏳${busy}` : '', wait ? `⏸${wait}` : ''].filter(Boolean)
152    if (words.length) parts.push(`${tag} ${words.join(' ')}`)
153  }
154  return parts.length ? parts.join(' · ') : undefined
155}
156
157const GO = /^\s*(vai|ok|okay|si|sì|procedi|tutte vai|vai su tutte|go)\s*[.!]*\s*$/i
158
159export const bareGoAhead = (text: string) => GO.test(text)
160
161export const waiting = (items: DeskItem[]) => items.filter(i => i.status === 'needs-input')
162
163// deskstate.CHAT_STALE: a heartbeat older than this is no chat
164const CHAT_STALE = 45
165
166type DeskMark = { since?: string; stopped?: string }
167type Mark = { port?: number; stopped?: string }
168type Chat = { epoch?: number }
169export type StateFile = { mtime: number; state: unknown }
170export type Target = { port: number; repo: string; attached: boolean }
171
172export const repoOf = (fileName: string) => fileName.replace(/\.json$/, '').replace('__', '/')
173
174/** The desk this chat drives: the one it is attached to, else the one touched last.
175 *  `attached`: some chat listens to it, so the server has a chat to route a click to. */
176export function deskTarget(files: Record<string, StateFile>, session: string, nowSec: number): Target | null {
177  const found: (Target & { mine: boolean; mtime: number })[] = []
178  for (const [fileName, file] of Object.entries(files)) {
179    const s = file.state as { desks?: { pr?: Mark }; chats?: Record<string, Chat> } | null
180    const mark = s?.desks?.pr
181    if (!mark?.port || mark.stopped) continue
182    const chats = s?.chats ?? {}
183    found.push({ port: mark.port, repo: repoOf(fileName), mtime: file.mtime, mine: session in chats,
184                 attached: Object.values(chats).some(chat => nowSec - (chat.epoch ?? 0) <= CHAT_STALE) })
185  }
186  found.sort((a, b) => Number(b.mine) - Number(a.mine) || b.mtime - a.mtime)
187  const best = found[0]
188  return best ? { port: best.port, repo: best.repo, attached: best.attached } : null
189}
190

1export type Tag = 'PR' | 'ISSUE'
2
3export type DeskItem = {
4  key: string
5  id: string
6  repo: string
7  session: string
8  tag: Tag
9  label: string
10  status: string
11  at: string
12  report: string
13}
14
15export type Preparation = {
16  status: string
17  phrase: string
18  due: (number | string)[]
19  landed: (number | string)[]
20  failed: Record<string, string>
21  report?: string | null
22}
23
24export type Desk = { base: string; repo: string; attached: boolean }
25
26declare module 'claude-code' {
27  interface PluginState {
28    'git-workflow': {
29      items: DeskItem[]
30      desk: Desk | null
31    }
32  }
33}
34