bespunky-house

1// bespunky-house — the HOUSE BAND: a row above the prompt, shown only
2// while this project's house tooling has something to say (the toolkit moved
3// on, a layer was never applied, the container's post-create failed), with one
4// button that asks Claude to deal with it and one that hides the band.
5//
6// WHY IT ASKS THE SCRIPT. Every rule about when a project is behind — order the
7// stamp against the install, a project AHEAD of this machine is not staleness,
8// silence when the plugin root lives inside the project, the snoozes — lives in
9// check-house-version.sh, the SessionStart hook. The band runs that same script
10// with `--json` and draws what it records, so the two surfaces cannot disagree
11// and no rule is written twice.
12//
13// DETECT, DON'T EXECUTE. The band never runs an upgrade, an update or a chown. Its
14// button submits a prompt — the person's own request, made by pressing it — and
15// Claude then runs the consented path (the /bespunky-house:upgrade command's own
16// gates included).
17//
18// THE PLUGIN WORKS WITHOUT IT. The SessionStart hook still relays the notice to
19// the model; with mods disabled nothing here is missed but the view.
20
21import type { EngineInterface, Register } from 'claude-code'
22
23import type { HouseAction, HouseBand, HouseNotice } from '../types/index.d.ts'
24
25import { BrandFrame, brandLine } from './_brand.tsx'
26
27/** The one value the band draws from. */
28const BAND = { plugin: 'bespunky-house', key: 'band' } as const
29
30const CHECK_TIMEOUT_MS = 10_000
31/** A dismissed band cannot say how it comes back, so the dismissal does. */
32export const DISMISSED_TOAST = 'House notice hidden for this session; the next session checks again'
33const ACTIONS: readonly HouseAction[] = ['upgrade', 'update-toolkit', 'fix-mounts']
34
35/** Each action's button and the prompt it submits. */
36const BUTTONS: Record<HouseAction, { label: string; hotkey: string; prompt: (summary: string) => string }> = {
37  upgrade: {
38    label: 'Upgrade',
39    hotkey: 'u',
40    prompt: summary =>
41      `Run /bespunky-house:upgrade to bring this project up to the current house standard. The house band says: ${summary}`,
42  },
43  'update-toolkit': {
44    label: 'Update toolkit',
45    hotkey: 't',
46    prompt: summary =>
47      `Help me update the claude-toolkit plugins on this machine. The house band says: ${summary} Do not run an upgrade as part of this.`,
48  },
49  'fix-mounts': {
50    label: 'Fix',
51    hotkey: 'f',
52    prompt: summary =>
53      `This container's post-create looks like it failed. The house band says: ${summary} Show me the fix and ask before running anything.`,
54  },
55}
56
57/**
58 * The notices in the script's `--json` output; anything else (no output, a
59 * failed run, an unknown action) is no notice. Pure: the whole parsing policy.
60 */
61export function parseNotices(stdout: string): HouseNotice[] {
62  try {
63    const parsed: unknown = JSON.parse(stdout)
64    const notices = (parsed as { notices?: unknown }).notices
65
66    return Array.isArray(notices) ? notices.filter(isNotice) : []
67  } catch {
68    return []
69  }
70}
71
72function isNotice(value: unknown): value is HouseNotice {
73  const n = value as Partial<HouseNotice> | null
74
75  return (
76    typeof n?.kind === 'string' &&
77    typeof n.summary === 'string' &&
78    n.summary !== '' &&
79    ACTIONS.includes(n.action as HouseAction)
80  )
81}
82
83/** The prompt one notice's button submits. */
84export function promptFor(notice: HouseNotice): string {
85  return BUTTONS[notice.action].prompt(notice.summary)
86}
87
88export const register: Register = on => {
89  on('session.start', async ($, e, next) => {
90    if (e.isInteractive) {
91      const notices = await check($, e.cwd)
92      await $.state.set(BAND, { projectDir: e.cwd, notices, dismissed: false })
93    }
94
95    return next(e)
96  })
97
98  // While the band is up, re-ask after each main-thread turn: an upgrade (or a fix)
99  // that ran in it takes the band down. Nothing shown, nothing re-run.
100  on('turn.complete', async ($, e, next) => {
101    const result = await next(e)
102    const { value: band, version } = await $.state.get(BAND)
103
104    if (e.agentId === undefined && band !== undefined && !band.dismissed && band.notices.length > 0) {
105      const notices = await check($, band.projectDir)
106      if (JSON.stringify(notices) !== JSON.stringify(band.notices)) {
107        await $.state.set(BAND, { ...band, notices }, { ifVersion: version })
108      }
109    }
110
111    return result
112  })
113
114  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
115    const { value: band } = await $.state.get(BAND)
116
117    if (e.props.hasSurvey || band === undefined || band.dismissed || band.notices.length === 0) {
118      return next(e)
119    }
120
121    const ui = $.ui.resolve(e)
122    const { Box, Button, Text } = ui
123
124    return (
125      <BrandFrame ui={ui} site={e}>
126        {band.notices.map((notice, index) => {
127          const button = BUTTONS[notice.action]
128
129          return (
130            <Box key={`house-row-${notice.kind}`} flexDirection="row" gap={1}>
131              <Box flexGrow={1} flexShrink={1}>
132                <Text wrap="truncate-end">{notice.summary}</Text>
133              </Box>
134              <Button
135                key={`house-${notice.kind}`}
136                label={button.label}
137                hotkey={button.hotkey}
138                variant="primary"
139                onPress={() => void $.prompt.submit({ text: promptFor(notice), asUser: true })}
140              />
141              {index === 0 && (
142                <Button key="house-dismiss" label="Dismiss" hotkey="d" role="dismiss" onPress={() => void dismiss($)} />
143              )}
144            </Box>
145          )
146        })}
147      </BrandFrame>
148    )
149  })
150}
151
152/** Runs the SessionStart hook's own detection in `--json` mode; silent on any failure. */
153async function check($: EngineInterface, projectDir: string): Promise<HouseNotice[]> {
154  const root = $.plugin.root
155  try {
156    const ran = await $.process.run(['bash', `${root}/hooks/check-house-version.sh`, '--json'], {
157      cwd: projectDir,
158      env: { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PROJECT_DIR: projectDir },
159      timeoutMs: CHECK_TIMEOUT_MS,
160    })
161
162    return ran.exitCode === 0 ? parseNotices(ran.stdout) : []
163  } catch (error) {
164    $.ui.log(`bespunky-house: house check failed: ${error instanceof Error ? error.message : String(error)}`, {
165      to: 'debug',
166    })
167
168    return []
169  }
170}
171
172/** Hides the band for the rest of the session. */
173async function dismiss($: EngineInterface) {
174  const { value: band, version } = await $.state.get(BAND)
175  if (band !== undefined) {
176    await $.state.set(BAND, { ...band, dismissed: true } satisfies HouseBand, { ifVersion: version })
177    $.ui.toast(brandLine(DISMISSED_TOAST))
178  }
179}
180

