bead-chime

1import type { Register } from 'claude-code'
2
3import { registerSounds } from './engine'
4import { rule as beadChime } from './rules/bead-chime'
5
6export const register: Register = (on, options) => registerSounds(on, [beadChime], options)
7

1import type { On, PluginOptions } from 'claude-code'
2
3import { closesBead } from './bead'
4import { TEST_RUNNER } from './runner'
5
6// The sounds of a rule, as paths inside the plugin folder. A pack names the
7// first four; a rule that plays for one event names only that one, and the
8// events it leaves out stay silent.
9export type Clips = {
10  testPass?: string
11  testFail?: string
12  denied?: string
13  turnDone?: string
14  beadClosed?: string
15}
16
17// One sound rule: it maps each event to a file under assets/<id>/.
18export type SoundRule = { id: string; clips: Clips }
19
20// The plugin's userConfig values, checked. `gain` is $.audio.play's linear
21// gain (0 to 4).
22export type Settings = { gain: number; quiet: boolean }
23
24const DEFAULT_GAIN = 1
25const MAX_GAIN = 4
26
27export const settingsFrom = (options: PluginOptions): Settings => {
28  const volume = options['volume']
29  const valid = typeof volume === 'number' && Number.isFinite(volume) && volume >= 0
30  return { gain: valid ? Math.min(volume, MAX_GAIN) : DEFAULT_GAIN, quiet: options['quiet'] === true }
31}
32
33const failed = (id: string, error: unknown): string =>
34  `${id}: no sound, ${error instanceof Error ? error.message : String(error)}`
35
36type Play = (asset: string) => Promise<void>
37
38// A clip that cannot play is logged and dropped: a sound never changes what
39// a tool call or a turn does. `audio` is a closure over the hook's `$`.
40export const playAll = async (
41  rules: readonly SoundRule[],
42  pick: (clips: Clips) => string | undefined,
43  audio: Play,
44  log: (text: string) => unknown,
45): Promise<void> => {
46  for (const rule of rules) {
47    try {
48      const clip = pick(rule.clips)
49      if (clip !== undefined) await audio(clip)
50    } catch (error) {
51      await log(failed(rule.id, error))
52    }
53  }
54}
55
56// The events a finished tool call stands for, as the clip each one plays.
57const picksFor = (e: { tool: string; command?: string }, ran: { deny?: string; isError?: boolean }): ((clips: Clips) => string | undefined)[] => {
58  if (ran.deny !== undefined) return [clips => clips.denied]
59  if (e.tool !== 'Bash' || e.command === undefined) return []
60  const picks: ((clips: Clips) => string | undefined)[] = []
61  if (TEST_RUNNER.test(e.command)) picks.push(ran.isError === true ? clips => clips.testFail : clips => clips.testPass)
62  // Only a close that ended with exit 0 chimes.
63  if (ran.isError !== true && closesBead(e.command)) picks.push(clips => clips.beadClosed)
64  return picks
65}
66
67// The sound registration shared by every sound mod: what a tool call plays.
68// The turn-end sound is a host (hosts/turn.ts), so a mod without one does not
69// list the hook.
70export const registerSounds = (on: On, rules: readonly SoundRule[], options: PluginOptions): void => {
71  const { gain } = settingsFrom(options)
72  // Gain 0 is silence: skip the call rather than start a muted player.
73  if (gain === 0) return
74
75  on('tool.call', async ($, e, next) => {
76    const ran = await next(e)
77    for (const pick of picksFor(e, ran)) {
78      await playAll(rules, pick, asset => $.audio.play({ asset }, { gain }), text => $.ui.log(text))
79    }
80    return ran
81  })
82}
83

1import type { SoundRule } from '../engine'
2
3// One chime, for one event: a `bd close` (or `bd done`) that ended with exit 0.
4// The bell is the zen pack's pass bell, copied (a rule's assets are its own).
5export const rule: SoundRule = {
6  id: 'bead-chime',
7  clips: { beadClosed: 'assets/bead-chime/chime.wav' },
8}
9

