htui

1// htui's mod: a band above the prompt when something waits on you, a /htui
2// command, and a pane. It reads htui's state only by running `htui ... --json`
3// (docs/htui-cli.md) and never writes anything of htui's.
4import { atom, read, update } from 'claude-code'
5import type { EngineInterface, Register, Timer } from 'claude-code'
6import type { HtuiRow, HtuiWaiting } from '../types'
7import { VERSION } from './version'
8
9const waiting = atom({ plugin: 'htui', key: 'waiting' } as const, null as HtuiWaiting | null)
10const skew = atom({ plugin: 'htui', key: 'skew' } as const, null as string | null)
11const active = atom({ plugin: 'htui', key: 'active' } as const, false as boolean)
12
13/** What one run of `htui` came to: its document and exit code, or the line that says why there is none. */
14type Ran = { ok: true; doc: any; exitCode: number } | { ok: false; line: string }
15
16/** The line for an answer the mod cannot read. */
17const unreadable = (exitCode: number): string => `htui: unreadable answer (exit ${exitCode})`
18
19/** A count as htui prints one: a whole number, not negative (V3). */
20const isCount = (v: unknown): v is number => Number.isSafeInteger(v) && (v as number) >= 0
21
22/** A JSON object: not null, not a list. */
23const isObject = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
24
25/** The pane's id, and the requestId its `ui.render` carries. */
26const PANE = 'htui'
27
28/** `42s`, `5m`, `3h`, `2d`: the largest whole unit, as htui's own text output. */
29const age = (s: number): string =>
30  s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86400)}d`
31
32/**
33 * `s` as a string with its control characters dropped, as htui's own text output drops them
34 * (`state_cmd.rs`'s `clean`): stored text must not drive the terminal, nor break a one-line row.
35 */
36const clean = (s: unknown): string => String(s ?? '').replace(/\p{Cc}/gu, '')
37
38/** A row's reason as the overlay names it: `judge_failed` reads `judge failed`. */
39const label = (reason: string): string => reason.replace(/_/g, ' ')
40
41/** Cuts `s` to `columns` characters, a trailing `…` marking the cut. */
42const fit = (s: string, columns: number): string => {
43  const chars = Array.from(s)
44  return chars.length <= columns ? s : chars.slice(0, Math.max(0, columns - 1)).join('') + '…'
45}
46
47/**
48 * One pane row: reason, item, step and age in columns of 13, 10, 16 and 4, then the text, cut to
49 * the pane's width. A value as wide as its column or wider still ends in one space (V4).
50 */
51const rowLine = (r: HtuiRow, columns: number): string =>
52  fit(
53    `${label(r.reason).padEnd(12)} ${r.item_key.padEnd(9)} ${(r.step ?? '-').padEnd(15)} ${age(r.age_seconds).padStart(4)}  ${r.text}`,
54    columns,
55  )
56
57/** Runs `htui` and reads its JSON answer. Never throws: every failure is a line. */
58async function runHtui($: EngineInterface, argv: readonly string[], timeoutMs: number): Promise<Ran> {
59  const started = await $.clock.now()
60  let r
61  try {
62    r = await $.process.run(argv, { timeoutMs })
63  } catch {
64    const elapsed = (await $.clock.now()) - started
65    return { ok: false, line: elapsed >= timeoutMs ? 'htui: timed out' : 'htui: not found on PATH' }
66  }
67  if (r.stdout.trim() === '') return { ok: false, line: `htui printed nothing (exit ${r.exitCode})` }
68  let doc: any
69  try {
70    doc = JSON.parse(r.stdout)
71  } catch {
72    doc = undefined
73  }
74  if (!isObject(doc)) return { ok: false, line: unreadable(r.exitCode) }
75  if (typeof doc.version === 'number' && doc.version > 1) {
76    return {
77      ok: false,
78      line: `htui: answer version ${doc.version} is newer than this plugin: run htui claude emit --force, then /reload-plugins`,
79    }
80  }
81  if (typeof doc.error?.message === 'string') return { ok: false, line: `htui: ${clean(doc.error.message)}` }
82  if (r.exitCode !== 0) return { ok: false, line: `htui: exit ${r.exitCode}` }
83  return { ok: true, doc, exitCode: r.exitCode }
84}
85
86/**
87 * The rows of a `waiting` document, reduced to the fields the mod reads and stripped of control
88 * characters; an entry that is not an object (a list included) is left out.
89 */
90const rowsOf = (rows: readonly unknown[]): HtuiRow[] =>
91  rows
92    .filter(isObject)
93    .map((r: any) => ({
94      reason: clean(r.reason),
95      item_key: clean(r.item_key),
96      step: typeof r.step === 'string' ? clean(r.step) : null,
97      text: clean(r.text),
98      age_seconds: Math.max(0, Math.floor(Number(r.age_seconds) || 0)),
99    }))
100
101/**
102 * A `waiting` run's rows and workspace name; a document whose `rows` is not a list is unreadable,
103 * so that no count is shown that htui did not give (V3).
104 */
105function waitingOf(ran: Ran): { ok: true; rows: HtuiRow[]; workspace: string | null } | { ok: false; line: string } {
106  if (!ran.ok) return ran
107  if (!Array.isArray(ran.doc.rows)) return { ok: false, line: unreadable(ran.exitCode) }
108  return { ok: true, rows: rowsOf(ran.doc.rows), workspace: ran.doc.workspace ? clean(ran.doc.workspace.name) : null }
109}
110
111/** `/htui waiting`'s text, one line per row. */
112const waitingText = (rows: readonly HtuiRow[]): string =>
113  rows.length === 0
114    ? 'Nothing waits on you.'
115    : rows.map(r => `${r.item_key}  ${label(r.reason)}  ${r.step ?? '-'}  ${age(r.age_seconds)}  ${r.text}`).join('\n')
116
117/** `/htui status`'s text: the top bar's line, a note when permissions are unknown, then the skew line. */
118async function statusText($: EngineInterface): Promise<string> {
119  const ran = await runHtui($, ['htui', 'status', '--json'], 10000)
120  const lines: string[] = []
121  if (ran.ok && !(isCount(ran.doc.working) && isCount(ran.doc.waiting))) {
122    lines.push(unreadable(ran.exitCode))
123  } else if (ran.ok) {
124    const d = ran.doc
125    lines.push(
126      `${d.workspace ? clean(d.workspace.name) : 'no workspace'} · ${d.box ? clean(d.box.hostname) : 'no box'} · ${clean(d.store)} · ${d.working} working · ${d.waiting} waiting`,
127    )
128    if (d.permissions_known === false) lines.push('permission requests could not be listed; the count may be low')
129  } else {
130    lines.push(ran.line)
131  }
132  const s = await read($, skew)
133  if (s !== null) lines.push(s)
134  return lines.join('\n')
135}
136
137/** `/htui search <query>`'s text, one line per hit. The query rides inside one argument (A-6). */
138async function searchText($: EngineInterface, query: string): Promise<string> {
139  const ran = await runHtui($, ['htui', `--search-items=${query}`, '--json'], 60000)
140  if (!ran.ok) return ran.line
141  if (ran.doc.index === 'empty') return 'No concepts index yet: run htui --index-items.'
142  const hits: any[] = Array.isArray(ran.doc.hits) ? ran.doc.hits.filter(isObject) : []
143  if (hits.length === 0) return 'No hits.'
144  return hits
145    .map(
146      h =>
147        `${clean(h.key)}  ${clean(h.place)}${h.document_kind ? ' ' + clean(h.document_kind) : ''}${h.resolution ? ' (' + clean(h.resolution) + ')' : ''}  ${clean(h.snippet)}`,
148    )
149    .join('\n')
150}
151
152/** `auto`, `command` or `off` (D12), as `register` read it from the options. */
153let panel: 'auto' | 'command' | 'off' = 'auto'
154/** The poll period: `poll_seconds` clamped to [5, 3600]; 0 or a non-number reads as 30 (A-12). */
155let periodMs = 30000
156/** `poll_seconds` as a period in seconds: 0 or a non-number is 30; else clamped to [5, 3600]. */
157const pollSeconds = (v: unknown): number =>
158  typeof v !== 'number' || Number.isNaN(v) || v === 0 ? 30 : Math.min(3600, Math.max(5, v))
159/** The poll timer while one runs; a module reload drops it. */
160let timer: Timer | null = null
161/** Set while a poll runs, so a slow poll is never overlapped by the next tick. */
162let polling = false
163
164/** One `htui waiting` poll into `waiting`; a failure replaces the rows, never keeps them. */
165async function poll($: EngineInterface): Promise<void> {
166  if (polling) return
167  polling = true
168  try {
169    const got = waitingOf(await runHtui($, ['htui', 'waiting', '--json'], 10000))
170    const at = await $.clock.now()
171    const next: HtuiWaiting = got.ok
172      ? { rows: got.rows, workspace: got.workspace, at, error: null }
173      : { rows: [], workspace: null, at, error: got.line }
174    await update($, waiting, () => next)
175  } catch {
176    // The module unloaded mid-poll (its `$` is gone): nothing is left to show.
177  } finally {
178    polling = false
179  }
180}
181
182/** Whether the engine lists the `htui` pane as open (A-4), or null when it cannot say. */
183async function paneOpen($: EngineInterface): Promise<boolean | null> {
184  try {
185    return (await $.ui.panes()).some(p => p.id === PANE)
186  } catch {
187    return null
188  }
189}
190
191/** One period: under `command`, stops the timer once the pane is closed; otherwise polls. */
192async function tick($: EngineInterface): Promise<void> {
193  if (panel === 'command') {
194    const isOpen = await paneOpen($)
195    if (isOpen === null) return
196    if (!isOpen) {
197      timer?.cancel()
198      timer = null
199      return
200    }
201  }
202  await poll($)
203}
204
205/** V2: under `command`, a pane that stayed open across a reload polls again, as /htui would. */
206async function resume($: EngineInterface): Promise<void> {
207  if ((await paneOpen($)) !== true) return
208  void poll($)
209  startTimer($)
210}
211
212/** Starts the poll timer unless one runs. */
213function startTimer($: EngineInterface): void {
214  if (timer !== null) return
215  timer = $.clock.every(periodMs, () => void tick($))
216}
217
218/**
219 * D14: names a binary whose version is not the plugin's. Every run writes `skew`,
220 * because `$.state` outlives a reload: after `emit --force` and `/reload-plugins`
221 * the line an earlier check set must go. A failure writes null; the poll reports it.
222 */
223async function checkVersion($: EngineInterface): Promise<void> {
224  let line: string | null = null
225  try {
226    const r = await $.process.run(['htui', '--version'], { timeoutMs: 10000 })
227    // The version is htui-supplied text like any other: stripped of control characters (F7c).
228    const bin = r.exitCode === 0 ? clean(/^htui (\S+)/m.exec(r.stdout)?.[1]) : ''
229    if (bin !== '' && bin !== VERSION) {
230      line = `htui ${bin} ≠ plugin ${VERSION}: run htui claude emit --force, then /reload-plugins`
231    }
232  } catch {
233    // Not on PATH or timed out: the poll reports that.
234  }
235  try {
236    await update($, skew, () => line)
237  } catch {
238    // The module unloaded mid-check (its `$` is gone): nothing is left to show.
239  }
240}
241
242export const register: Register = (on, options) => {
243  panel = options.panel === 'command' || options.panel === 'off' ? options.panel : 'auto'
244  periodMs = pollSeconds(options.poll_seconds) * 1000
245  timer = null
246  polling = false
247
248  on('session.start', async ($, e, next) => {
249    if ((await $.env.get('HTUI_SESSION')) !== undefined) return next(e)
250    await $.command.register({
251      name: 'htui',
252      description: 'htui: what waits on you, status, item search',
253      argumentHint: '[status|waiting|search <query>]',
254    })
255    await update($, active, () => true)
256    void checkVersion($)
257    if (panel === 'auto') {
258      void poll($)
259      startTimer($)
260    } else if (panel === 'command') {
261      void resume($)
262    }
263    return next(e)
264  })
265
266  on('command.run', { command: 'htui' }, async ($, e) => {
267    // D15: a session htui drives never registers /htui; should the command reach the hook anyway,
268    // it runs nothing. Still no `next` (A-2): the hook answers its own command.
269    if (!(await read($, active))) return { text: 'htui: stands down in sessions htui drives' }
270    const args = e.args.trim()
271    const space = args.search(/\s/)
272    const verb = space === -1 ? args : args.slice(0, space)
273    const rest = space === -1 ? '' : args.slice(space).trim()
274
275    if (verb === '' && panel !== 'off') {
276      const o = await $.ui.open({ id: PANE, title: 'htui' })
277      void poll($)
278      startTimer($)
279      return o.isPlaced ? {} : { text: `htui: the pane waits: ${o.reason}` }
280    }
281    if (verb === '' || verb === 'waiting') {
282      const got = waitingOf(await runHtui($, ['htui', 'waiting', '--json'], 10000))
283      return { text: got.ok ? waitingText(got.rows) : got.line }
284    }
285    if (verb === 'status') return { text: await statusText($) }
286    if (verb === 'search') {
287      return { text: rest === '' ? 'usage: /htui search <query>' : await searchText($, rest) }
288    }
289    return { text: 'usage: /htui [status|waiting|search <query>]' }
290  })
291
292  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
293    if (panel !== 'auto' || e.props.hasSurvey || !(await read($, active))) return next(e)
294    const w = await read($, waiting)
295    const s = await read($, skew)
296    const n = w?.rows.length ?? 0
297    const error = w?.error ?? null
298    if (n === 0 && error === null && s === null) return next(e)
299    const { Box, Text } = $.ui.resolve(e)
300    return (
301      <Box key="htui-band" flexDirection="column">
302        {n > 0 && <Text wrap="truncate">{`htui: ${n} waiting on you`}</Text>}
303        {s !== null && <Text wrap="truncate">{s}</Text>}
304        {error !== null && (
305          <Text dimColor wrap="truncate">
306            {error}
307          </Text>
308        )}
309      </Box>
310    )
311  })
312
313  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
314    const w = await read($, waiting)
315    const s = await read($, skew)
316    const columns = e.props.bodyColumns
317    const rows = w?.rows ?? []
318    // V1: before the first answer, or after a failed poll, no count is known: the header says only
319    // `htui`, and the line beneath says why.
320    const header = w === null || w.error !== null ? 'htui' : `${w.workspace ?? 'no workspace'} · ${rows.length} waiting`
321    const { Box, Text } = $.ui.resolve(e)
322    return (
323      <Box key="htui-pane" flexDirection="column">
324        <Text bold wrap="truncate">
325          {header}
326        </Text>
327        {s !== null && <Text wrap="truncate">{s}</Text>}
328        {w?.error != null && (
329          <Text dimColor wrap="truncate">
330            {w.error}
331          </Text>
332        )}
333        {rows.map((r, i) => (
334          <Box key={`row-${i}`}>
335            <Text wrap="truncate">{rowLine(r, columns)}</Text>
336          </Box>
337        ))}
338        {w === null && <Text dimColor>htui: no answer yet</Text>}
339        {w !== null && w.error === null && rows.length === 0 && <Text dimColor>Nothing waits on you.</Text>}
340      </Box>
341    )
342  })
343}
344

1export const VERSION = '0.0.0-source'
2

1/** One row of `htui waiting --json` as the mod reads it (docs/htui-cli.md, "waiting"). Other fields are ignored. */
2export type HtuiRow = { reason: string; item_key: string; step: string | null; text: string; age_seconds: number }
3
4/** The last poll: its rows, or the visible line for a poll that failed (then `rows` is empty). */
5export type HtuiWaiting = {
6  rows: readonly HtuiRow[]
7  /** `workspace.name` as the top bar shows it, or null when the store has no workspace. */
8  workspace: string | null
9  /** `$.clock.now()` when the poll answered. */
10  at: number
11  error: string | null
12}
13
14declare module 'claude-code' {
15  interface PluginState {
16    htui: {
17      /** null until the first poll answers. */
18      waiting: HtuiWaiting | null
19      /** D14's skew line, or null. */
20      skew: string | null
21      /** True once session.start ran and did not stand down (D15); the render hooks read it. */
22      active: boolean
23    }
24  }
25}
26