tui-hint-board

1import type { Register } from 'claude-code'
2import { update } from 'claude-code'
3
4// The terminal-program profiles the interactive-shell skill ships and the agent
5// has written (appprofiles/*.md): the list is shown first, and a profile opens
6// as formatted text with a button back to the list. The chosen profile is kept
7// in $.state. Toggled by `enabled` in settings.json pluginConfigs["tui-hint-board"].options.
8
9const PANE = 'tui-hint-board'
10const TOOL = 'show_tui_profiles'
11const READ = 'read_tui_hint_board'
12const OPEN = 'open_tui_profile'
13const SECTION = 'scroll_tui_profile'
14const profile = { plugin: 'tui-hint-board', key: 'profile' } as const
15const filter = { plugin: 'tui-hint-board', key: 'filter' } as const
16
17type Fs = {
18  exists: (path: string) => Promise<boolean>
19  list: (path?: string) => Promise<{ name: string; kind: string }[]>
20  read: (path: string) => Promise<string>
21}
22
23// Inline markers the pane cannot draw are removed.
24function plain(text: string): string {
25  return text
26    .replace(/\*\*(.+?)\*\*/g, '$1')
27    .replace(/__(.+?)__/g, '$1')
28    .replace(/`([^`]+)`/g, '$1')
29}
30
31// The profile's Markdown, line by line: headings, table rows left as text, and
32// bullets as `•`.
33function lines(markdown: string): { style: 'heading' | 'body' | 'blank' | 'divider'; text: string }[] {
34  return markdown.split('\n').map(raw => {
35    const line = raw.trimEnd()
36    if (line.trim() === '') return { style: 'blank' as const, text: '' }
37    // Longer than any pane; the pane cuts it at its own edge.
38    if (/^\s*-{3,}\s*$/.test(line)) return { style: 'divider' as const, text: '─'.repeat(400) }
39    const heading = /^#{1,6}\s+(.*)$/.exec(line)
40    if (heading) return { style: 'heading' as const, text: plain(heading[1] ?? '') }
41    const bullet = /^(\s*)[-*]\s+(.*)$/.exec(line)
42    if (bullet) return { style: 'body' as const, text: `${bullet[1] ?? ''}• ${plain(bullet[2] ?? '')}` }
43    return { style: 'body' as const, text: plain(line) }
44  })
45}
46
47// Whether a profile name matches the filter the person typed: any case, any part of the name.
48function matches(name: string, query: string): boolean {
49  return name.toLowerCase().includes(query.trim().toLowerCase())
50}
51
52// A profile the board lists, with every folder it is written in: the agent's own
53// notes (appprofiles.d) and the shipped one (appprofiles). One name, one entry.
54type Profile = { name: string; dirs: string[] }
55
56// The profile names the board lists: the shipped profiles and the agent's own.
57async function listProfiles(fs: Fs, dirs: string[]): Promise<Profile[]> {
58  const found: Profile[] = []
59  for (const dir of dirs) {
60    if (!(await fs.exists(dir))) continue
61    for (const entry of await fs.list(dir)) {
62      if (entry.kind === 'file' && entry.name.endsWith('.md') && entry.name !== 'FORMAT.md') {
63        const name = entry.name.replace(/\.md$/, '')
64        const known = found.find(item => item.name === name)
65        if (known) known.dirs.push(dir)
66        else found.push({ name, dirs: [dir] })
67      }
68    }
69  }
70  return found.sort((a, b) => a.name.localeCompare(b.name))
71}
72
73// A profile's text: the shipped text, with the agent's notes for this system appended
74// under their own heading, so system-specific knowledge extends the seeded one.
75async function bodyOf(fs: Fs, item: Profile): Promise<string | null> {
76  let shippedText: string | null = null
77  let ownText: string | null = null
78  for (const dir of item.dirs) {
79    const text = await fs.read(`${dir}/${item.name}.md`).catch(() => null)
80    if (text === null) continue
81    // The marker line tells the reader the file is a profile; the board does not show it.
82    const body = text.replace(/^<!--[^\n]*-->\n?/, '').trim()
83    if (dir.endsWith('appprofiles.d')) ownText = body
84    else shippedText = body
85  }
86  if (shippedText !== null && ownText !== null) {
87    return `${shippedText}\n\n---\n\n## Added for this system\n\n${ownText}`
88  }
89  return shippedText ?? ownText
90}
91
92export const register: Register = (on, options) => {
93  if (options.enabled === false) return
94
95  on('session.start', async ($, e, next) => {
96    await $.command.register({
97      name: 'tui-hint-board',
98      description: 'Show the terminal-program profiles the agent has in a pane; `/tui-hint-board close` hides it',
99    })
100    await $.tool.register({
101      name: TOOL,
102      description: 'Show the terminal-program profiles the agent knows, in a pane, and return their names as text.',
103      inputSchema: { type: 'object', properties: {} },
104    })
105    await $.tool.register({
106      name: READ,
107      description: 'Read which terminal program profile the person has picked in the board, as text, without opening the pane.',
108      inputSchema: { type: 'object', properties: {} },
109    })
110    await $.tool.register({
111      name: SECTION,
112      description:
113        'Scroll the open profile in the board to one of its titled sections, by part of the section title (e.g. "Keys", "Added for this system"). Lists the section titles when none matches.',
114      inputSchema: {
115        type: 'object',
116        properties: { section: { type: 'string', description: 'Part of the section title to scroll to.' } },
117        required: ['section'],
118      },
119    })
120    await $.tool.register({
121      name: OPEN,
122      description:
123        'Open one terminal program profile in the board for the person to read, by its name (its file name without .md). Shows the shipped text with any notes for this system under "Added for this system".',
124      inputSchema: {
125        type: 'object',
126        properties: { name: { type: 'string', description: 'The profile name, e.g. less or lldb.' } },
127        required: ['name'],
128      },
129    })
130    return next(e)
131  })
132
133  on('command.run', { command: 'tui-hint-board' }, async ($, e) => {
134    if (e.args.trim().toLowerCase() === 'close') {
135      await $.ui.close({ id: PANE })
136      return { text: 'TUI hint board closed.' }
137    }
138    await $.ui.open({ id: PANE, title: 'Terminal program profiles', focus: true })
139    return { text: 'TUI hint board opened.' }
140  })
141
142  on('tool.call', { tool: `mcp__tui-hint-board__${TOOL}` }, async $ => {
143    const home = (await $.env.get('HOME')) ?? ''
144    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
145    const fs: Fs = {
146      exists: path => $.fs.exists(path),
147      list: path => $.fs.list(path),
148      read: path => $.fs.read(path),
149    }
150    const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
151    const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
152    const names = await listProfiles(fs, [own, shipped])
153    await $.ui.open({ id: PANE, title: 'Terminal program profiles', focus: true })
154
155    return {
156      result: [
157        names.length === 0 ? 'No terminal program profiles yet.' : 'Terminal program profiles:',
158        ...names.map(item => item.name),
159      ].join('\n'),
160    }
161  })
162
163  // The agent's way to move the open profile to one of its sections: the section is
164  // the first heading whose title contains the words given. The reading view keys each
165  // heading, so the scroll lands it at the top of the pane.
166  on('tool.call', { tool: `mcp__tui-hint-board__${SECTION}` }, async ($, e) => {
167    const home = (await $.env.get('HOME')) ?? ''
168    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
169    const fs: Fs = {
170      exists: path => $.fs.exists(path),
171      list: path => $.fs.list(path),
172      read: path => $.fs.read(path),
173    }
174    const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
175    const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
176    const everyone = await listProfiles(fs, [own, shipped])
177    const { value: picked } = await $.state.get(profile)
178    const chosen = everyone.find(item => item.name === picked)
179    const text = chosen ? await bodyOf(fs, chosen) : null
180    if (!chosen || text === null) {
181      return { result: 'No profile is open in the board. Open one first with open_tui_profile.' }
182    }
183    const headings = lines(text)
184      .map((line, index) => ({ line, index }))
185      .filter(item => item.line.style === 'heading')
186    const wanted = String(e.section ?? '').trim().toLowerCase()
187    const found = headings.find(item => item.line.text.toLowerCase().includes(wanted))
188    if (!found) {
189      return { result: `No section matching "${wanted}". Sections: ${headings.map(item => item.line.text).join(', ')}` }
190    }
191    await $.ui.open({ id: PANE, title: 'Terminal program profiles', focus: true })
192    await $.ui.scroll({ to: { key: `section-${found.index}` }, in: PANE, block: 'start' })
193    return { result: `Scrolled ${chosen.name} to "${found.line.text}".` }
194  })
195
196  // The agent's way to open a profile for the person: the board picks it and opens
197  // the pane, so the reading view shows it with the notes for this system.
198  on('tool.call', { tool: `mcp__tui-hint-board__${OPEN}` }, async ($, e) => {
199    const home = (await $.env.get('HOME')) ?? ''
200    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
201    const fs: Fs = {
202      exists: path => $.fs.exists(path),
203      list: path => $.fs.list(path),
204      read: path => $.fs.read(path),
205    }
206    const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
207    const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
208    const names = await listProfiles(fs, [own, shipped])
209    const wanted = String(e.name ?? '').trim()
210    const found = names.find(item => item.name === wanted)
211    if (!found) {
212      return { result: `No profile named "${wanted}". Profiles: ${names.map(item => item.name).join(', ')}` }
213    }
214    await update($, profile, () => found.name)
215    await $.ui.open({ id: PANE, title: 'Terminal program profiles', focus: true })
216    return { result: `Opened the ${found.name} profile in the board.` }
217  })
218
219  // The agent's read of the board's pick: the profile the person chose, or none.
220  // Read-only; the pane is not opened.
221  on('tool.call', { tool: `mcp__tui-hint-board__${READ}` }, async $ => {
222    const home = (await $.env.get('HOME')) ?? ''
223    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
224    const fs: Fs = {
225      exists: path => $.fs.exists(path),
226      list: path => $.fs.list(path),
227      read: path => $.fs.read(path),
228    }
229    const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
230    const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
231    const names = await listProfiles(fs, [own, shipped])
232    const { value: picked } = await $.state.get(profile)
233    const chosen = names.find(item => item.name === picked)
234    const lines = [
235      chosen ? `Picked in the board: ${chosen.name}` : 'Picked in the board: none (the list is shown)',
236      `Profiles available: ${names.length}`,
237    ]
238    if (chosen) lines.push(`Files: ${chosen.dirs.map(dir => `${dir}/${chosen.name}.md`).join(', ')}`)
239    // The text the person has highlighted in the pane, when they have: a part of the profile.
240    const live = await $.ui.selection().catch(() => undefined)
241    lines.push(`Highlighted in the board: ${live?.text ?? 'none'}`)
242    return { result: lines.join('\n') }
243  })
244
245  // The ring moving onto one of the last three profiles scrolls the list so the
246  // profile two below it sits at the bottom: the focused one stays third from the
247  // bottom, and the list moves up one with each step until the end of the list.
248  on('ui.focus', { requestId: PANE }, async ($, e, next) => {
249    if (e.component === 'Pane' && e.element !== undefined) {
250      const home = (await $.env.get('HOME')) ?? ''
251      const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
252      const fs: Fs = {
253        exists: path => $.fs.exists(path),
254        list: path => $.fs.list(path),
255        read: path => $.fs.read(path),
256      }
257      const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
258      const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
259      const { value: query } = await $.state.get(filter)
260      const names = (await listProfiles(fs, [own, shipped])).filter(item => matches(item.name, query ?? ''))
261      const index = names.findIndex(item => item.name === e.element)
262      const last = names.length - 1
263      if (index >= 0 && index >= last - 2) {
264        const target = names[Math.min(index + 2, last)]
265        if (target) await $.ui.scroll({ to: { key: target.name }, in: PANE, block: 'end' })
266      }
267    }
268    return next(e)
269  })
270
271  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
272    const { Box, Button, Input, Text } = $.ui.resolve(e)
273    const home = (await $.env.get('HOME')) ?? ''
274    const xdg = (await $.env.get('XDG_CONFIG_HOME')) ?? ''
275    const fs: Fs = {
276      exists: path => $.fs.exists(path),
277      list: path => $.fs.list(path),
278      read: path => $.fs.read(path),
279    }
280    const shipped = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles`
281    const own = `${xdg || `${home}/.config`}/tsch-ai-skills/appprofiles.d`
282    const everyone = await listProfiles(fs, [own, shipped])
283    const { value: picked } = await $.state.get(profile)
284    const { value: query } = await $.state.get(filter)
285    const names = everyone.filter(item => matches(item.name, query ?? ''))
286    const chosen = everyone.find(item => item.name === picked)
287    const text = chosen ? await bodyOf(fs, chosen) : null
288
289    return (
290      <Box flexDirection="column">
291        <Box flexDirection="row" justifyContent="space-between">
292          <Text bold inverse>
293            Terminal program profiles
294          </Text>
295        </Box>
296        {!(chosen && text !== null) && (
297          <Input key="profile-filter" label="filter: " placeholder="type a program name" onSubmit={text => update($, filter, () => text)} />
298        )}
299        {!(chosen && text !== null) && !!query?.trim() && (
300          <Box flexDirection="row">
301            <Text>Active filter: </Text>
302            <Text inverse color="cyan">{` ${query.trim()} `}</Text>
303            <Text> </Text>
304            <Button variant="primary" onPress={() => update($, filter, () => '')}>clear filter</Button>
305          </Box>
306        )}
307        <Text> </Text>
308        {chosen && text !== null ? (
309          <Box flexDirection="column">
310            <Button variant="primary" autoFocus onPress={() => update($, profile, () => null)}>
311              back to profiles
312            </Button>
313            <Text dimColor>
314              {chosen.dirs.length > 1
315                ? 'shipped profile, with your notes for this system'
316                : chosen.dirs[0]?.endsWith('appprofiles.d')
317                  ? 'your own profile'
318                  : 'shipped profile'}
319            </Text>
320            <Text> </Text>
321            {lines(text).map((line, index) =>
322              line.style === 'blank' ? (
323                <Text key={index}> </Text>
324              ) : line.style === 'divider' ? (
325                <Text key={index} dimColor wrap="truncate">
326                  {line.text}
327                </Text>
328              ) : line.style === 'heading' ? (
329                <Box key={`section-${index}`}>
330                  <Text bold underline color="cyan">
331                    {line.text}
332                  </Text>
333                </Box>
334              ) : (
335                <Text key={index}>{line.text}</Text>
336              ),
337            )}
338          </Box>
339        ) : (
340          <Box flexDirection="column">
341            {names.length === 0 && <Text dimColor>No terminal program profiles yet.</Text>}
342            {names.map((item, index) => (
343              <Button
344                key={item.name}
345                autoFocus={index === 0 || undefined}
346                onPress={() => update($, profile, () => item.name)}
347              >
348                {item.name}
349              </Button>
350            ))}
351          </Box>
352        )}
353        <Text> </Text>
354        <Button role="dismiss" onPress={() => $.ui.close({ id: PANE })}>
355          Close
356        </Button>
357      </Box>
358    )
359  })
360}
361

1// The profile the board shows, by its file name without `.md`. Null means the list.
2declare module 'claude-code' {
3  interface PluginState {
4    'tui-hint-board': { profile: string | null; filter: string }
5  }
6}
7