done-widget

1import { atom, read, update } from 'claude-code'
2import type { Elements, EngineInterface, Register, RenderElement, RenderSurface } from 'claude-code'
3import type { WidgetsPlace } from 'widgets'
4
5import { fit, plural } from './lib'
6
7type Tags = Pick<Elements[RenderSurface], 'Box' | 'Text'>
8type Item = { text: string; evidence: string }
9type List = { items: Item[]; isDue: boolean; nudges: number }
10type Tick = { item?: unknown; evidence?: unknown }
11
12const PANE = 'widgets'
13const CARD_COLUMNS = 40
14const LONG_COLUMNS = 36
15const MAX_ITEMS = 6
16const MAX_TEXT = 80
17const MAX_EVIDENCE = 120
18const MAX_ECHO = 20
19const USAGE = 'Usage: /done-widget [on|off|add <criterion>|drop <number>|show|clear]'
20const OFF = 'Done is off.'
21const OPENING =
22  "done-widget: the user's definition of done for this task. Tick each item with the tick tool as you meet it, giving the evidence that proves it, and do not call the work finished while any is open:"
23const EMPTY = ['No definition of done yet.', '/done-widget add the tests pass', 'Claude ticks each with its evidence.'] as const
24const NAMED = /\b(done list|definition of done|done-widget)\b/g
25const NUMBERED = /\bitems?\s+#?\d+((\s*,\s*|\s*&\s*|\s+and\s+|\s+or\s+)#?\d+)*/g
26const ALL_BUT = /\b(?:everything|all)\s+but\b/g
27const SENTENCE = /(?<=[.!?\n])/
28const CLAUSE = /[.,;:!?\n]|\s[-–—]\s|\b(?:but|and|though|although|however|while|so(?!\s+far\b))\b/
29const ASKED = /\?[^\p{L}\p{N}]*$/u
30const FAILURES = /\b(?!0+\b)\d+\s+(?:fail\w*|errors?)\b/g
31const REPORTED = '\u0000'
32const WHOLE = String.raw`(?:finished|completed|done\s+with|finished\s+with)(?:\s+(?:implementing|building|writing))?\s+(?:everything|it\s+all|all\s+of\s+it|all\s+(?:of\s+)?the\s+work|(?:the|this|that)\s+(?:whole\s+|entire\s+)?(?:work|task|job|refactor|refactoring|implementation|migration|rewrite|changes?|fix|feature|update))`
33const CLOSED = String.raw`(?:\s+(?:now|here|too|already|as\s+well|for\s+you|as\s+requested|as\s+asked|as\s+planned|successfully|correctly|properly|fully|entirely))*[^\p{L}\p{N}]*$`
34const CLAIM = new RegExp(String.raw`\b(?:done|finished|complete|completed|fixed|resolved|all\s+set|${WHOLE})${CLOSED}`, 'u')
35const RAN = new RegExp(
36  String.raw`(?:\b(?:tests?|test\s+runs?|suites?|builds?|runs?|commands?|installs?|downloads?|compiles?|scripts?)(?:['’]s|(?:\s+(?:is|are|was|were|has|have|had|been|just|now|also|all))*)\s+|\x60\s*|\b(?:bun|npm|npx|pnpm|yarn|node|deno|tsc|eslint|prettier|vitest|jest|pytest|cargo|go|make|git|docker|pip)\s+)(?:done|finished|complete|completed)${CLOSED}`,
37  'u',
38)
39const HEDGED =
40  /\b(?:not|never|no|nothing|none|nor|cannot|without|except|far\s+from|nowhere\s+near|yet\s+to|so\s+far|almost|nearly|mostly|mainly|largely|partly|partially|half|still|remaining|remains?|open|once|until|when|if|before|after|will|to\s+be|needs?|needed)\b|n['’]t\b/
41const ONE_ITEM = /\bitems?\b/
42const EVERY_ITEM = /\b(?:all|every|each)\s+(?:of\s+)?(?:the\s+)?(?:(?:\d+|two|three|four|five|six)\s+)?items?\b/
43const BLANK: List = { items: [], isDue: false, nudges: 0 }
44const site = { plugin: 'widgets', key: 'site' } as const
45const widths = { plugin: 'widgets', key: 'widths' } as const
46const isOn = atom({ plugin: 'done-widget', key: 'isOn' } as const, false)
47const list = atom({ plugin: 'done-widget', key: 'list' } as const, BLANK)
48
49const clean = (typed: string, most: number): string => typed.replaceAll(/\s+/g, ' ').trim().slice(0, most)
50
51const listed = (items: readonly Item[]): string =>
52  items.map(({ text, evidence }, at) => (evidence === '' ? `${at + 1}. [ ] ${text}` : `${at + 1}. [x] ${text} (${evidence})`)).join('\n')
53
54const wrapped = (sentence: string, columns: number): string[] =>
55  sentence.split(' ').reduce<string[]>((rows, word) => {
56    const last = rows.at(-1)
57
58    return last !== undefined && last.length + 1 + word.length <= columns ? [...rows.slice(0, -1), `${last} ${word}`] : [...rows, word]
59  }, [])
60
61const unmet = (items: readonly Item[]): number[] => items.flatMap(({ evidence }, at) => (evidence === '' ? [at + 1] : []))
62
63const reported = (sentence: string): string => {
64  const at = [...sentence.matchAll(FAILURES)].at(-1)?.index
65
66  return at === undefined ? sentence : `${sentence.slice(0, at).replaceAll(':', `${REPORTED}:`)}${sentence.slice(at)}`
67}
68
69const claims = (answer: string, items: readonly Item[]): boolean =>
70  items
71    .reduce((said, { text }) => said.replaceAll(text.toLowerCase(), ' '), answer.toLowerCase())
72    .replaceAll(NAMED, ' ')
73    .replaceAll(NUMBERED, 'item')
74    .replaceAll(ALL_BUT, 'except')
75    .split(SENTENCE)
76    .filter(sentence => !ASKED.test(sentence))
77    .flatMap(sentence => reported(sentence).split(CLAUSE))
78    .some(
79      clause =>
80        !clause.endsWith(REPORTED) &&
81        CLAIM.test(clause) &&
82        !HEDGED.test(clause) &&
83        (!ONE_ITEM.test(clause) || EVERY_ITEM.test(clause)) &&
84        !RAN.test(clause),
85    )
86
87const answer = (said: string, isError = false) => (isError ? { result: said, text: said, isError } : { result: said, text: said })
88
89const show = async (
90  $: EngineInterface,
91  { Box, Text }: Tags,
92  beneath: RenderElement,
93  place: WidgetsPlace,
94  columns: number,
95): Promise<RenderElement> => {
96  if (!(await read($, isOn))) return beneath
97  if ((await $.state.get(site)).value !== place) return beneath
98
99  const width = fit((await $.state.get(widths)).value?.['done-widget'] ?? CARD_COLUMNS, columns)
100  const inner = width - 4
101  const isLong = inner >= LONG_COLUMNS
102  const { items, nudges } = await read($, list)
103  const met = items.length - unmet(items).length
104
105  return $.widgets.card({
106    beneath,
107    width,
108    title: 'Done',
109    note: items.length === 0 ? '' : met === items.length ? 'all met' : `${met}/${items.length} met`,
110    body:
111      items.length === 0 ? (
112        <Box flexDirection="column">
113          {EMPTY.flatMap(sentence => wrapped(sentence, inner)).map(row => (
114            <Text dimColor>{row}</Text>
115          ))}
116        </Box>
117      ) : (
118        <Box flexDirection="column">
119          {items.flatMap(({ text, evidence }, at) => [
120            <Text key={`item-${at + 1}`} wrap="truncate-end">
121              {evidence === '' ? <Text color="yellow">·</Text> : <Text color="green">✓</Text>} {at + 1} {text}
122            </Text>,
123            ...(evidence === ''
124              ? []
125              : [
126                  <Text key={`evidence-${at + 1}`} dimColor wrap="truncate-end">
127                    {`    ${evidence}`}
128                  </Text>,
129                ]),
130          ])}
131          {nudges > 0 && (
132            <Text key="nudges" color="yellow" wrap="truncate-end">
133              {isLong ? `Said done too soon: ${plural(nudges, 'nudge')}` : plural(nudges, 'nudge')}
134            </Text>
135          )}
136        </Box>
137      ),
138  })
139}
140
141const offer = async ($: EngineInterface): Promise<void> => {
142  await $.tool.register({
143    name: 'tick',
144    description:
145      "Tick one item on the user's definition of done, with evidence. The user keeps a checklist of what finished means for this task; you are told it with a prompt. When you have met an item and verified it, call this with its number and what proves it: the command you ran and its result, or the file and line. Tick only what you have verified. Do not tell the user the work is finished while items are open: say which are open and why.",
146    inputSchema: {
147      type: 'object',
148      properties: {
149        item: { type: 'number', description: 'The number of the item on the checklist.' },
150        evidence: { type: 'string', description: 'What proves it: the command you ran and its result, or the file and line.' },
151      },
152      required: ['item', 'evidence'],
153    },
154  })
155}
156
157export const register: Register = on => {
158  on('session.start', async ($, e, next) => {
159    await $.command.register({
160      name: 'done-widget',
161      description: 'Toggle the definition of done that Claude ticks with evidence',
162      argumentHint: '[on|off|add <criterion>|drop <number>|show|clear]',
163    })
164    if ((await $.store.get('isOn')) === true) {
165      await update($, isOn, () => true)
166      await offer($)
167    }
168
169    return next(e)
170  })
171
172  on('command.run', { command: 'done-widget' }, async ($, e) => {
173    const typed = e.args.trim()
174    const [verb = ''] = typed.split(/\s+/)
175    const arg = verb.toLowerCase()
176    const rest = typed.slice(verb.length).trim()
177
178    if (arg === 'add' || arg === 'drop' || ((arg === 'show' || arg === 'clear') && rest === '')) {
179      if (!(await read($, isOn))) return { text: OFF }
180
181      const held = await read($, list)
182      const { items } = held
183      if (arg === 'show') {
184        if (items.length === 0) return { text: 'The definition of done is empty. /done-widget add <criterion> adds an item.' }
185
186        return {
187          text: [
188            `${plural(items.length, 'item')}, ${items.length - unmet(items).length} met:`,
189            listed(items),
190            ...(held.nudges > 0 ? [`Said done too soon: ${plural(held.nudges, 'nudge')}`] : []),
191          ].join('\n'),
192        }
193      }
194      if (arg === 'clear') {
195        await update($, list, () => BLANK)
196
197        return { text: 'Done list cleared.' }
198      }
199      if (arg === 'add') {
200        const text = clean(rest, MAX_TEXT)
201        if (text === '') return { text: 'Add what? Try /done-widget add the tests pass' }
202
203        const same = items.findIndex(item => item.text.toLowerCase() === text.toLowerCase())
204        if (same >= 0) return { text: `Already on the list as item ${same + 1}.` }
205        if (items.length >= MAX_ITEMS) {
206          return { text: `The list is full (${plural(MAX_ITEMS, 'item')}). /done-widget drop <number> makes room.` }
207        }
208        await update($, list, () => ({ ...held, items: [...items, { text, evidence: '' }], isDue: true }))
209
210        return { text: `Item ${items.length + 1}: done when ${text}. Claude is told with your next prompt.` }
211      }
212
213      const at = /^\d+$/.test(rest) ? Number(rest) : 0
214      const dropped = items[at - 1]
215      if (dropped === undefined) return { text: `There is no item "${rest.slice(0, MAX_ECHO)}". /done-widget show lists them.` }
216      await update($, list, () => ({ ...held, items: items.filter((_, index) => index !== at - 1), isDue: true }))
217
218      return { text: `Dropped item ${at}: ${dropped.text}` }
219    }
220    if (rest !== '' || (arg !== '' && arg !== 'on' && arg !== 'off')) return { text: USAGE }
221
222    const isShown = await update($, isOn, shown => (arg === '' ? !(shown ?? false) : arg === 'on'))
223    await $.store.set('isOn', isShown)
224    if (isShown) {
225      await update($, list, held => ({ ...(held ?? BLANK), isDue: true }))
226      await offer($)
227    }
228
229    return {
230      text: isShown
231        ? 'Done on; /done-widget add <criterion> writes the list. /widgets places it.'
232        : 'Done off. The tick tool stays listed until the session ends and ticks nothing.',
233    }
234  })
235
236  on('tool.call', { tool: 'mcp__done-widget__tick' }, async ($, e) => {
237    if (!(await read($, isOn))) return answer('Done is off; nothing was ticked.', true)
238
239    const held = await read($, list)
240    const { items } = held
241    if (items.length === 0) return answer('The definition of done is empty; there is nothing to tick.', true)
242
243    const tick = e as Tick
244    const at = tick.item
245    if (typeof at !== 'number' || !Number.isInteger(at) || at < 1 || at > items.length) {
246      return answer(`There is no item ${at === undefined ? '(none given)' : String(at).slice(0, MAX_ECHO)}. The list:\n${listed(items)}`, true)
247    }
248
249    const evidence = clean(String(tick.evidence ?? ''), MAX_EVIDENCE)
250    if (evidence === '') return answer(`Item ${at} needs evidence: the command you ran and its result, or the file and line.`, true)
251
252    const ticked = items.map((item, index) => (index + 1 === at ? { ...item, evidence } : item))
253    await update($, list, () => ({ ...held, items: ticked }))
254    const open = unmet(ticked)
255
256    return answer(`${listed(ticked)}\n${open.length === 0 ? 'Every item is met.' : `Still open: ${open.join(', ')}.`}`)
257  })
258
259  on('prompt.submit', async ($, e, next) => {
260    if (!(await read($, isOn))) return next(e)
261    if (e.origin.kind !== 'composer' && e.origin.kind !== 'bridge' && e.origin.kind !== 'sdk') return next(e)
262
263    const held = await read($, list)
264    if (!held.isDue || held.items.length === 0) return next(e)
265
266    await update($, list, now => ({ ...(now ?? held), isDue: false }))
267
268    return next({ ...e, context: [...(e.context ?? []), `${OPENING}\n${listed(held.items)}`] })
269  })
270
271  on('turn.complete', async ($, e, next) => {
272    const ended = await next(e)
273    if (!(await read($, isOn)) || e.agentId !== undefined || e.isAborted || e.reason !== 'answer') return ended
274
275    const { items } = await read($, list)
276    const open = unmet(items)
277    if (open.length === 0 || !claims(e.answer, items)) return ended
278
279    await update($, list, held => ({ ...(held ?? BLANK), nudges: (held?.nudges ?? 0) + 1 }))
280    try {
281      await $.prompt.suggest({
282        text:
283          open.length === 1
284            ? `Item ${open[0]} on the done list is still open. Meet it and tick it with evidence, or say why not.`
285            : `Items ${open.join(', ')} on the done list are still open. Meet them and tick them with evidence, or say why not.`,
286      })
287    } catch {
288      return ended
289    }
290
291    return ended
292  })
293
294  on('session.compact', async ($, e, next) => {
295    const result = await next(e)
296    if ((await read($, isOn)) && e.agentId === undefined && e.trigger !== 'precompute' && result.skip === undefined) {
297      await update($, list, held => ({ ...(held ?? BLANK), isDue: true }))
298    }
299
300    return result
301  })
302
303  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e, next) =>
304    show($, $.ui.resolve(e), await next(e), 'side', e.props.bodyColumns),
305  )
306
307  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) =>
308    e.props.hasSurvey ? next(e) : show($, $.ui.resolve(e), await next(e), 'above', e.props.bodyColumns),
309  )
310
311  on('ui.render', { component: 'PromptHint' }, async ($, e, next) =>
312    show($, $.ui.resolve(e), await next(e), 'below', e.viewport?.columns ?? 80),
313  )
314}
315

