idea-shelf

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import type { Idea } from '../types'
5import { addIdea, count, editIdea, hideIdea, preview, readShelf, removeIdea, sentIn, shelfKey } from './shelf'
6import type { Changed } from './shelf'
7import { STORE_KEY, storedSwitch, switchText, switchWord } from './toggle'
8
9const PANE = 'idea-shelf'
10// The switch as this session read it (toggle.ts). Off, every hook passes its event on unchanged and /idea parks
11// nothing; the ideas stay in the store. The mod starts off; `/idea-shelf on` turns it on for every session.
12const enabled = atom({ plugin: 'idea-shelf', key: 'enabled' } as const, false)
13const ideas = atom({ plugin: 'idea-shelf', key: 'ideas' } as const, [] as Idea[])
14const notice = atom({ plugin: 'idea-shelf', key: 'notice' } as const, null as string | null)
15const editing = atom({ plugin: 'idea-shelf', key: 'editing' } as const, null as string | null)
16
17// The project's shelf and what this session knows about the prompt box. `handed`: ideas Send put in the prompt
18// box, taken off the shelf once a prompt that carries them is submitted. `isBusy`: a turn of the main loop runs.
19type Session = { key: string; handed: Set<string>; isBusy: boolean }
20
21// Reads this project's shelf from the store into the session's state, which the drawings read.
22async function load($: any, s: Session): Promise<void> {
23  s.key = shelfKey(await $.session.root())
24  const list = readShelf(await $.store.get(s.key).catch(() => undefined))
25  await update($, ideas, () => list)
26}
27
28// Applies a change: the store keeps the shelf past the session, the state redraws the band and the shelf.
29async function apply($: any, s: Session, changed: Changed): Promise<string> {
30  if ('error' in changed) {
31    await update($, notice, () => changed.error)
32    return changed.error
33  }
34  await $.store.set(s.key, changed.ideas)
35  await update($, ideas, () => changed.ideas)
36  await update($, notice, () => changed.said)
37  return changed.said
38}
39
40// Sends one idea. With the prompt box empty and Claude idle it goes as a prompt; otherwise it is put in the box,
41// after what is already there, and the rest is left to you. Either way it leaves the shelf once it is submitted.
42async function send($: any, s: Session, idea: Idea): Promise<void> {
43  const box = await $.prompt.read()
44  s.handed.add(idea.id)
45  if (box.text.trim() === '' && !s.isBusy) {
46    await $.prompt.submit({ text: idea.text })
47    await apply($, s, removeIdea(await read($, ideas), idea.id))
48    await update($, notice, () => 'sent as a prompt')
49    return
50  }
51  const text = box.text.trim() === '' ? idea.text : `${box.text.replace(/\s+$/, '')}\n${idea.text}`
52  const filled = await $.prompt.fill({ text, mode: 'replace' })
53  await update($, notice, () => (filled.isFilled ? 'put in the prompt box: press Enter there to send it' : 'the prompt box could not take it now'))
54}
55
56async function park($: any, s: Session, text: string): Promise<string> {
57  return apply($, s, addIdea(await read($, ideas), text, await $.clock.now()))
58}
59
60async function change($: any, s: Session, id: string, text: string): Promise<void> {
61  await apply($, s, editIdea(await read($, ideas), id, text))
62  await update($, editing, () => null)
63}
64
65async function drop($: any, s: Session, id: string): Promise<void> {
66  await apply($, s, removeIdea(await read($, ideas), id))
67}
68
69// A conversation row with every text block passed through hideIdea; the same row when nothing changed.
70function withIdeaHidden<E extends { message: { content: { type: string; [field: string]: unknown }[] } }>(e: E): E {
71  let isChanged = false
72  const content = e.message.content.map(block => {
73    if (block.type !== 'text' || typeof block.text !== 'string') return block
74    const text = hideIdea(block.text)
75    if (text === block.text) return block
76    isChanged = true
77    return { ...block, text }
78  })
79  return isChanged ? { ...e, message: { ...e.message, content } } : e
80}
81
82async function openShelf($: any): Promise<void> {
83  await update($, notice, () => null)
84  // Panes draw only in the terminal and the desktop app; elsewhere the command's line is the answer.
85  await $.ui.open({ id: PANE, title: 'Idea shelf', focus: true, closeOnEscape: true }).catch(() => undefined)
86}
87
88export const register: Register = on => {
89  const s: Session = { key: '', handed: new Set(), isBusy: false }
90
91  on('session.start', async ($, e, next) => {
92    // Registered even when the mod is off, so that it can be turned on. `immediate`: /idea parks an idea while
93    // Claude is working, without waiting for the turn to end and without interrupting it.
94    await $.command
95      .register({ name: 'idea', description: 'Park an idea for later without interrupting Claude (/idea alone opens the shelf)', argumentHint: '[<idea>|list]', immediate: true })
96      .catch(() => undefined)
97    await $.command
98      .register({ name: 'idea-shelf', description: "Switch the idea shelf on or off, or show how many ideas this project's shelf holds", argumentHint: '[on|off|status]', immediate: true })
99      .catch(() => undefined)
100    const isOn = storedSwitch(await $.store.get(STORE_KEY).catch(() => undefined), false)
101    await update($, enabled, () => isOn)
102    if (isOn) await load($, s)
103    return next(e)
104  })
105
106  on('command.run', { command: 'idea-shelf' }, async ($, e) => {
107    const word = switchWord(e.args)
108    if (word === undefined) return { text: 'use /idea-shelf on, /idea-shelf off or /idea-shelf status' }
109    if (word === 'status') {
110      if (!(await read($, enabled))) return { text: switchText('idea-shelf', false) }
111      return { text: `${switchText('idea-shelf', true)} · ${count((await read($, ideas)).length)} on this project's shelf` }
112    }
113    const isOn = word === 'on'
114    await $.store.set(STORE_KEY, isOn)
115    await update($, enabled, () => isOn)
116    if (isOn) await load($, s)
117    return { text: switchText('idea-shelf', isOn) }
118  })
119
120  // The command's line is part of the conversation, so it says what happened and never repeats the idea.
121  on('command.run', { command: 'idea' }, async ($, e) => {
122    if (!(await read($, enabled))) return { text: switchText('idea-shelf', false) }
123    const text = e.args.trim()
124    if (text === '' || text.toLowerCase() === 'list') {
125      await openShelf($)
126      return { text: `${count((await read($, ideas)).length)} on this project's shelf` }
127    }
128    return { text: await park($, s, text) }
129  })
130
131  // The /idea row in the conversation would carry the idea to the model; it keeps a stand-in instead (shelf.ts).
132  // The row is rewritten before it is stored, so neither the model nor the transcript file reads the idea there.
133  // If the hook fails, the stand-in still goes in: a failure never lets the idea through.
134  on('session.append', { door: 'command' }, async ($, e, next) => {
135    if (!(await read($, enabled))) return next(e)
136    return next(withIdeaHidden(e))
137  }).catch(($, e, next) => (next.called ? next(e) : next(withIdeaHidden(e))))
138
139  on('turn.start', async ($, e, next) => {
140    if (await read($, enabled)) s.isBusy = true
141    return next(e)
142  })
143
144  on('turn.complete', async ($, e, next) => {
145    if (e.agentId === undefined) s.isBusy = false
146    return next(e)
147  })
148
149  // An idea Send put in the prompt box leaves the shelf when the prompt that carries it is submitted.
150  on('prompt.submit', async ($, e, next) => {
151    if (!(await read($, enabled)) || s.handed.size === 0) return next(e)
152    const sent = sentIn(await read($, ideas), s.handed, e.text)
153    for (const id of sent) {
154      s.handed.delete(id)
155      await apply($, s, removeIdea(await read($, ideas), id))
156    }
157    return next(e)
158  }).catch(($, e, next) => next(e))
159
160  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
161    const below = await next(e)
162    if (!(await read($, enabled))) return below
163    const list = await read($, ideas)
164    if (e.props.hasSurvey || list.length === 0) return below
165    const { Box, Button, Text } = $.ui.resolve(e)
166    return (
167      <Box flexDirection="column">
168        <Box>
169          <Text dimColor wrap="truncate">{`ideas ▸ ${count(list.length)} parked `}</Text>
170          <Button key="shelf" label="Shelf" hotkey="i" onPress={() => openShelf($)} />
171        </Box>
172        {below}
173      </Box>
174    )
175  })
176
177  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
178    const ui = $.ui.resolve(e)
179    const { Box, Button, Text } = ui
180    // Mobile draws no text field: there the shelf lists, sends and deletes, and /idea parks.
181    const Input = 'Input' in ui ? ui.Input : undefined
182    if (!(await read($, enabled))) return <Text dimColor>{switchText('idea-shelf', false)}</Text>
183    const list = await read($, ideas)
184    const said = await read($, notice)
185    const open = await read($, editing)
186    const width = Math.max(10, e.props.bodyColumns - 26)
187    return (
188      <Box flexDirection="column">
189        <Text bold>{`Idea shelf · ${count(list.length)} for this project`}</Text>
190        {Input !== undefined && (
191          <Input key="new" label="New idea: " placeholder="type it, Enter parks it" submitLabel="park" autoFocus onSubmit={(value: string) => void park($, s, value)} />
192        )}
193        {said !== null && <Text dimColor>{said}</Text>}
194        {list.length === 0 && <Text dimColor>Nothing parked yet. /idea text parks one from the prompt, even while Claude works.</Text>}
195        {list.map(idea =>
196          open === idea.id && Input !== undefined ? (
197            <Input key={`text-${idea.id}`} label="Edit: " value={idea.text} submitLabel="save" onSubmit={(value: string) => void change($, s, idea.id, value)} />
198          ) : (
199            <Box key={`row-${idea.id}`}>
200              <Text wrap="truncate">{`${preview(idea.text, width)} `}</Text>
201              <Button key={`send-${idea.id}`} label="Send" onPress={() => send($, s, idea)} />
202              <Button key={`edit-${idea.id}`} label="Edit" onPress={() => update($, editing, () => idea.id)} />
203              <Button key={`delete-${idea.id}`} label="Delete" onPress={() => drop($, s, idea.id)} />
204            </Box>
205          ),
206        )}
207      </Box>
208    )
209  })
210}
211

