brainstorm-board

1import type { Register } from 'claude-code'
2import { update } from 'claude-code'
3
4// The brainstorms the brainstorm skill recorded: each is a `brainstorm.md` in a
5// plan's folder, the project's own `.plans` first and the global plans after.
6// The list is shown first; a brainstorm opens as formatted text, with a button
7// back to the list. The chosen one is kept in $.state, so a redraw keeps it.
8// Toggled by `enabled` in settings.json pluginConfigs["brainstorm-board"].options.
9
10const PANE = 'brainstorm-board'
11const TOOL = 'show_brainstorm_board'
12const READ = 'read_brainstorm_board'
13const SCROLL = 'scroll_brainstorm_board'
14const pick = { plugin: 'brainstorm-board', key: 'pick' } as const
15
16type Entry = { dir: string; name: string; scope: 'project' | 'global'; mtimeMs: number; firstLine: string }
17
18// The part of `$.fs` the reading needs.
19type Fs = {
20  exists: (path: string) => Promise<boolean>
21  list: (path?: string) => Promise<{ name: string; kind: string }[]>
22  read: (path: string) => Promise<string>
23  stat: (path: string) => Promise<{ mtimeMs: number }>
24}
25
26type Line = { style: 'heading' | 'quote' | 'body' | 'blank'; text: string }
27
28// Inline markers the pane cannot draw are removed, so `**word**` reads as `word`.
29function plain(text: string): string {
30  return text
31    .replace(/\*\*(.+?)\*\*/g, '$1')
32    .replace(/__(.+?)__/g, '$1')
33    .replace(/`([^`]+)`/g, '$1')
34    .replace(/(^|\s)\*(\S[^*]*)\*/g, '$1$2')
35}
36
37// The Markdown of a brainstorm, line by line, with the planning skill's `§`
38// section numbers taken out, which a reader does not need.
39function markdownLines(markdown: string): Line[] {
40  return markdown
41    .split('\n')
42    .filter(raw => !raw.trimStart().startsWith('§'))
43    .map((raw): Line => {
44      const line = raw.trimEnd()
45      if (line.trim() === '') return { style: 'blank', text: '' }
46      if (/^\s*-{3,}\s*$/.test(line)) return { style: 'quote', text: '─'.repeat(24) }
47      const heading = /^#{1,6}\s+(.*)$/.exec(line)
48      if (heading) return { style: 'heading', text: plain(heading[1] ?? '') }
49      const task = /^(\s*)[-*]\s+\[( |x|X)\]\s+(.*)$/.exec(line)
50      if (task) {
51        const box = task[2] === ' ' ? '☐' : '☑'
52        return { style: 'body', text: `${task[1] ?? ''}${box} ${plain(task[3] ?? '')}` }
53      }
54      const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line)
55      if (bullet) return { style: 'body', text: `${bullet[1] ?? ''}• ${plain(bullet[2] ?? '')}` }
56      return { style: 'body', text: plain(line) }
57    })
58}
59
60// The first heading of a brainstorm, which names it; its folder name otherwise.
61function titleOf(markdown: string, fallback: string): string {
62  const heading = markdown.split('\n').find(line => /^#{1,6}\s+/.test(line))
63  return heading ? plain(heading.replace(/^#{1,6}\s+/, '').trim()) : fallback
64}
65
66// The brainstorms under one folder, most recently changed first.
67async function listBrainstorms(fs: Fs, base: string, scope: 'project' | 'global'): Promise<Entry[]> {
68  if (!(await fs.exists(base))) return []
69  const entries: Entry[] = []
70  for (const folder of await fs.list(base)) {
71    if (folder.kind !== 'dir') continue
72    const file = `${base}/${folder.name}/brainstorm.md`
73    if (!(await fs.exists(file))) continue
74    // A file that vanishes between the checks is skipped, not allowed to fail the list.
75    const text = await fs.read(file).catch(() => null)
76    const mtimeMs = await fs.stat(file).then(stat => stat.mtimeMs).catch(() => 0)
77    if (text === null) continue
78    entries.push({
79      dir: `${base}/${folder.name}`,
80      name: folder.name,
81      scope,
82      mtimeMs,
83      firstLine: titleOf(text, folder.name),
84    })
85  }
86  return entries.sort((a, b) => b.mtimeMs - a.mtimeMs)
87}
88
89// The redraw timer's cancel handle, kept so a re-registered session replaces the
90// timer rather than adding a second one.
91let tick: { cancel: () => void } | undefined
92
93export const register: Register = (on, options) => {
94  if (options.enabled === false) return
95
96  const plansDir = String(options.plansDir ?? '')
97
98  on('session.start', async ($, e, next) => {
99    await $.command.register({
100      name: 'brainstorm-board',
101      description: 'Show the brainstorms in a pane; `/brainstorm-board close` hides it',
102    })
103    await $.tool.register({
104      name: TOOL,
105      description:
106        'Show the brainstorms recorded for this project and the global plans, in a pane, and return the list as text for the chat.',
107      inputSchema: { type: 'object', properties: {} },
108    })
109    await $.tool.register({
110      name: READ,
111      description:
112        'Read which brainstorm the person has picked in the brainstorm board, and the brainstorms recorded, as text, without opening the pane.',
113      inputSchema: { type: 'object', properties: {} },
114    })
115    await $.tool.register({
116      name: SCROLL,
117      description:
118        'Scroll the brainstorm board to a paragraph of the brainstorm it shows, by words in that paragraph. Says when no line matches.',
119      inputSchema: {
120        type: 'object',
121        properties: { text: { type: 'string', description: 'Words in the paragraph to scroll to.' } },
122        required: ['text'],
123      },
124    })
125    // A brainstorm recorded while the pane is open shows up on the next redraw.
126    tick?.cancel()
127    tick = $.clock.every(5000, () => $.ui.invalidate('ui.render'))
128    return next(e)
129  })
130
131  on('command.run', { command: 'brainstorm-board' }, async ($, e) => {
132    if (e.args.trim().toLowerCase() === 'close') {
133      await $.ui.close({ id: PANE })
134      return { text: 'Brainstorm board closed.' }
135    }
136    await $.ui.open({ id: PANE, title: 'Brainstorms' })
137
138    return { text: 'Brainstorm board opened.' }
139  })
140
141  // The agent's way to show the board. It opens the pane and returns the list.
142  on('tool.call', { tool: `mcp__brainstorm-board__${TOOL}` }, async $ => {
143    const home = (await $.env.get('HOME')) ?? ''
144    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
145    const project = await $.session.root()
146    const global = plansDir || `${xdg || `${home}/.config`}/tsch-ai-skills/plans`
147    const fs: Fs = {
148      exists: path => $.fs.exists(path),
149      list: path => $.fs.list(path),
150      read: path => $.fs.read(path),
151      stat: path => $.fs.stat(path),
152    }
153    const all = [
154      ...(await listBrainstorms(fs, `${project}/.plans`, 'project')),
155      ...(await listBrainstorms(fs, global, 'global')),
156    ]
157    await $.ui.open({ id: PANE, title: 'Brainstorms' })
158
159    const listed = all.map(entry => `${entry.scope}: ${entry.firstLine} (${entry.name})`)
160    return {
161      result: [
162        all.length === 0 ? 'No brainstorms recorded.' : 'Brainstorms recorded:',
163        ...listed,
164      ].join('\n'),
165    }
166  })
167
168  // The agent's way to move the board to a paragraph of the picked brainstorm: the
169  // first drawn line holding the words. Keys match the reading view's lines.
170  on('tool.call', { tool: `mcp__brainstorm-board__${SCROLL}` }, async ($, e) => {
171    const home = (await $.env.get('HOME')) ?? ''
172    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
173    const project = await $.session.root()
174    const global = plansDir || `${xdg || `${home}/.config`}/tsch-ai-skills/plans`
175    const fs: Fs = {
176      exists: path => $.fs.exists(path),
177      list: path => $.fs.list(path),
178      read: path => $.fs.read(path),
179      stat: path => $.fs.stat(path),
180    }
181    const { value: chosenDir } = await $.state.get(pick)
182    const all = [
183      ...(await listBrainstorms(fs, `${project}/.plans`, 'project')),
184      ...(await listBrainstorms(fs, global, 'global')),
185    ]
186    const chosen = all.find(entry => entry.dir === chosenDir)
187    if (!chosen) return { result: 'No brainstorm is picked in the board.' }
188    const text = await fs.read(`${chosen.dir}/brainstorm.md`).catch(() => null)
189    if (text === null) return { result: 'The picked brainstorm could not be read.' }
190
191    const wanted = String(e.text ?? '').trim().toLowerCase()
192    const drawn = markdownLines(text)
193    const index = drawn.findIndex(line => line.style !== 'blank' && line.text.toLowerCase().includes(wanted))
194    if (index < 0) return { result: `Nothing matching "${wanted}" in the brainstorm.` }
195    await $.ui.open({ id: PANE, title: 'Brainstorms', focus: true })
196    await $.ui.scroll({ to: { key: `brainstorm-${index}` }, in: PANE, block: 'start' })
197    return { result: `Scrolled to "${drawn[index]?.text ?? ''}".` }
198  })
199
200  // The agent's read of the board's pick: the brainstorm the person chose, its
201  // file, and the list. Read-only; the pane is not opened.
202  on('tool.call', { tool: `mcp__brainstorm-board__${READ}` }, async $ => {
203    const home = (await $.env.get('HOME')) ?? ''
204    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
205    const project = await $.session.root()
206    const global = plansDir || `${xdg || `${home}/.config`}/tsch-ai-skills/plans`
207    const fs: Fs = {
208      exists: path => $.fs.exists(path),
209      list: path => $.fs.list(path),
210      read: path => $.fs.read(path),
211      stat: path => $.fs.stat(path),
212    }
213    const { value: chosenDir } = await $.state.get(pick)
214    const all = [
215      ...(await listBrainstorms(fs, `${project}/.plans`, 'project')),
216      ...(await listBrainstorms(fs, global, 'global')),
217    ]
218    const chosen = all.find(entry => entry.dir === chosenDir)
219    const lines = [
220      chosen ? 'Picked in the board: one brainstorm' : 'Picked in the board: none (the list is shown)',
221      `Brainstorms recorded: ${all.length}`,
222      ...all.map(entry => `${entry.scope}: ${entry.firstLine} (${entry.name})`),
223    ]
224    if (chosen) lines.push(`Picked: ${chosen.scope}: ${chosen.firstLine}`, `File: ${chosen.dir}/brainstorm.md`)
225    const live = await $.ui.selection().catch(() => undefined)
226    lines.push(`Highlighted in the board: ${live?.text ?? 'none'}`)
227    return { result: lines.join('\n') }
228  })
229
230  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
231    const { Box, Button, Text } = $.ui.resolve(e)
232    const rendered = (markdown: string) =>
233      markdownLines(markdown).map((line, index) => {
234        const key = `brainstorm-${index}`
235        if (line.style === 'blank') return <Box key={key}><Text> </Text></Box>
236        if (line.style === 'heading')
237          return (
238            <Box key={key}>
239              <Text bold underline color="cyan">
240                {line.text}
241              </Text>
242            </Box>
243          )
244        if (line.style === 'quote') return <Box key={key}><Text dimColor>{line.text}</Text></Box>
245        return <Box key={key}><Text>{line.text}</Text></Box>
246      })
247
248    const home = (await $.env.get('HOME')) ?? ''
249    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
250    const project = await $.session.root()
251    const global = plansDir || `${xdg || `${home}/.config`}/tsch-ai-skills/plans`
252    const fs: Fs = {
253      exists: path => $.fs.exists(path),
254      list: path => $.fs.list(path),
255      read: path => $.fs.read(path),
256      stat: path => $.fs.stat(path),
257    }
258    const { value: chosenDir } = await $.state.get(pick)
259    const all = [
260      ...(await listBrainstorms(fs, `${project}/.plans`, 'project')),
261      ...(await listBrainstorms(fs, global, 'global')),
262    ]
263    const chosen = all.find(entry => entry.dir === chosenDir)
264    // A file removed between the listing and this read is treated as missing, so
265    // the pane shows the list instead of drawing nothing.
266    const text = chosen ? await fs.read(`${chosen.dir}/brainstorm.md`).catch(() => null) : null
267
268    return (
269      <Box flexDirection="column">
270        <Box flexDirection="row" justifyContent="space-between">
271          <Text bold inverse>
272            Brainstorms
273          </Text>
274          <Button role="dismiss" onPress={() => $.ui.close({ id: PANE })}>
275            Close
276          </Button>
277        </Box>
278        <Text> </Text>
279        {chosen && text !== null ? (
280          <Box flexDirection="column">
281            <Button variant="primary" onPress={() => update($, pick, () => null)}>
282              back to brainstorms
283            </Button>
284            <Text dimColor>{`${chosen.scope} plan: ${chosen.name}`}</Text>
285            <Text> </Text>
286            {rendered(text)}
287          </Box>
288        ) : (
289          <Box flexDirection="column">
290            {all.length === 0 && <Text dimColor>No brainstorms recorded yet.</Text>}
291            {all.map(entry => (
292              <Button
293                key={entry.dir}
294                onPress={() => update($, pick, () => entry.dir)}
295              >
296                {`${entry.scope}: ${entry.firstLine}  (${entry.name})`}
297              </Button>
298            ))}
299          </Box>
300        )}
301      </Box>
302    )
303  })
304}
305

1// The brainstorm the board shows, by its folder. Null means the list.
2declare module 'claude-code' {
3  interface PluginState {
4    'brainstorm-board': { pick: string | null }  }
5}
6