1const MIN_CARD = 20
2const BARS = '▁▂▃▄▅▆▇█'
3
4export const fit = (wanted: number, columns: number): number => Math.min(wanted, Math.max(MIN_CARD, columns))
5
6export const plural = (count: number, word: string): string => `${count} ${word}${count === 1 ? '' : 's'}`
7
8export const span = (ms: number): string => {
9  const seconds = Math.max(0, Math.round(ms / 1000))
10  if (seconds < 60) return `${seconds}s`
11  const minutes = Math.floor(seconds / 60)
12  if (minutes < 60) return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`
13  const hours = Math.floor(minutes / 60)
14  if (hours < 24) return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`
15
16  return `${Math.floor(hours / 24)}d ${hours % 24}h`
17}
18
19export const spark = (values: readonly number[], width: number): string => {
20  const shown = width > 0 ? values.slice(-width) : []
21  const top = Math.max(...shown, 0)
22
23  return shown
24    .map(value => (top <= 0 ? BARS[0] : BARS[Math.min(BARS.length - 1, Math.round((Math.max(0, value) / top) * (BARS.length - 1)))]))
25    .join('')
26}
27
28export const hash = (text: string): number => {
29  let held = 2166136261
30  for (const letter of text) held = Math.imul(held ^ (letter.codePointAt(0) ?? 0), 16777619)
31
32  return held >>> 0
33}
34
35export const shade = (color: number, factor: number): number =>
36  (Math.round((color >> 16) * factor) << 16) |
37  (Math.round(((color >> 8) & 255) * factor) << 8) |
38  Math.round((color & 255) * factor)
39
40export const folder = (path: string): string => {
41  const flat = path.replaceAll('\\', '/').replace(/\/+$/, '')
42
43  return /^[a-z]:/i.test(flat) ? flat.toLowerCase() : flat
44}
45

1export type DoneSwitch = boolean
2
3declare module 'claude-code' {
4  interface PluginState {
5    'done-widget': {
6      isOn: DoneSwitch
7      list: { items: { text: string; evidence: string }[]; isDue: boolean; nudges: number }
8    }
9  }
10}
11