1// The idea shelf's pure parts: one list of ideas per project, kept in the plugin's store, with limits on how
2// many ideas and how long each may be.
3import type { Idea } from '../types'
4
5export const MAX_IDEAS = 200
6export const MAX_CHARS = 2000
7
8// The store is one per plugin, shared by every folder, so a project's shelf lives under a key made from the
9// project's root folder. A Windows path is compared without regard to case or separator.
10export function shelfKey(root: string): string {
11  const path = root.split('\\').join('/').replace(/\/+$/, '')
12  return `shelf:${/^[A-Za-z]:\//.test(path) ? path.toLowerCase() : path}`
13}
14
15// What the store holds, as a list of ideas; anything else (nothing yet, a hand-edited file) is an empty shelf.
16export function readShelf(value: unknown): Idea[] {
17  if (!Array.isArray(value)) return []
18  return value.filter(
19    (i): i is Idea => i !== null && typeof i === 'object' && typeof i.id === 'string' && typeof i.text === 'string' && typeof i.at === 'number',
20  )
21}
22
23// A shelf after a change, or why the change was refused.
24export type Changed = { ideas: Idea[]; said: string } | { error: string }
25
26export function addIdea(ideas: readonly Idea[], text: string, at: number): Changed {
27  const clean = text.trim()
28  if (clean === '') return { error: 'nothing to park: type the idea after /idea, or in the shelf' }
29  if (clean.length > MAX_CHARS) return { error: `too long to park: ${clean.length} characters, at most ${MAX_CHARS}` }
30  if (ideas.length >= MAX_IDEAS) return { error: `the shelf holds ${MAX_IDEAS} ideas; send or delete one first` }
31  // Unique within the shelf even when two ideas are parked in the same millisecond.
32  let n = ideas.length
33  while (ideas.some(i => i.id === `${at}-${n}`)) n++
34  const list = [...ideas, { id: `${at}-${n}`, text: clean, at }]
35  return { ideas: list, said: `parked (${list.length} on the shelf)` }
36}
37
38export function editIdea(ideas: readonly Idea[], id: string, text: string): Changed {
39  const clean = text.trim()
40  if (clean === '') return removeIdea(ideas, id)
41  if (clean.length > MAX_CHARS) return { error: `too long: ${clean.length} characters, at most ${MAX_CHARS}` }
42  if (!ideas.some(i => i.id === id)) return { error: 'that idea is no longer on the shelf' }
43  return { ideas: ideas.map(i => (i.id === id ? { ...i, text: clean } : i)), said: 'idea changed' }
44}
45
46export function removeIdea(ideas: readonly Idea[], id: string): Changed {
47  const list = ideas.filter(i => i.id !== id)
48  return { ideas: list, said: list.length === ideas.length ? 'that idea is no longer on the shelf' : `deleted (${list.length} on the shelf)` }
49}
50
51// The ideas a submitted prompt carried: those Send put in the prompt box whose whole text is in the prompt.
52export function sentIn(ideas: readonly Idea[], handed: ReadonlySet<string>, prompt: string): string[] {
53  return ideas.filter(i => handed.has(i.id) && prompt.includes(i.text)).map(i => i.id)
54}
55
56// The first line of an idea, cut to fit a row.
57export function preview(text: string, width: number): string {
58  const first = text.split('\n')[0] ?? ''
59  const room = Math.max(8, width)
60  const line = first.length > room ? `${first.slice(0, room - 1)}…` : first
61  return text.includes('\n') && line === first ? `${line} …` : line
62}
63
64export const count = (n: number) => `${n} idea${n === 1 ? '' : 's'}`
65
66// The row a slash command leaves in the conversation names the command and what was typed after it, and the
67// model reads that row. For /idea that is the idea itself, so the shelf puts a stand-in there: the model reads
68// that an idea was parked, never which. /idea alone and /idea list carry no idea and stay as typed.
69export const KEPT_ARGS = '(an idea, kept on the shelf)'
70const IDEA_ROW = /<command-name>\/(?:[\w-]+:)?idea<\/command-name>/
71const ARGS = /<command-args>([\s\S]*?)<\/command-args>/
72
73export function hideIdea(text: string): string {
74  if (!IDEA_ROW.test(text)) return text
75  return text.replace(ARGS, (whole, args: string) => {
76    const typed = args.trim().toLowerCase()
77    return typed === '' || typed === 'list' ? whole : `<command-args>${KEPT_ARGS}</command-args>`
78  })
79}
80