1// bespunky-house — the house band's state contract.
2//
3// The band (hooks/band.tsx) is a VIEW over `check-house-version.sh --json`: the
4// SessionStart hook's own detection, recorded as notices instead of relayed as
5// text. Its poller writes this ONE session value and the drawing reads only it.
6// Declared here because `$.state` values are typed by the owner's `PluginState`
7// entry, and anyone may read them.
8
9/**
10 * What a notice asks of a human — the script decides, the band only maps it to
11 * a button:
12 * - `upgrade`        an upgrade is the fix (`/bespunky-house:upgrade`).
13 * - `update-toolkit` this machine's toolkit is behind; an upgrade here would be wrong or refuse.
14 * - `fix-mounts`     the container's post-create failed on an unwritable mount point.
15 */
16export type HouseAction = 'upgrade' | 'update-toolkit' | 'fix-mounts'
17
18/** One notice, as `check-house-version.sh --json` prints it. */
19export type HouseNotice = {
20  /** Which check fired (`toolkit-moved`, `layer-drift`, `dependency-ahead`, `machine-behind`, `post-create-failed`). */
21  kind: string
22  action: HouseAction
23  /** One line, for a person. */
24  summary: string
25}
26
27/**
28 * The band's whole state for the session.
29 *
30 * - `projectDir` the directory the check ran against (the session's start cwd).
31 * - `notices`    what the check said last; empty draws nothing.
32 * - `dismissed`  the person closed the band; it stays closed for the session.
33 */
34export type HouseBand = {
35  projectDir: string
36  notices: readonly HouseNotice[]
37  dismissed: boolean
38}
39
40declare module 'claude-code' {
41  interface PluginState {
42    'bespunky-house': { band: HouseBand }
43  }
44}
45