1// Says whether a Bash command line closes a bead: some command in it is
2// `bd close` or `bd done` (the alias), run for real. It only reads the text;
3// it never runs anything. The sound and stats engines each keep their own
4// copy of this file (a mod may import only its own files), and a test in each
5// holds the same table.
6//
7// Quoted text is one word, so `echo "bd close x"` is an echo. A command that
8// is written inside a string for another shell (`bash -c "bd close x"`) is
9// not seen. The caller checks the exit code: a line that ends with exit 0
10// but hid a failed close (`bd close x || true`) still counts, a limit of
11// reading only the text.
12
13// bd's global flags that take a value as the next word (`--flag=value` is one word).
14const VALUE_FLAGS = new Set(['-C', '--directory', '--actor', '--db', '--dolt-auto-commit'])
15// Words that may stand before a command and leave it the same command.
16const PREFIXES = new Set(['if', 'then', 'else', 'elif', 'do', 'while', 'until', '!', 'time', 'command', 'exec', 'nohup', 'sudo', 'env'])
17const CLOSERS = new Set(['close', 'done'])
18const HEREDOC = /<<-?\s*(['"]?)([A-Za-z_][\w-]*)\1/g
19
20const withoutHeredocs = (command: string): string => {
21  const lines = command.split('\n')
22  const kept: string[] = []
23  let ends: string | undefined
24  for (const line of lines) {
25    if (ends !== undefined) {
26      if (line.trim() === ends) ends = undefined
27      continue
28    }
29    kept.push(line)
30    const match = [...line.matchAll(HEREDOC)].at(-1)
31    if (match !== undefined) ends = match[2]
32  }
33  return kept.join('\n')
34}
35
36// The commands of a line as lists of words. Quotes group a word and are
37// dropped; `;`, `&`, `|`, a newline and a parenthesis or brace end a command.
38const commandsOf = (line: string): string[][] => {
39  const commands: string[][] = []
40  let words: string[] = []
41  let word = ''
42  let inWord = false
43  let quote: '"' | "'" | undefined
44  const endWord = () => {
45    if (inWord) words = [...words, word]
46    word = ''
47    inWord = false
48  }
49  const endCommand = () => {
50    endWord()
51    if (words.length > 0) commands.push(words)
52    words = []
53  }
54  for (let i = 0; i < line.length; i += 1) {
55    const ch = line.charAt(i)
56    if (quote !== undefined) {
57      if (ch === quote) quote = undefined
58      else if (ch === '\\' && quote === '"' && i + 1 < line.length) word += line.charAt(++i)
59      else word += ch
60    } else if (ch === '"' || ch === "'") {
61      quote = ch
62      inWord = true
63    } else if (ch === '\\' && i + 1 < line.length) {
64      word += line.charAt(++i)
65      inWord = true
66    } else if (ch === ' ' || ch === '\t') endWord()
67    else if (';&|\n(){}`'.includes(ch)) endCommand()
68    else {
69      word += ch
70      inWord = true
71    }
72  }
73  endCommand()
74  return commands
75}
76
77const isBd = (word: string): boolean => word === 'bd' || word.endsWith('/bd')
78
79const closes = (words: readonly string[]): boolean => {
80  let i = 0
81  // Leading words that do not change the command: keywords, wrappers, NAME=value.
82  while (i < words.length && (PREFIXES.has(words[i] ?? '') || /^[A-Za-z_]\w*=/.test(words[i] ?? ''))) i += 1
83  if (!isBd(words[i] ?? '')) return false
84  i += 1
85  while (i < words.length && (words[i] ?? '').startsWith('-')) {
86    i += VALUE_FLAGS.has(words[i] ?? '') ? 2 : 1
87  }
88  if (!CLOSERS.has(words[i] ?? '')) return false
89  // Help and a read-only run change nothing.
90  return !words.some(word => word === '-h' || word === '--help' || word === '--readonly')
91}
92
93export const closesBead = (command: string): boolean => commandsOf(withoutHeredocs(command)).some(closes)
94

1// Test runners count only in command position, so `cat jest.config.js` or
2// `grep vitest` never count as a test run. Copied from the nudge engine's
3// test-reminder rule: a mod may import only its own files.
4const START = '(^|[;&|] *)((npx|bunx|pnpm exec|yarn|uv run|poetry run|bundle exec) +)?'
5const RUNNERS =
6  '((npm|pnpm|yarn|bun) +(run +)?test|vitest|jest|mocha|pytest|python3? +-m +(pytest|unittest)|go +test|cargo +test|rspec|phpunit|mvn +(test|verify)|gradle +test|dotnet +test|ctest|make +(test|check)|bash +tests?/run\\.sh|tests?/run\\.sh|claude +plugin +test)'
7export const TEST_RUNNER = new RegExp(`${START}${RUNNERS}( |$)`, 'm')
8