Turn a ~$5 AliExpress clock into a physical AI usage dashboard (Claude, Codex, multi-account). No firmware flashing.
// TokenTV's mod for Claude Code. While Claude Code waits for you to answer a permission prompt, Clawd on your
// TokenTV clock raises a hand (then hops, then holds up a sign); when a turn is done, it bows. `/tokentv pet` and
// `/tokentv snack` give Clawd a pat or a snack, one loop of hearts or munching. A risky command puts Clawd in the
// courtroom, a deleted file leaves a ghost about, a rude prompt turns its back, a failed tool makes it dizzy, a
// compaction makes it squeeze its head, and the readout says Claude Code's own thinking word while a turn runs.
// `/tokentv sound on` plays a short sound on this computer when a prompt waits for you and when a turn is done.
//
// It tells the TokenTV running on this computer a name and nothing else: `claude.ask` (a permission prompt is now
// waiting for you), `claude.answered` (you answered it, or it is over), `claude.end` (a turn ended), `claude.stop`
// (a turn that showed a thinking word was cut short), `claude.pet` and `claude.snack` (the two commands),
// `claude.risky`, `claude.deleted`, `claude.rude`, `claude.calm`, `claude.failed`, `claude.compact`, and
// `claude.word:` with one word of letters (Claude Code's spinner word, `claude.word:PONDERING`). Prompts, commands,
// their words, paths, outputs and ids stay in this file, and are read only to decide which name it is: nothing of
// them is kept. TokenTV counts the waits of every session, so each session says once that its prompt opened and
// once that it closed. Sounds go to TokenTV not at all.
//
// Nothing here is awaited on Claude Code's path, nor changes or blocks anything there: the requests go out in the
// background, one after another so they arrive in the order they happened, and when no TokenTV runs (or it does not
// answer) nothing happens at all. What is below lives as long as the session (one per session); the sound setting
// alone is kept, in Claude Code's own store for this plugin.
// TokenTV lets every wait go 30 minutes after the continuous wait began, at this ask or before it (its answer to the
// ask says how long that wait had lasted: TokenTV-Wait-Age). An answer after that would close another, newer wait
// there, so it is not sent; nor one that would come this close to it (it might land just after).
const EXPIRE_MS = 30 * 60 * 1000
const MARGIN_MS = 5000
const KEEP = 256 // calls already answered, remembered so a late repeat of one is not a new wait
const PATIENCE_MS = 2000 // the longest one request holds the next back (TokenTV answers in milliseconds)
const STALE_MS = 5000 // a moment that could not go out within this is dropped: news, not history
const WORD = 'claude.word:' // and the spinner's word: one word of 1 to 14 letters A-Z, sent in capitals
const SAY_AGAIN_MS = 5 * 60 * 1000 // a word still on is said again this often (TokenTV lets a word go unheard 30 min)
const SOUNDS = { wait: 'sounds/wait.wav', done: 'sounds/done.wav' } // the plugin's own two short clips
const STORE_MS = 1000 // the longest the sound setting's store may take, read or written
// The most of a prompt and of a command read to tell which name it is (their head): a paste of megabytes would take
// a tenth of a second or more, and a shout or a risky command is short.
const PROMPT_READ = 64 * 1024
const COMMAND_READ = 128 * 1024
// `to` names the running TokenTV that counted the wait's ask; its answer goes to that one only, never to another
// (one started since, which never saw the ask, would close a wait of someone else's). `sent` is the ask's own
// request, which the answer waits for: TokenTV may count the ask however late it says so. `waited` is how long
// TokenTV's continuous wait had lasted when it took the ask (ms; none from a TokenTV that does not say).
type Wait = { agent: string | undefined; at: number; to?: string; sent?: Promise<unknown>; waited?: number }
const waits = new Map<string, Wait>() // tool_use_id -> a prompt this session announced and has not closed
const callers = new Map<string, string | undefined>() // tool_use_id -> the subagent making a call now, if one is
const answered: string[] = []
let interactive = true // false in `claude -p` and the SDK: nobody sits at a dialog there
let mode: string | undefined // the permission mode, when Claude Code says it (auto mode's classifier asks no one)
let lastTurn: string | undefined
let queue: Promise<void> = Promise.resolve() // what is told goes out in the order it happened
// What a call that is still going has shown of itself, kept only till it ends: whether it asked you, ran (drawn
// running, or Claude Code's PostToolUseFailure for it), was cut short, or refused by a rule, a hook or auto mode.
const prompted = new Set<string>()
const ran = new Set<string>()
const cut = new Set<string>()
const denied = new Set<string>()
let turning = false // a main turn is going (turn.start to its turn.complete): the spinner's word is its
let said: string | undefined // the word this turn last sent...
let saidAt: number | undefined // ...and when
let sound = false // the sound setting as this session knows it (the store's, when it answers, wins)
export function register(on: any) {
on('session.start', async ($: any, e: any, next: any) => {
interactive = e?.isInteractive !== false
try {
// `immediate`: a pat typed while Claude works goes at once, not after the turn (it touches nothing of it)
await $.command.register({ name: 'tokentv',
description: 'Pet Clawd on your TokenTV clock, give it a snack, or turn its sounds on or off',
argumentHint: 'pet | snack | sound on | sound off', immediate: true })
} catch {}
return next(e)
})
// `/tokentv pet` and `/tokentv snack`: one name each to TokenTV, sent as the other moments are (in the
// background: the command never waits for it). `/tokentv sound on` and `/tokentv sound off`: this computer's
// sounds, nothing to TokenTV. Anything else after /tokentv sends nothing; its words go nowhere.
on('command.run', { command: 'tokentv' }, async ($: any, e: any) => {
const word = String(e?.args ?? '').trim().toLowerCase()
const setting = /^sound\s+(on|off)$/.exec(word)
if (setting) {
sound = setting[1] === 'on'
try {
await within($, Promise.resolve($.store.set('sound', sound)), STORE_MS)
} catch {}
return { text: sound ? 'Sounds on: a short sound on this computer when Claude Code waits for you and when a ' +
'turn is done (Claude Code plays it on macOS; a Linux or Windows terminal stays silent).'
: 'Sounds off.' }
}
const moment = word === 'pet' ? 'claude.pet' : word === 'snack' ? 'claude.snack' : undefined
if (!moment) return { text: 'Try /tokentv pet, /tokentv snack, or /tokentv sound on|off.' }
if (await onWindows($)) return { text: 'On Windows the TokenTV mod sends nothing for now.' }
if (!(await findTokenTV($).catch(() => undefined))) {
return { text: 'No TokenTV is running on this computer: nothing was sent.' }
}
send($, moment)
return { text: word === 'pet' ? 'A pat for Clawd, on its way to TokenTV.' : 'A snack for Clawd, on its way to TokenTV.' }
})
// Read only for the permission mode (auto mode's classifier, not a person, settles what the rules leave open):
// as the session starts and again before each tool call, as Claude Code's settings hooks are told it.
on('classic.SessionStart', noteMode)
on('classic.PreToolUse', async ($: any, e: any, next: any) => {
if (typeof e?.permission_mode === 'string') mode = e.permission_mode
const verdict = await next(e)
try {
if (typeof verdict?.deny === 'string') note(denied, e?.tool_use_id) // a settings hook refused the call
} catch {}
return verdict
})
// A call that failed: one loop of Clawd dizzy, if it ran (not one you refused, nor one cut short). Claude Code
// says which of its failures were interruptions; and when auto mode's classifier (or a rule) refused one.
on('classic.PostToolUseFailure', async ($: any, e: any, next: any) => {
try {
note(e?.is_interrupt === true ? cut : ran, e?.tool_use_id)
} catch {}
return next(e)
})
on('classic.PermissionDenied', async ($: any, e: any, next: any) => {
try {
note(denied, e?.tool_use_id)
} catch {}
return next(e)
})
// The decision on a call, with Claude Code's verdict passed on untouched. `ask` with nobody else to decide it
// means the permission prompt is about to show: one wait, once per call however often it is seen.
on('tool.check', async ($: any, e: any, next: any) => {
const decided = await next(e)
try {
const id = e?.tool_use_id
if (decided?.decision === 'deny') note(denied, id)
if (asksYou(decided, id) && !waits.has(id) && !answered.includes(id)) {
const wait = { agent: e.agentId ?? callers.get(id), at: 0 }
const first = waits.size === 0 // this session's first prompt open: a wait begins (its sound, if on)
waits.set(id, wait)
note(prompted, id)
send($, 'claude.ask', wait)
if (first) cue($, 'wait')
}
} catch {}
return decided
})
// Your answer, as it happens: Claude Code draws the asked call's row again the moment you answer, running (you
// said yes) or with its result (you said no). Measured in Claude Code 2.1.289 (2026-11-01): the asked call's
// `isRunning` turns true in the first ToolGroup drawing after "Yes", while the tool.call around it settles only
// once the tool is done. Drawings come often: with no prompt open they are handed straight on, and none is changed.
on('ui.render', { component: ['ToolGroup', 'ToolUse'] }, async ($: any, e: any, next: any) => {
if (waits.size === 0 && callers.size === 0) return next(e)
try {
const calls = e?.component === 'ToolGroup' ? e.props?.calls ?? [] : [e?.props] // a ToolUse row is one call
for (const call of calls) {
if (call?.isRunning === true) note(ran, call.tool_use_id) // (it ran: a failure now is the tool's own)
if (call?.isInterrupted === true) note(cut, call.tool_use_id)
if (waits.has(call?.tool_use_id) && (call.isRunning === true || call.output != null)) {
answer($, call.tool_use_id)
}
}
} catch {}
return next(e)
})
// The spinner's word while a turn runs (`Pondering`, as Claude Code samples it for the turn): one word of up to
// 14 letters goes to TokenTV, once (and again every SAY_AGAIN_MS while it stays); anything else is left out. The
// drawing passes on untouched.
on('ui.render', { component: 'Spinner' }, async ($: any, e: any, next: any) => {
try {
const word = e?.props?.word
if (turning && typeof word === 'string' && /^[A-Za-z]{1,14}$/.test(word)) say($, word.toUpperCase())
} catch {}
return next(e)
})
on('turn.start', async ($: any, e: any, next: any) => {
turning = true // (a subagent's run raises no turn.start)
said = saidAt = undefined
return next(e)
})
// A prompt you typed (here, or from your phone through Remote Control): in capitals, or with a swear in it, Clawd
// turns its back (`claude.rude`); any other turns it round (`claude.calm`). The prompt is read for that and
// passed on untouched; nothing of it is kept or sent.
on('prompt.submit', async ($: any, e: any, next: any) => {
try {
const from = e?.origin?.kind
if (typeof e?.text === 'string' && (from === undefined || from === 'composer' || from === 'bridge')) {
send($, rude(e.text.slice(0, PROMPT_READ)) ? 'claude.rude' : 'claude.calm')
}
} catch {}
return next(e)
})
// A compaction of the main conversation, once done (not one computed ahead to keep, nor a subagent's): one loop
// of Clawd squeezing its head. What was compacted passes on untouched.
on('session.compact', async ($: any, e: any, next: any) => {
const done = await next(e)
try {
if (!e?.agentId && e?.trigger !== 'precompute' && Array.isArray(done?.messages)) send($, 'claude.compact')
} catch {}
return done
})
// The permission check, your answer and the tool all happen inside `next`: once it is back, the prompt is over
// (the tool ran, or was refused, or the turn was cut short), if no drawing said so before. A Bash command is read
// as it is called, for its risk (the courtroom, said at once) and whether it deletes files (a ghost, said once it
// succeeded); a call of any tool that ran and failed is a dizzy Clawd. The call and its result pass through
// untouched.
on('tool.call', async ($: any, e: any, next: any) => {
const id = e?.tool_use_id
if (typeof id === 'string') callers.set(id, e.agentId) // tool.check carries it only from Claude Code 2.1.290
let kinds: Kinds | undefined
try {
kinds = e?.tool === 'Bash' && typeof e?.command === 'string' ? judged(e.command.slice(0, COMMAND_READ)) : undefined
if (kinds?.risky) send($, 'claude.risky')
} catch {}
let result: any
try {
result = await next(e)
return result
} finally {
callers.delete(id)
answer($, id)
try {
finished($, id, kinds, result, next?.signal)
} catch {}
}
})
// A turn's end closes its open prompts; the main turn's end, when it was not cut short, is a bow (and its sound,
// if on). One cut short that showed a word says so, so its word goes too.
on('turn.complete', async ($: any, e: any, next: any) => {
try {
for (const [id, wait] of [...waits]) if (wait.agent === e?.agentId) answer($, id)
const id = e?.turnId
if (!e?.agentId) {
const spoke = said !== undefined
turning = false
said = saidAt = undefined
if (id === undefined || id !== lastTurn) {
if (!e?.isAborted) {
lastTurn = id
send($, 'claude.end')
cue($, 'done')
} else if (spoke) {
lastTurn = id
send($, 'claude.stop')
}
}
}
} catch {}
return next(e)
})
on('session.end', async ($: any, e: any, next: any) => {
try {
for (const id of [...waits.keys()]) answer($, id) // sent as the rest are; TokenTV lets go of any left
if (turning && said !== undefined) send($, 'claude.stop') // ended mid-turn: its word goes
turning = false
said = saidAt = undefined
} catch {}
return next(e)
})
}
// A call still going (tool.call has it): what it showed of itself, till it ends.
function note(set: Set<string>, id: unknown) {
if (typeof id === 'string' && callers.has(id)) set.add(id)
}
// A call is over with `result`: a Bash call that deleted files and succeeded leaves a ghost; any call that ran and
// failed (Claude Code says isError) makes Clawd dizzy, but not one refused (by you, a rule, a hook or auto mode),
// cut short or abandoned. What the call showed of itself is let go here.
function finished($: any, id: unknown, kinds: Kinds | undefined, result: any, signal: any) {
const key = typeof id === 'string' ? id : ''
const shown = { asked: prompted.has(key), ran: ran.has(key), cut: cut.has(key), denied: denied.has(key) }
for (const set of [prompted, ran, cut, denied]) set.delete(key)
if (!result || typeof result !== 'object' || typeof result.deny === 'string' || signal?.aborted === true) return
if (result.isError === true) {
if (!shown.cut && !shown.denied && (!shown.asked || shown.ran)) send($, 'claude.failed')
} else if (kinds?.deletes) {
send($, 'claude.deleted')
}
}
// The spinner's word: sent when it is new this turn, and again only once SAY_AGAIN_MS has gone by.
function say($: any, word: string) {
if (word !== said) {
said = word
saidAt = undefined
send($, WORD + word)
clockNow($).then((now) => { if (said === word) saidAt = now }, () => {})
return
}
clockNow($).then((now) => {
if (said === word && saidAt !== undefined && now - saidAt >= SAY_AGAIN_MS) {
saidAt = now
send($, WORD + word)
}
}, () => {})
}
// A short sound on this computer (`wait` or `done`), if the setting is on: Claude Code's own player plays the
// plugin's clip; nothing goes to TokenTV for it, and nothing waits for it. Where there is no player (a Linux or
// Windows terminal), or it fails, nothing sounds.
function cue($: any, which: 'wait' | 'done') {
soundOn($)
.then((on) => (on ? $.audio.play({ asset: SOUNDS[which] }) : undefined))
.catch(() => {})
}
// The sound setting: the store's (so a change in one session holds in the others), else this session's.
async function soundOn($: any) {
try {
const kept = await within($, Promise.resolve($.store.get('sound')), STORE_MS)
if (typeof kept === 'boolean') return kept
} catch {}
return sound
}
async function noteMode($: any, e: any, next: any) {
if (typeof e?.permission_mode === 'string') mode = e.permission_mode
return next(e)
}
function asksYou(decided: any, id: unknown) {
if (!decided || decided.decision !== 'ask' || decided.decider) return false // a host program answers that one
if (typeof id !== 'string' || id === '' || !interactive || mode === 'dontAsk') return false
// In auto mode the classifier settles an ask, unless an ask rule or a PreToolUse hook asked for you.
return mode !== 'auto' || Boolean(decided.rule || decided.hook)
}
function answer($: any, id: unknown) {
if (typeof id !== 'string') return
const wait = waits.get(id)
if (!wait) return
waits.delete(id)
answered.push(id)
if (answered.length > KEEP) answered.shift()
send($, 'claude.answered', wait)
}
// In the background, never awaited by a hook: each moment waits for the one before it to be answered (or for
// PATIENCE_MS), so TokenTV takes them in the order they happened; one held up past STALE_MS is dropped.
function send($: any, moment: string, wait?: Wait) {
const asked = clockNow($)
asked.catch(() => {})
queue = queue.then(() => deliver($, moment, asked, wait)).catch(() => {})
}
async function deliver($: any, moment: string, asked: Promise<number>, wait?: Wait) {
if (wait && moment === 'claude.answered') {
// The ask's own request first: TokenTV may say late that it counted it. Not past STALE_MS: a TokenTV that
// never answers holds nothing up for long (and an ask it never confirmed is not answered).
if (wait.sent) await within($, wait.sent, STALE_MS)
if (wait.to === undefined) return // TokenTV never took the ask: nothing of it to close
const began = wait.at - (wait.waited ?? 0) // the continuous wait at TokenTV, which this ask joined
if ((await clockNow($)) - began >= EXPIRE_MS - MARGIN_MS) return // TokenTV has let this wait go by now
// An answer whose ask was counted goes however late, or the wait would stay on the clock.
} else if ((await clockNow($)) - (await asked) > STALE_MS) {
return
}
const place = await findTokenTV($)
if (!place) return
if (wait && moment === 'claude.answered' && wait.to !== place.id) return // another TokenTV run never saw the ask
const init = { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ moment }),
socketPath: place.socket }
const sent = $.http.fetch(place.url, init).then((response: any) => {
if (!wait || moment !== 'claude.ask' || !response?.ok) return
wait.to = place.id
const waited = Number(response.headers?.['tokentv-wait-age']) // seconds; absent from an older TokenTV
if (Number.isFinite(waited) && waited >= 0) wait.waited = waited * 1000
})
const settled = sent.catch(() => {})
if (wait && moment === 'claude.ask') {
wait.at = await clockNow($)
wait.sent = settled
}
await within($, settled, PATIENCE_MS)
}
// `work`, or nothing after `ms`: the host's clock, else the runtime's own timer where there is one, else `work`.
function within($: any, work: Promise<unknown>, ms: number) {
const later = () =>
typeof (globalThis as any).setTimeout === 'function'
? new Promise((done) => (globalThis as any).setTimeout(done, ms))
: work
let timer: Promise<unknown>
try {
timer = Promise.resolve($.clock.sleep(ms)).catch(later)
} catch {
timer = later()
}
return Promise.race([work, timer])
}
async function clockNow($: any) {
try {
return await $.clock.now()
} catch {
return Date.now()
}
}
// Where the running TokenTV listens: its state folder beside the config `token-tv start` uses
// (<XDG_CONFIG_HOME or ~/.config>/token-tv/state), or beside TOKEN_TV_CONFIG for another config. TokenTV writes its
// address there while it runs (live.url) and, on Linux and macOS, a socket of its own (live.sock). A moment goes
// only over that socket, where it meets no proxy and cannot be redirected anywhere else (Claude Code 2.1.289,
// measured 2026-11-01: Content-Length, Host 127.0.0.1:port). Over TCP the same fetch takes a proxy set in its
// environment, even to 127.0.0.1, and follows a redirect wherever it points, whatever its options say (measured the
// same day): so with no socket nothing is sent, and a live.url alone, perhaps left from a TokenTV that stopped, its
// port another program's now, is never tried. TokenTV makes no socket on Windows: there nothing is sent for now,
// whatever the folder holds.
async function onWindows($: any) {
return (await Promise.resolve().then(() => $.env.get('OS')).catch(() => undefined)) === 'Windows_NT'
}
async function findTokenTV($: any) {
if ((await $.env.get('OS')) === 'Windows_NT') return undefined
const home = (await $.env.get('HOME')) || (await $.env.get('USERPROFILE'))
const config = await $.env.get('TOKEN_TV_CONFIG')
let state: string | undefined
if (config) {
const path = /^~[\\/]/.test(config) && home ? home + config.slice(1) : config
const cut = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
state = (cut < 0 ? '' : path.slice(0, cut + 1)) + 'state'
} else {
const base = (await $.env.get('XDG_CONFIG_HOME')) || (home ? home + '/.config' : undefined)
state = base ? base + '/token-tv/state' : undefined
}
if (!state) return undefined
if (!absolute(state)) {
// Claude Code takes a socket only by an absolute path (2.1.289 refuses `./state/live.sock`): a relative one is
// made absolute from the folder the session started in, where the relative TOKEN_TV_CONFIG was set. Not the
// session's current folder, which follows a `cd` the model runs. With no absolute folder: nothing is sent.
const root = await Promise.resolve().then(() => $.session.root()).catch(() => undefined)
if (!absolute(root)) return undefined
state = root.replace(/[\\/]+$/, '') + '/' + state.replace(/^(\.[\\/])+/, '')
}
const text = await $.fs.read(state + '/live.url')
const url = loopback(text)
if (!url) return undefined
// Which run of TokenTV this is: it writes live.url anew each time it starts.
const stat = await $.fs.stat(state + '/live.url').catch(() => undefined)
const id = String(text).trim() + '@' + (stat?.mtimeMs ?? '')
const socket = state + '/live.sock'
if (!(await $.fs.exists(socket))) return undefined
return { url: url + '/moment', socket, id }
}
// A path from the root of a drive: /…, C:\… or C:/…, or \\server\share.
function absolute(path: unknown): path is string {
return typeof path === 'string' && /^(\/|[A-Za-z]:[\\/]|\\\\)/.test(path)
}
// Only this computer: http to 127.0.0.1, localhost (sent as 127.0.0.1, never looked up) or [::1] with a port,
// and nothing else. Any other address, a user, a path or a query: not ours to send to.
function loopback(text: unknown) {
const found = /^http:\/\/(127\.0\.0\.1|localhost|\[::1\]):(\d{1,5})$/.exec(String(text ?? '').trim())
if (!found || Number(found[2]) < 1 || Number(found[2]) > 65535) return undefined
return 'http://' + (found[1] === 'localhost' ? '127.0.0.1' : found[1]) + ':' + Number(found[2])
}
// --- Which name: the prompt and the Bash command, read here and kept nowhere -------------------------------------
// e7: a prompt in capitals (at least CAPS_MIN letters, four in five or more of them capitals; a letter of a script
// without capitals, Hangul say, counts as a letter that is not one) or with a swear in it: SWEAR_EN, whole words in
// any case; SWEAR_KO, words starting so, but not the everyday words in SWEAR_KO_NOT. The owner's lists, one place.
const CAPS_MIN = 8
const SWEAR_EN = new Set(['fuck', 'fucks', 'fucked', 'fucking', 'fucker', 'motherfucker', 'shit', 'shitty', 'bullshit',
'damn', 'dammit', 'damnit', 'goddamn', 'wtf', 'stfu', 'bitch', 'asshole', 'bastard'])
const SWEAR_KO = ['씨발', '시발', '씨팔', 'ㅅㅂ', 'ㅆㅂ', '개새끼', '병신', '지랄', '존나', '좆']
const SWEAR_KO_NOT = ['시발점', '시발역', '병신년']
function rude(text: string) {
const letters = text.match(/\p{L}/gu) ?? []
const capitals = letters.filter((c) => /\p{Lu}|\p{Lt}/u.test(c)).length
if (letters.length >= CAPS_MIN && capitals * 5 >= letters.length * 4) return true
return (text.match(/[\p{L}\p{M}]+/gu) ?? []).some((word) => SWEAR_EN.has(word.toLowerCase()) ||
(SWEAR_KO.some((stem) => word.startsWith(stem)) && !SWEAR_KO_NOT.some((benign) => word.startsWith(benign))))
}
// e3, e4: what a Bash command does, read as a shell would (quotes, comments, here-documents and redirections are
// data; `;`, `&&`, `|`, `$(…)`, backquotes, `bash -c`, `eval`, `find -exec` and wrappers such as `sudo` or `env`
// lead to commands; `command -v` and the like only look one up). Risky: `rm` recursive and forced, `git push
// --force` (`-f`, `--force-with-lease`, a `+refspec`), `git reset --hard`, `git clean` forced with directories (not
// a dry run), `DROP TABLE` or `DROP DATABASE` given to a database client as SQL (not in a string or a comment),
// `mkfs`, `dd of=/dev/…`, `chmod -R 777 /`. Deleting: `rm`, `git rm` (not `--cached`, not a dry run), `find …
// -delete` (or `-exec rm`), `unlink`, each with something to delete. Read in one pass: a command of many parts takes
// no longer than its length says.
type Kinds = { risky: boolean; deletes: boolean }
type Command = { words: string[]; input: string[]; pipe: number }
const PREFIXES = new Set(['if', 'then', 'else', 'elif', 'do', 'while', 'until', '!', '{'])
// A wrapper runs the command after it: its options that take a value, and the words it takes before the command;
// with an option `looks` matches, it only looks the command up (`command -v rm`) and runs nothing.
const WRAPPERS = new Map<string, { takes: string[]; operands: number; looks?: RegExp }>(Object.entries({
sudo: { takes: ['-u', '-g', '-C', '-D', '-h', '-p', '-r', '-t', '-U', '-T', '--user', '--group', '--chdir', '--host',
'--prompt', '--role', '--type', '--other-user', '--command-timeout', '--close-from'], operands: 0 },
doas: { takes: ['-u', '-C'], operands: 0 },
env: { takes: ['-u', '-C', '-S', '--unset', '--chdir', '--split-string'], operands: 0 },
command: { takes: [], operands: 0, looks: /^-[A-Za-z]*[vV]/ },
builtin: { takes: [], operands: 0 },
exec: { takes: ['-a'], operands: 0 },
nohup: { takes: [], operands: 0 },
time: { takes: ['-f', '-o', '--format', '--output'], operands: 0 },
nice: { takes: ['-n', '--adjustment'], operands: 0 },
ionice: { takes: ['-c', '-n', '-p', '-P', '-u'], operands: 0 },
timeout: { takes: ['-s', '-k', '--signal', '--kill-after'], operands: 1 },
setsid: { takes: [], operands: 0 },
stdbuf: { takes: ['-i', '-o', '-e'], operands: 0 },
xargs: { takes: ['-I', '-n', '-P', '-L', '-s', '-d', '-E', '-a', '--max-args', '--max-procs', '--max-lines',
'--max-chars', '--delimiter', '--eof', '--arg-file', '--replace'], operands: 0 },
}))
const SHELLS = new Set(['bash', 'sh', 'zsh', 'dash', 'ksh'])
// The commands judge() reads (with mkfs.<kind> and the shells): any other runs nothing of the lists.
const JUDGED = new Set(['rm', 'unlink', 'git', 'find', 'dd', 'chmod', 'eval', ...SHELLS])
const SQL = new Set(['psql', 'mysql', 'mariadb', 'sqlite3', 'sqlcmd', 'duckdb', 'clickhouse', 'clickhouse-client',
'cockroach', 'pgcli', 'mycli', 'litecli', 'usql', 'sqlplus', 'snowsql', 'bq', 'trino', 'beeline'])
const HASH_COMMENTS = new Set(['mysql', 'mariadb', 'mycli']) // `#` starts a comment there (elsewhere an operator)
const CLIENT = 1 // a pipeline's marks (judged)
const HASH = 2
const DROPS = 4
const OPEN_ALL = new Set(['777', '0777', 'a+rwx', 'a=rwx', 'ugo+rwx', 'ugo=rwx'])
const GIT_VALUED = new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace', '--super-prefix', '--config-env'])
// find's tests and actions that take the next word as their value (a pattern, a name, a format, a file): never an
// action itself, as `-name '-delete'` is not one. (`-fprintf` takes two, `-newerXY` one.)
const FIND_VALUED = new Set(['-name', '-iname', '-path', '-ipath', '-wholename', '-iwholename', '-regex', '-iregex',
'-lname', '-ilname', '-newer', '-anewer', '-cnewer', '-samefile', '-perm', '-type', '-xtype', '-user', '-group',
'-uid', '-gid', '-size', '-mtime', '-atime', '-ctime', '-mmin', '-amin', '-cmin', '-used', '-links', '-inum',
'-maxdepth', '-mindepth', '-fstype', '-context', '-printf', '-fprint', '-fprint0', '-fls', '-regextype',
'-files0-from'])
function judged(source: string, depth = 0): Kinds {
const kinds = { risky: false, deletes: false }
if (depth > 4) return kinds // (`bash -c` within `bash -c` within …: enough)
const commands: Command[] = []
const pipes = { n: 0 }
parse(source, { i: 0 }, '', commands, pipes)
// Each pipeline's marks: a database client is in it (CLIENT; HASH when `#` starts a comment there), it says "drop"
// somewhere (DROPS). A DROP counts only in a pipeline with both, as SQL one of its clients reads.
const marks = new Uint8Array(pipes.n)
for (const command of commands) {
const found = unwrapped(command.words)
if (found && SQL.has(found.name)) marks[command.pipe] |= CLIENT | (HASH_COMMENTS.has(found.name) ? HASH : 0)
if (command.words.some(saysDrop) || command.input.some(saysDrop)) marks[command.pipe] |= DROPS
judge(found, kinds, depth)
}
const texts = new Map<number, string[]>()
for (const command of commands) {
if ((marks[command.pipe] & (CLIENT | DROPS)) !== (CLIENT | DROPS)) continue
let parts = texts.get(command.pipe)
if (!parts) texts.set(command.pipe, (parts = []))
for (const word of command.words) parts.push(given(word))
for (const text of command.input) parts.push(text)
}
for (const [pipe, parts] of texts) {
if (drops(parts.map((text) => sqlRead(text, (marks[pipe] & HASH) !== 0)))) kinds.risky = true
}
return kinds
}
function saysDrop(text: string) {
return text.length >= 4 && /drop/i.test(text)
}
// What of a word in a database client's pipeline may be SQL: an option's value (`--command=…`), not the option.
function given(word: string) {
if (word[0] !== '-') return word
const valued = /^--?[A-Za-z][\w-]*=/.exec(word)
return valued ? word.slice(valued[0].length) : /^-\S*$/.test(word) ? '' : word
}
// DROP TABLE or DROP DATABASE as SQL in the texts read (sqlRead), not in a string or a comment; but where the SQL
// runs a string as a statement (EXECUTE, PREPARE, a DO block), a DROP in its strings counts too.
function drops(read: [string, string][]) {
const dynamic = read.some(([bare]) => /\b(EXECUTE|PREPARE)\b|(^|;)\s*DO\b/i.test(bare))
return /\bDROP\s+(TABLE|DATABASE)\b/i.test(read.map((both) => both[dynamic ? 1 : 0]).join(' '))
}
// `text` read as SQL, its comments left out (`-- …`, `/* … */`, and `# …` where `hash`): [without its string
// literals and quoted names, with them]. Those are `'…'` and `"…"` (a backslash escapes in them), `` `…` `` and
// `$tag$…$tag$`. One pass: each literal or comment is skipped whole.
const DOLLAR_TAG = /\$(?:[A-Za-z_]\w{0,62})?\$/y
function sqlRead(text: string, hash: boolean): [string, string] {
if (!/['"`$#/-]/.test(text)) return [text, text] // (nothing of the kind in it)
const bare: string[] = []
const full: string[] = []
let from = 0 // the SQL not yet kept starts here
let i = 0
while (i < text.length) {
const c = text[i]
let end = -1 // where the literal or comment starting at `i` ends
let literal = false
if (c === "'" || c === '"' || c === '`') {
let j = i + 1
while (j < text.length && text[j] !== c) j += text[j] === '\\' && c !== '`' ? 2 : 1
end = Math.min(j + 1, text.length)
literal = true
} else if ((c === '-' && text[i + 1] === '-') || (c === '#' && hash)) {
end = text.indexOf('\n', i)
if (end < 0) end = text.length
} else if (c === '/' && text[i + 1] === '*') {
end = text.indexOf('*/', i + 2)
end = end < 0 ? text.length : end + 2
} else if (c === '$' && !/[\w$]/.test(text[i - 1] ?? ' ')) {
DOLLAR_TAG.lastIndex = i
const tag = DOLLAR_TAG.exec(text)?.[0]
if (tag) {
const close = text.indexOf(tag, i + tag.length)
end = close < 0 ? text.length : close + tag.length
literal = true
}
}
if (end < 0) {
i++
continue
}
const sql = text.slice(from, i)
bare.push(sql, ' ')
full.push(sql, literal ? text.slice(i, end) : ' ')
from = i = end
}
bare.push(text.slice(from))
full.push(text.slice(from))
return [bare.join(''), full.join('')]
}
// What the command `found` (unwrapped) runs, into `kinds`.
function judge(found: Found | undefined, kinds: Kinds, depth: number) {
if (!found) return
const name = found.name
const mkfs = name.startsWith('mkfs') && /^mkfs(\.[A-Za-z0-9]+)?$/.test(name)
if (!JUDGED.has(name) && !mkfs) return // (most commands)
const args = found.words.slice(1)
const either = (more: Kinds) => {
kinds.risky ||= more.risky
kinds.deletes ||= more.deletes
}
if (SHELLS.has(name)) {
const at = args.findIndex((a) => /^-[A-Za-z]*c[A-Za-z]*$/.test(a))
if (at >= 0 && typeof args[at + 1] === 'string') either(judged(args[at + 1], depth + 1))
return
}
if (name === 'eval') return either(judged(args.join(' '), depth + 1))
if (name === 'git') return git(args, kinds)
if (name === 'dd') {
if (args.some((a) => a.startsWith('of=/dev/'))) kinds.risky = true
return
}
if (name === 'find') {
for (let k = 0; k < args.length; k++) {
const a = args[k]
if (a === '-delete') kinds.deletes = true
else if (a === '-fprintf') k += 2
else if (FIND_VALUED.has(a) || /^-newer[aBcmt]{2}$/.test(a)) k++ // (its value, whatever it says)
else if (['-exec', '-execdir', '-ok', '-okdir'].includes(a)) {
let end = k + 1
while (end < args.length && args[end] !== ';' && args[end] !== '+') end++
judge(unwrapped(args.slice(k + 1, end)), kinds, depth)
k = end
}
}
return
}
const opts = options(args)
const has = (short: string, long: string) => opts.short.has(short) || opts.long.has(long)
const something = opts.operands.length > 0 || found.fed // (xargs gives it what to work on)
if (name === 'rm' && something && !opts.long.has('help') && !opts.long.has('version')) {
kinds.deletes = true
if ((has('r', 'recursive') || opts.short.has('R')) && has('f', 'force')) kinds.risky = true
} else if (name === 'unlink' && something) {
kinds.deletes = true
} else if (name === 'chmod') {
const [mode, ...targets] = opts.operands
if (has('R', 'recursive') && OPEN_ALL.has(mode ?? '') && targets.some((t) => t === '/' || t === '/*')) kinds.risky = true
} else if (mkfs && opts.operands.length > 0) {
kinds.risky = true
}
}
function git(args: string[], kinds: Kinds) {
let k = 0
while (k < args.length && args[k].startsWith('-')) k += GIT_VALUED.has(args[k]) ? 2 : 1 // git's own options
const sub = args[k]
const opts = options(args.slice(k + 1))
if (sub === 'push') {
// forced by an option, or by a refspec after the remote that starts with `+` (`git push origin +main`)
const plus = opts.operands.slice(1).some((ref) => ref.length > 1 && ref.startsWith('+'))
if (opts.short.has('f') || opts.long.has('force') || opts.long.has('force-with-lease') || plus) kinds.risky = true
} else if (sub === 'reset') {
if (opts.long.has('hard')) kinds.risky = true
} else if (sub === 'clean') {
const force = opts.short.has('f') || opts.long.has('force')
const dry = opts.short.has('n') || opts.long.has('dry-run')
if (force && opts.short.has('d') && !dry) kinds.risky = true
} else if (sub === 'rm') {
const dry = opts.short.has('n') || opts.long.has('dry-run')
if (!dry && !opts.long.has('cached') && opts.operands.length > 0) kinds.deletes = true
}
}
// The words before `--` as short options (each letter) and long ones (name before any `=`), and the operands.
function options(args: string[]) {
const short = new Set<string>()
const long = new Set<string>()
const operands: string[] = []
let ended = false
for (const a of args) {
if (ended || a === '-' || !a.startsWith('-')) operands.push(a)
else if (a === '--') ended = true
else if (a.startsWith('--')) long.add(a.slice(2).split('=')[0])
else for (const c of a.slice(1)) short.add(c)
}
return { short, long, operands }
}
// The command a simple command runs: past its variable assignments, the shell's words before a command (`if`,
// `then`, `!`, …) and wrappers with their options. `fed`: xargs gives it what to work on. None when it runs none
// (`command -v rm` only looks rm up).
type Found = { words: string[]; fed: boolean; name: string } // (name: the command's, its folder left out)
function unwrapped(words: string[]): Found | undefined {
let k = 0
let fed = false
for (let guard = 0; guard < 32 && k < words.length; guard++) {
const word = words[k]
if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || PREFIXES.has(word)) {
k++
continue
}
const name = basename(word)
const wrapper = WRAPPERS.get(name)
if (!wrapper) break
fed ||= name === 'xargs'
k++
while (k < words.length && words[k].startsWith('-') && words[k] !== '-') {
const opt = words[k++]
if (opt === '--') break
if (wrapper.looks?.test(opt)) return undefined
if (wrapper.takes.includes(opt)) k++
}
k += wrapper.operands
}
return k < words.length ? { words: k ? words.slice(k) : words, fed, name: basename(words[k]) } : undefined
}
function basename(word: string) {
return word.slice(word.lastIndexOf('/') + 1)
}
// A shell's reading of `source` from `at.i` up to `stop` (`)` closing `$(`, a backquote) or its end: each simple
// command's words (unquoted), what it is fed (here-documents, here-strings) and its pipeline, into `out`.
function parse(source: string, at: { i: number }, stop: string, out: Command[], pipes: { n: number }) {
let words: string[] = []
let input: string[] = []
let word = ''
let has = false // a word has begun (an empty quoted one is a word)
let route: 'arg' | 'file' | 'heredoc' | 'herestring' = 'arg' // where the next word goes, after a redirection
let strip = false // `<<-`: the here-document's lines lose their leading tabs
let depth = 0 // subshells open, `( … )`
let pipe = pipes.n++
const heredocs: { end: string; strip: boolean; into: string[] }[] = []
const endWord = () => {
if (!has) return
if (route === 'arg') words.push(word)
else if (route === 'heredoc') heredocs.push({ end: word, strip, into: input })
else if (route === 'herestring') input.push(word)
route = 'arg'
word = ''
has = false
}
const endCommand = (piped: boolean) => {
endWord()
route = 'arg'
if (words.length || input.length) out.push({ words, input, pipe })
words = []
input = []
if (!piped) pipe = pipes.n++
}
const bodies = () => { // after a line's end: the here-documents it began, each up to its own end line
for (const doc of heredocs.splice(0)) {
const lines: string[] = []
while (at.i < source.length) {
const end = source.indexOf('\n', at.i)
const line = source.slice(at.i, end < 0 ? source.length : end)
at.i = end < 0 ? source.length : end + 1
if ((doc.strip ? line.replace(/^\t+/, '') : line) === doc.end) break
lines.push(line)
}
doc.into.push(lines.join('\n'))
}
}
const substitution = (close: string) => { // `$( … )` or a backquote's: commands of their own
parse(source, at, close, out, pipes)
word += close === ')' ? '$()' : '``'
has = true
}
const quoted = () => { // "…": a backslash keeps only $ ` " \ and a newline; $( … ) and backquotes still run
while (at.i < source.length) {
const c = source[at.i]
if (c === '"') {
at.i++
return
}
if (c === '\\' && '$`"\\\n'.includes(source[at.i + 1] ?? 'x')) {
if (source[at.i + 1] !== '\n') word += source[at.i + 1]
at.i += 2
} else if (c === '$' && source[at.i + 1] === '(') {
at.i += 2
substitution(')')
} else if (c === '`') {
at.i++
substitution('`')
} else {
word += c
at.i++
}
}
}
while (at.i < source.length) {
const c = source[at.i]
const next = source[at.i + 1]
if (stop === '`' && c === '`') {
at.i++
break
}
if (c === '\\') {
if (next !== '\n') {
word += next ?? ''
has = true
}
at.i += 2
} else if (c === "'") {
const end = source.indexOf("'", at.i + 1)
word += source.slice(at.i + 1, end < 0 ? source.length : end)
has = true
at.i = end < 0 ? source.length : end + 1
} else if (c === '"') {
at.i++
has = true
quoted()
} else if (c === '$' && next === '(') {
at.i += 2
substitution(')')
} else if (c === '`') {
at.i++
substitution('`')
} else if ((c === '<' || c === '>') && next === '(') { // <( … ): a command, its output a file
endWord()
at.i += 2
parse(source, at, ')', out, pipes)
} else if (c === '#' && !has) { // a comment, to the line's end
const end = source.indexOf('\n', at.i)
at.i = end < 0 ? source.length : end
} else if (c === ' ' || c === '\t') {
endWord()
at.i++
} else if (c === '\n') {
endCommand(false)
at.i++
bodies()
} else if (c === '&' && next === '>') { // &> and &>>: both outputs to a file
endWord()
route = 'file'
at.i += source[at.i + 2] === '>' ? 3 : 2
} else if (c === ';' || c === '&' || c === '|') {
endCommand(c === '|' && next !== '|') // `|` and `|&` go on in the same pipeline
at.i += (c === '&' && next === '&') || (c === '|' && (next === '|' || next === '&')) ||
(c === ';' && (next === ';' || next === '&')) ? 2 : 1 // (&&, ||, |&, ;;, ;&)
} else if (c === '(') {
endCommand(false)
depth++
at.i++
} else if (c === ')') {
at.i++
if (depth === 0 && stop === ')') break
endCommand(false)
depth = Math.max(0, depth - 1)
} else if (c === '<' || c === '>') { // a redirection: a word of digits before it is its descriptor
if (has && route === 'arg' && /^\d+$/.test(word)) {
word = ''
has = false
} else {
endWord()
}
let op = c
at.i++
while (at.i < source.length && op.length < 3 && '<>&|-'.includes(source[at.i])) op += source[at.i++]
route = op === '<<' || op === '<<-' ? 'heredoc' : op === '<<<' ? 'herestring' : 'file'
strip = op === '<<-'
} else {
word += c
has = true
at.i++
}
}
endCommand(false)
}