1// GENERATED from tools/mod-brand/brand.tsx by `node tools/mod-brand/project.mjs --write` — DO NOT EDIT.
2// Change the brand at its source; CI fails when this copy drifts from it.
3
4// ✦ bespunky — THE TOOLKIT'S MOD BRAND: one mark, one accent, one frame, so every toolkit mod (a pane, a band
5// above the prompt, a status entry, a toast) reads as one family — and never as Claude's own UI or another
6// plugin's.
7//
8// THE SINGLE SOURCE. Plugins cannot import each other's files, so this file is PROJECTED, verbatim under a
9// generated header, into `hooks/_brand.tsx` of every plugin whose hooks.json names a module
10// (`node tools/mod-brand/project.mjs --write`); CI fails on any drift. Change the brand HERE, never in a
11// projection, and never re-type the glyph or the colour in a mod.
12//
13// THE RULES IT ENCODES.
14//   - Plain-text surfaces (status line, toast) carry the GLYPH alone: Claude Code titles both with the plugin's
15//     name (`bespunky-workflow: …`), which already says bespunky — spelling it again reads
16//     `bespunky-workflow: ✦ bespunky · …`. `brandLine(text)`.
17//   - A mod's slash command answers in the transcript under the PLUGIN's name (`bespunky-workflow: …`), which
18//     reads as any plugin's. Its output row is redrawn as the toolkit's: `✦ bespunky · <command>` then the
19//     text. `<BrandCommandRow>`, from a `ui.render` hook on `{ component: 'CommandOutput', props: { command } }`.
20//   - Anything drawn BELOW the transcript (every band; a pane seated inline) starts one blank row down, so it
21//     never reads as the tail of Claude's reply.
22//   - The accent is a raw colour, not a theme key: theme keys are Claude's palette, and the point is to look
23//     like something that is not Claude. A mid-tone violet keeps its contrast on light and dark themes; with no
24//     colour at all the glyph and the bold wordmark still carry the mark.
25//
26// Pure: no `$`, no state, no I/O — the mods pass in their surface's element table and render argument.
27
28import type { BoxProps, ElementConstructor, RenderChildren, RenderSurface, TextProps } from 'claude-code'
29
30export const BRAND = {
31  glyph: '✦',
32  name: 'bespunky',
33  /** Violet-500: distinct from Claude's clay, readable on light and dark. */
34  accent: '#8b5cf6',
35} as const
36
37/** The wordmark: `✦ bespunky`. */
38export const WORDMARK = `${BRAND.glyph} ${BRAND.name}`
39
40/** A status entry or toast, marked as the toolkit's: `✦ <text>` (the engine titles both with the plugin's name). */
41export function brandLine(text: string) {
42  return `${BRAND.glyph} ${text}`
43}
44
45/** A drawn site's title: `✦ bespunky · <mod>`, or the wordmark alone. */
46export function brandTitle(mod?: string) {
47  return mod === undefined ? WORDMARK : `${WORDMARK} · ${mod}`
48}
49
50/** Cells a band's brand gutter takes from its row: the wordmark and the gap after it. */
51export const BAND_GUTTER_CELLS = WORDMARK.length + 1
52
53/** The two elements every surface's table carries, which is all the frame draws with. */
54export type BrandUi = { Box: ElementConstructor<BoxProps>; Text: ElementConstructor<TextProps> }
55
56/** The parts of a `ui.render` argument the frame reads: where it draws, and how wide. */
57export type BrandSite =
58  | { surface: RenderSurface; component: 'AbovePrompt'; props: { bodyColumns: number } }
59  | { surface: RenderSurface; component: 'Pane'; props: { bodyColumns: number; placement: 'dock' | 'inline' } }
60
61export type BrandFrameProps = {
62  /** `$.ui.resolve(e)`, the surface's own elements. */
63  ui: BrandUi
64  /** The render argument `e` itself. */
65  site: BrandSite
66  /** The mod's short name for a pane's title (`standing`); a band shows the wordmark alone. */
67  mod?: string
68  children?: RenderChildren
69}
70
71/**
72 * The toolkit's frame for a drawn site. A band: one blank row down from the transcript, the wordmark in a
73 * gutter, the mod's rows beside it. A pane: the branded title over a dim rule (the rule on the terminal only —
74 * the other surfaces frame their panes natively, and a rule of box-drawing glyphs is a terminal idiom), then
75 * the body; one blank row down when seated inline under the transcript.
76 */
77export function BrandFrame({ ui, site, mod, children }: BrandFrameProps) {
78  const { Box, Text } = ui
79  const columns = site.props.bodyColumns
80
81  if (site.component === 'AbovePrompt') {
82    return (
83      <Box flexDirection="row" gap={1} marginTop={1}>
84        <Text color={BRAND.accent} bold>
85          {WORDMARK}
86        </Text>
87        <Box flexDirection="column" flexGrow={1} flexShrink={1}>
88          {children}
89        </Box>
90      </Box>
91    )
92  }
93
94  const title = brandTitle(mod)
95  const rule = site.surface === 'terminal' ? Math.max(0, columns - title.length - 1) : 0
96
97  return (
98    <Box flexDirection="column" gap={1} marginTop={site.props.placement === 'inline' ? 1 : 0}>
99      <Box key="brand-title" flexDirection="row" gap={1}>
100        <Text color={BRAND.accent} bold>
101          {title}
102        </Text>
103        {rule > 0 && <Text dimColor>{'─'.repeat(rule)}</Text>}
104      </Box>
105      {children}
106    </Box>
107  )
108}
109
110/**
111 * A thin dim rule between items of a list, sized to the site (`columns` cells). On the terminal a line of
112 * `─`; elsewhere a one-row gap does the same job without a glyph the surface's font may not tile.
113 */
114export function BrandDivider({ ui, site, columns }: { ui: BrandUi; site: BrandSite; columns?: number }) {
115  const { Box, Text } = ui
116  const width = Math.max(0, columns ?? site.props.bodyColumns)
117
118  return site.surface === 'terminal' ? (
119    <Text dimColor wrap="truncate-end">
120      {'─'.repeat(width)}
121    </Text>
122  ) : (
123    <Box height={1} />
124  )
125}
126
127/**
128 * A toolkit command's output row in the transcript: `✦ bespunky · <command>` in the accent, then the text the
129 * command answered. `text` is the row's own (`e.props.text`); `plugin` is the answering plugin's manifest name
130 * (`$.plugin.name`), whose `name: ` lead — the engine's attribution of a hook-answered row — the brand replaces.
131 */
132export function BrandCommandRow({ ui, command, text, plugin }: { ui: BrandUi; command: string; text: string; plugin: string }) {
133  const { Box, Text } = ui
134  const lead = `${plugin}: `
135  const body = text.startsWith(lead) ? text.slice(lead.length) : text
136
137  return (
138    <Box flexDirection="row" gap={1}>
139      <Text color={BRAND.accent} bold>
140        {brandTitle(command)}
141      </Text>
142      <Box flexGrow={1} flexShrink={1}>
143        <Text dimColor>{body}</Text>
144      </Box>
145    </Box>
146  )
147}
148