1// The mod's on/off switch, `/<mod> on|off|status`. The value is kept in $.store under STORE_KEY: one store per
2// plugin, shared by every session and folder, so the switch holds across restarts. A session reads it as it
3// starts and when its own command changes it; a session already open elsewhere picks a change up when it next
4// starts. Pure helpers only: `claude plugin validate` follows `$` only within the file that uses it.
5export const STORE_KEY = 'enabled'
6
7export type SwitchWord = 'on' | 'off' | 'status'
8
9// The command's argument as a switch word: '' and 'status' ask, 'on' and 'off' set; anything else is the mod's own.
10export function switchWord(args: string | undefined): SwitchWord | undefined {
11  const word = (args ?? '').trim().toLowerCase()
12  if (word === '' || word === 'status') return 'status'
13  return word === 'on' || word === 'off' ? word : undefined
14}
15
16// The stored value, or the mod's default when it was never set (or holds something else).
17export function storedSwitch(value: unknown, byDefault: boolean): boolean {
18  return typeof value === 'boolean' ? value : byDefault
19}
20
21export function switchText(mod: string, isOn: boolean): string {
22  return isOn ? `on (/${mod} off turns it off)` : `off (/${mod} on turns it on)`
23}
24

1// One idea on a project's shelf: its text as typed, and when it was parked.
2export type Idea = { id: string; text: string; at: number }
3
4declare module 'claude-code' {
5  interface PluginState {
6    // enabled: the mod's on/off switch as this session read it from the store, or as /idea-shelf on|off set it.
7    // ideas: this project's shelf, as the store holds it. notice: what the last action did, shown in the shelf.
8    // editing: the idea whose text is open for editing in the shelf, by id.
9    'idea-shelf': { enabled: boolean; ideas: Idea[]; notice: string | null; editing: string | null }
10  }
11}
12