rvlib-shipkit 2.1.1 → 2.3.0

package/src/reflect/transcript.ts

@@ -0,0 +1,254 @@
+// THE transcript reader: one Claude Code jsonl line in, the events it holds out.
+// `sk reflect` keeps the prompts, `sk time` keeps everything. One parser for
+// both, so a harness shape fixed here is fixed for every reader.
+//
+// A line is one entry. An assistant entry holds ONE content block (thinking,
+// text or tool_use), the user entry after a tool_use holds its tool_result,
+// and the harness writes many user-role entries the human never typed (tool
+// results, command wrappers, compaction summaries, sub-agent hand-backs).
+// Every prompt filter below exists because one of them polluted a real pass.
+
+export type PromptOrigin = 'typed' | 'queued'
+
+/** how a call was allowed: by the human (`user`), by the auto mode
+ *  classifier (a model call before the tool runs), by a rule or a hook, by the
+ *  permission mode, or not recorded */
+export type Perm = 'user' | 'classifier' | 'rule' | 'mode' | ''
+
+export function permOf(d: { source?: unknown; reasonType?: unknown } | undefined): Perm {
+    if (d == null) return ''
+    if (typeof d.source === 'string' && d.source.startsWith('user')) return 'user'
+    if (d.reasonType === 'classifier') return 'classifier'
+    if (d.reasonType === 'mode') return 'mode'
+    return typeof d.source === 'string' ? 'rule' : ''
+}
+
+/** the harness's wrapper around a message relayed into a running agent */
+const RELAYED = /^[^\n]{1,80}? sent (?:a new |a )?message while you were working\b/
+
+/** how a tool call ended, read from its tool_result */
+export type Outcome = 'ok' | 'exit' | 'timeout' | 'blocked' | 'denied' | 'interrupted' | 'error'
+
+export type TranscriptEvent =
+    /** a prompt the human typed; `queued` = typed while the agent worked */
+    | { kind: 'prompt'; at: number; timestamp: string; uuid: string | null; sessionId: string | null; text: string; origin: PromptOrigin }
+    /** a user-role turn nobody typed that wakes the agent: a task notification,
+     *  a sub-agent hand-back, a peer message, a script-driven prompt */
+    | { kind: 'wake'; at: number }
+    /** a message relayed into the agent (the coordinator, the human, another
+     *  session "sent a message while you were working"): it can end a park of
+     *  hours after the agent handed back */
+    | { kind: 'message'; at: number }
+    | { kind: 'use'; at: number; id: string; name: string; detail: string }
+    /** `perm`: how the call was allowed; `user` = it waited for the human, so its time is his */
+    | { kind: 'result'; at: number; id: string; outcome: Outcome; code: number | null; perm: Perm }
+    /** an assistant text block: the agent talking, which can end its turn */
+    | { kind: 'reply'; at: number }
+
+// wrappers the harness injects as user-role entries: none of them are typed
+const NOISE_PREFIXES = [
+    '<local-command-caveat>',
+    '<local-command-stdout>',
+    '<command-name>',
+    '<command-message>',
+    '<system-reminder>',
+    '<task-notification>',
+    'Caveat: The messages below',
+    '[Request interrupted',
+    'This session is being continued from a previous conversation',
+    // model output parked in the queue (or wrapped as a meta entry): a
+    // sub-agent's hand-back, and a message another Claude session sent
+    '<agent-message',
+    '<cross-session-message',
+    'Another Claude session sent a message',
+]
+
+export function isTypedPrompt(text: string): boolean {
+    const trimmed = text.trim()
+    if (trimmed === '') return false
+    return !NOISE_PREFIXES.some((p) => trimmed.startsWith(p))
+}
+
+type Block = { type?: unknown; text?: unknown; id?: unknown; name?: unknown; input?: unknown; tool_use_id?: unknown; is_error?: unknown; content?: unknown }
+
+export type RawEntry = {
+    type?: unknown
+    entrypoint?: unknown
+    uuid?: unknown
+    timestamp?: unknown
+    sessionId?: unknown
+    isMeta?: unknown
+    isSidechain?: unknown
+    isCompactSummary?: unknown
+    /** `peer` on a sub-agent hand-back or another session's message */
+    turnOrigin?: unknown
+    /** queue-operation entries only */
+    operation?: unknown
+    content?: unknown
+    message?: { role?: unknown; content?: unknown }
+    toolUseResult?: unknown
+    /** on a tool_result entry: who allowed the call (`config`, `user_temporary`, …) */
+    permissionDecision?: { source?: unknown; reasonType?: unknown }
+}
+
+const stripReminders = (text: string): string => text.replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, '').trim()
+
+/** the user text of a user entry, reminders stripped, a slash command's typed
+ *  args rescued; null when it carries no text at all (a pure tool_result turn).
+ *  Content is a string for a plain prompt, an array of blocks when the message
+ *  carried pastes or attachments (the text blocks in there are still his). */
+function userText(entry: RawEntry): string | null {
+    const content = entry.message?.content
+    let text: string
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+        const parts = (content as Block[]).filter((b) => b?.type === 'text' && typeof b?.text === 'string').map((b) => b.text as string)
+        if (parts.length === 0) return null
+        text = parts.join('\n')
+    } else return null
+    text = stripReminders(text)
+    // a slash-command entry is a harness WRAPPER around typed text:
+    // <command-name>/cmd</command-name><command-args>THE TEXT</command-args>.
+    // Dropping the whole entry throws away real instructions and repro pastes.
+    const args = text.match(/<command-args>([\s\S]*?)<\/command-args>/)
+    if (args?.[1] != null) {
+        const body = args[1].trim()
+        if (body === '') return ''
+        const name = text.match(/<command-name>([\s\S]*?)<\/command-name>/)
+        text = name?.[1] == null ? body : `${name[1].trim()} ${body}`
+    }
+    return text
+}
+
+/** the typed prompt out of a parsed user entry, or null when he did not type
+ *  it. isSidechain = a subagent prompt the AGENT wrote; isMeta and
+ *  isCompactSummary = harness-generated; entrypoint sdk-cli = a script drove it */
+export function typedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'user') return null
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true) return null
+    if (entry.entrypoint === 'sdk-cli') return null
+    if (entry.message?.role !== 'user') return null
+    const text = userText(entry)
+    if (text == null || !isTypedPrompt(text)) return null
+    return text
+}
+
+/** A prompt he typed while the agent was still working: the harness parks it as
+ *  `{type:'queue-operation', operation:'enqueue', content}` and, if the run ends
+ *  first, it may NEVER become a user message. Skipping these loses exactly the
+ *  mid-flight corrections and standing conventions a retrospective is for */
+export function queuedPromptOf(entry: RawEntry): string | null {
+    if (entry.type !== 'queue-operation' || entry.operation !== 'enqueue') return null
+    if (typeof entry.content !== 'string') return null
+    const text = stripReminders(entry.content)
+    return isTypedPrompt(text) ? text : null
+}
+
+const BASH_EXIT = /^Exit code (\d+)/
+const BLOCKED = [/^PreToolUse:/, /^Permission to use /, /^Permission for this action was denied/, /auto mode classifier/i, /hook error/i]
+
+/** how a tool call ended. The harness marks every failure `is_error`, and the
+ *  text says which kind: a non zero exit, a hook or permission block, the
+ *  human saying no, a timeout (now moved to the background), anything else */
+export function outcomeOf(r: { isError: boolean; text: string; extra: unknown }): { outcome: Outcome; code: number | null } {
+    const extra = r.extra != null && typeof r.extra === 'object' ? (r.extra as Record<string, unknown>) : {}
+    if (typeof extra.timedOutAfterMs === 'number' || /^Command timed out after/.test(r.text)) return { outcome: 'timeout', code: null }
+    if (extra.interrupted === true || r.text.startsWith('[Request interrupted')) return { outcome: 'interrupted', code: null }
+    if (!r.isError) return { outcome: 'ok', code: null }
+    const exit = BASH_EXIT.exec(r.text)
+    if (exit?.[1] != null) return { outcome: 'exit', code: Number(exit[1]) }
+    if (/^The user doesn't want to proceed/.test(r.text) || /^The user (rejected|denied)/.test(r.text)) return { outcome: 'denied', code: null }
+    if (BLOCKED.some((re) => re.test(r.text))) return { outcome: 'blocked', code: null }
+    return { outcome: 'error', code: null }
+}
+
+const DETAIL_MAX = 400
+const clip = (s: string): string => (s.length > DETAIL_MAX ? s.slice(0, DETAIL_MAX) : s)
+
+/** a long command keeps its head and its tail: what runs after a heredoc
+ *  (`cat > x.ts <<EOF … EOF` then `bun x.ts`) is at the end */
+const clipMiddle = (s: string): string => (s.length > 2 * DETAIL_MAX ? `${s.slice(0, DETAIL_MAX)}\n${s.slice(-DETAIL_MAX)}` : s)
+
+/** the one input field that says what a call did: the Bash command, the
+ *  sub-agent type and its description, the skill, the url */
+export function detailOf(name: string, input: unknown): string {
+    const i = input != null && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+    const str = (k: string): string => (typeof i[k] === 'string' ? (i[k] as string) : '')
+    if (name === 'Bash') return clipMiddle(str('command'))
+    if (name === 'Agent' || name === 'Task') return clip(`${str('subagent_type') || 'general-purpose'}: ${str('description')}`)
+    if (name === 'Skill') return clip(str('skill'))
+    if (name === 'WebFetch') return clip(str('url'))
+    if (name === 'Monitor' || name === 'TaskOutput' || name === 'TaskStop') return clip(str('description') || str('task_id'))
+    return ''
+}
+
+const resultText = (content: unknown): string => {
+    if (typeof content === 'string') return content
+    if (Array.isArray(content)) {
+        const first = (content as Block[]).find((b) => b?.type === 'text' && typeof b.text === 'string')
+        return first == null ? '' : (first.text as string)
+    }
+    return ''
+}
+
+// the entry types that carry nothing a reader wants and make most of the
+// bytes (api-request alone is about 80 percent of a long session): a line
+// that starts with one of these is skipped before JSON.parse
+const KEPT_TYPE_PREFIXES = ['{"type":"user"', '{"type":"assistant"', '{"type":"queue-operation"']
+
+/** every event one transcript line holds; [] for anything else, a truncated
+ *  tail line of a live session included */
+export function readTranscriptLine(line: string): TranscriptEvent[] {
+    if (line.startsWith('{"type":"') && !KEPT_TYPE_PREFIXES.some((p) => line.startsWith(p))) return []
+    let parsed: unknown
+    try {
+        parsed = JSON.parse(line)
+    } catch {
+        return []
+    }
+    if (parsed == null || typeof parsed !== 'object') return []
+    return eventsOf(parsed as RawEntry)
+}
+
+export function eventsOf(entry: RawEntry): TranscriptEvent[] {
+    const timestamp = typeof entry.timestamp === 'string' ? entry.timestamp : ''
+    const at = Date.parse(timestamp)
+    const uuid = typeof entry.uuid === 'string' ? entry.uuid : null
+    const sessionId = typeof entry.sessionId === 'string' ? entry.sessionId : null
+    const prompt = (text: string, origin: PromptOrigin): TranscriptEvent => ({ kind: 'prompt', at, timestamp, uuid, sessionId, text, origin })
+
+    if (entry.type === 'queue-operation') {
+        const q = queuedPromptOf(entry)
+        return q == null ? [] : [prompt(q, 'queued')]
+    }
+    if (Number.isNaN(at) && entry.type !== 'user') return []
+    if (entry.type === 'assistant') {
+        const blocks = Array.isArray(entry.message?.content) ? (entry.message.content as Block[]) : []
+        const out: TranscriptEvent[] = []
+        for (const b of blocks) {
+            if (b?.type === 'tool_use' && typeof b.id === 'string' && typeof b.name === 'string') out.push({ kind: 'use', at, id: b.id, name: b.name, detail: detailOf(b.name, b.input) })
+            else if (b?.type === 'text') out.push({ kind: 'reply', at })
+        }
+        return out
+    }
+    if (entry.type !== 'user') return []
+    const out: TranscriptEvent[] = []
+    const content = entry.message?.content
+    if (Array.isArray(content)) {
+        const perm = permOf(entry.permissionDecision)
+        for (const b of content as Block[]) {
+            if (b?.type !== 'tool_result' || typeof b.tool_use_id !== 'string' || Number.isNaN(at)) continue
+            const o = outcomeOf({ isError: b.is_error === true, text: resultText(b.content), extra: entry.toolUseResult })
+            out.push({ kind: 'result', at, id: b.tool_use_id, ...o, perm })
+        }
+    }
+    const typed = typedPromptOf(entry)
+    if (typed != null) out.push(prompt(typed, 'typed'))
+    else if (out.length === 0 && !Number.isNaN(at) && entry.isMeta === true && RELAYED.test(userText(entry) ?? '')) out.push({ kind: 'message', at })
+    // a peer message (a sub-agent hand-back, another session's message) is written isMeta, yet it wakes the agent
+    else if (out.length === 0 && !Number.isNaN(at) && (entry.isMeta !== true || entry.turnOrigin === 'peer') && entry.isCompactSummary !== true) {
+        const text = userText(entry)
+        if (text != null && text !== '') out.push({ kind: 'wake', at })
+    }
+    return out
+}

package/src/review/anim.ts

@@ -0,0 +1,228 @@
+// a card's before and after as a looping animation to send (wiki build/shipkit/review.md, Verbs on the store): the one
+// function behind the hub's « animation » and `sk review anim`. One cycle is drawn by ffmpeg's own filters (no per pixel
+// expression: a card renders in a few seconds), an mp4 then repeats it with no second encode
+import { createCanvas, GlobalFonts } from '@napi-rs/canvas'
+import { existsSync, mkdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { ffmpeg } from '../trailer/ffmpeg.ts'
+import { sizeOf } from './media.ts'
+import { isGallery, isPair } from './model.ts'
+import { imageFile, readItem } from './store.ts'
+
+export const ANIM_MODES = ['cut', 'fade', 'wipe'] as const
+export type AnimMode = (typeof ANIM_MODES)[number]
+export const ANIM_FORMATS = ['mp4', 'gif'] as const
+export type AnimFormat = (typeof ANIM_FORMATS)[number]
+/** the corner labels' language, or none */
+export const ANIM_LABELS = ['en', 'fr', 'none'] as const
+export type AnimLabels = (typeof ANIM_LABELS)[number]
+const LABEL_WORDS: Record<Exclude<AnimLabels, 'none'>, [string, string]> = { en: ['before', 'after'], fr: ['avant', 'après'] }
+
+export interface AnimAsk {
+    /** the view's index on the card, 0 the first */
+    view: number
+    mode: AnimMode
+    format: AnimFormat
+    labels: AnimLabels
+    /** a font file the labels are drawn in; the system sans serif without one */
+    font?: string
+}
+
+export interface Anim {
+    file: string
+    /** the name it is saved under: the card's title in ascii, the view past the first, the mode */
+    name: string
+    /** 0 when the cached file served */
+    ms: number
+}
+
+/** bump when a mode's look changes: every cached animation draws again */
+const LOOK = 1
+
+/** seconds: a hold on one image, the cross fade, the wipe */
+const HOLD = 1.2
+const FADE = 0.5
+const WIPE_HOLD = 1.0
+const WIPE = 1.2
+const LOOPS = 3
+const MP4 = { fps: 30, maxW: 1920, crf: 20 }
+/** a gif stays a few MB: at most this wide, fewer frames (20 a second: a whole 5 cs each) */
+const GIF = { fps: 20, maxW: 960 }
+
+/** the cycle's length in seconds */
+const cycleOf = (mode: AnimMode): number => (mode === 'cut' ? 2 * HOLD : mode === 'fade' ? 2 * (HOLD + FADE) : 2 * (WIPE_HOLD + WIPE))
+
+export const isAnimMode = (s: unknown): s is AnimMode => ANIM_MODES.includes(s as AnimMode)
+export const isAnimFormat = (s: unknown): s is AnimFormat => ANIM_FORMATS.includes(s as AnimFormat)
+export const isAnimLabels = (s: unknown): s is AnimLabels => ANIM_LABELS.includes(s as AnimLabels)
+
+/** the title as a file name: ascii, lowercase, words joined by a hyphen */
+export const asciiName = (s: string, max = 60): string =>
+    s
+        .normalize('NFKD')
+        .replace(/[^\x20-\x7e]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .slice(0, max)
+        .replace(/^-+|-+$/g, '') || 'before-after'
+
+const fonts = new Set<string>()
+/** one corner label, cream on a soft dark pill, as a png of its own size */
+function labelPng(text: string, px: number, out: string, font: string | undefined): void {
+    let face = 'sans-serif'
+    if (font) {
+        if (!fonts.has(font)) {
+            if (!existsSync(font)) throw new Error(`anim.font ${font}: no such file`)
+            GlobalFonts.registerFromPath(font, 'ReviewAnim')
+            fonts.add(font)
+        }
+        face = 'ReviewAnim'
+    }
+    const probe = createCanvas(4, 4).getContext('2d')
+    probe.font = `800 ${px}px ${face}`
+    const padX = Math.round(px * 0.7)
+    const padY = Math.round(px * 0.32)
+    const w = Math.ceil(probe.measureText(text).width) + 2 * padX
+    const h = Math.round(px * 1.25) + 2 * padY
+    const c = createCanvas(w, h)
+    const g = c.getContext('2d')
+    g.fillStyle = 'rgba(42, 27, 15, 0.62)'
+    g.beginPath()
+    g.roundRect(0, 0, w, h, h / 2)
+    g.fill()
+    g.font = `800 ${px}px ${face}`
+    g.fillStyle = '#FCEFD4'
+    g.textAlign = 'center'
+    g.textBaseline = 'middle'
+    g.fillText(text, w / 2, h / 2 + px * 0.04)
+    writeFileSync(out, c.toBuffer('image/png'))
+}
+
+/** the share of the after shown at time `t` of a wipe, as an ffmpeg expression: hold, an eased wipe, hold, back */
+function shownExpr(): string {
+    const u = `mod(t,${cycleOf('wipe')})`
+    const ease = (v: string): string => `(${v})*(${v})*(3-2*(${v}))`
+    const a = WIPE_HOLD
+    const b = a + WIPE
+    const c = b + WIPE_HOLD
+    return `if(lt(${u},${a}),0,if(lt(${u},${b}),${ease(`(${u}-${a})/${WIPE}`)},if(lt(${u},${c}),1,1-${ease(`(${u}-${c})/${WIPE}`)})))`
+}
+
+/** the filter graph of one cycle: [0] before and [1] after scaled, labelled ([2] and [3]), then the mode, out [v]; `pix`
+ *  the frames' format through the mode: the mp4's own yuv420p (half the work of rgb at 1080p), rgb for a gif's palette */
+function graph(mode: AnimMode, w: number, h: number, fps: number, labels: boolean, pix: 'yuv420p' | 'gbrp'): string {
+    const m = Math.round(w * 0.018)
+    const prep = (i: number, label: number, at: string, out: string): string =>
+        `[${i}:v]scale=${w}:${h}:flags=lanczos,setsar=1,format=rgba${labels ? `[p${i}];[p${i}][${label}:v]overlay=${at}` : ''},format=${pix}[${out}]`
+    // a wipe's after comes in from the left, so its label takes the top left and the before's the bottom right
+    const [early, late] = [`${m}:${m}`, `W-w-${m}:H-h-${m}`]
+    const parts = mode === 'wipe' ? [prep(0, 2, late, 'b'), prep(1, 3, early, 'a')] : [prep(0, 2, early, 'b'), prep(1, 3, late, 'a')]
+    const cut = (from: string, d: number, out: string): string => `[${from}]trim=duration=${d},setpts=PTS-STARTPTS[${out}]`
+    if (mode === 'cut') {
+        parts.push(cut('b', HOLD, 'x0'), cut('a', HOLD, 'x1'), '[x0][x1]concat=n=2:v=1:a=0[v]')
+    } else if (mode === 'fade') {
+        parts.push(
+            '[b]split[b1][b2]',
+            cut('b1', HOLD + FADE, 'x0'),
+            cut('a', 2 * FADE + HOLD, 'x1'),
+            cut('b2', FADE, 'x2'),
+            `[x0][x1]xfade=transition=fade:duration=${FADE}:offset=${HOLD}[y]`,
+            `[y][x2]xfade=transition=fade:duration=${FADE}:offset=${2 * HOLD + FADE}[v]`,
+        )
+    } else {
+        // the before keeps the right of the seam: a mask black then white, twice as wide, slid by a crop
+        const d = cycleOf('wipe')
+        const shown = shownExpr()
+        const seam = `${w}*${shown}`
+        const line = Math.max(2, Math.round(w / 640))
+        const glow = line + 4
+        // the line only while the seam moves: off screen on a hold
+        const at = (lw: number): string => `if(gt(${shown},0)*lt(${shown},1),${seam}-${lw / 2},-100)`
+        parts.push(
+            `color=c=white:s=${w}x${h}:r=${fps}:d=${d}[mw]`,
+            `color=c=black:s=${w}x${h}:r=${fps}:d=${d}[mb]`,
+            `[mb][mw]hstack,format=gray,crop=w=${w}:h=${h}:x='${w}-(${seam})':y=0[mask]`,
+            '[b][mask]alphamerge[ba]',
+            `[a][ba]overlay=0:0:shortest=1[c0]`,
+            `color=c=black@0.28:s=${glow}x${h}:r=${fps}:d=${d},format=rgba[g]`,
+            `color=c=0xFFF6DA:s=${line}x${h}:r=${fps}:d=${d},format=rgba[l]`,
+            `[c0][g]overlay=x='${at(glow)}':y=0:shortest=1[c1]`,
+            `[c1][l]overlay=x='${at(line)}':y=0:shortest=1[v]`,
+        )
+    }
+    return parts.join(';')
+}
+
+const making = new Map<string, Promise<Anim>>()
+
+/** the animation of view `ask.view` of card `id`, made once and kept under `<dir>/.anims/` (readAll skips dot names) */
+export function pairAnimation(dir: string, id: string, ask: AnimAsk): Promise<Anim> {
+    const x = readItem(dir, id)
+    if (!x) return Promise.reject(new Error(`no card ${id}`))
+    const v = x.item.views[ask.view]
+    if (!v) return Promise.reject(new Error(`card ${id} has no view ${ask.view} (it has ${x.item.views.length})`))
+    if (isGallery(v) || !isPair(v.files)) return Promise.reject(new Error(`view ${ask.view} of ${id} is not a before and after`))
+    if (v.clip) return Promise.reject(new Error(`view ${ask.view} of ${id} is a pair of clips: no animation`))
+    if (v.audio) return Promise.reject(new Error(`view ${ask.view} of ${id} is a pair of sounds: no animation`))
+    const before = imageFile(dir, id, v.files.before)
+    const after = imageFile(dir, id, v.files.after)
+    if (!before || !after) return Promise.reject(new Error(`view ${ask.view} of ${id}: an image is missing`))
+    const viewPart = ask.view > 0 ? `-${asciiName(v.label || `view-${ask.view + 1}`, 30)}` : ''
+    const name = `${asciiName(x.item.title)}${viewPart}-${ask.mode}.${ask.format}`
+    const out = join(dir, '.anims', id, `L${LOOK}-v${ask.view}-${ask.mode}-${ask.labels}.${ask.format}`)
+    const newest = Math.max(statSync(before).mtimeMs, statSync(after).mtimeMs)
+    if (existsSync(out) && statSync(out).mtimeMs >= newest) return Promise.resolve({ file: out, name, ms: 0 })
+    const pending = making.get(out)
+    if (pending) return pending
+    const job = render(before, after, out, v.size, ask)
+        .then((ms) => ({ file: out, name, ms }))
+        .finally(() => making.delete(out))
+    making.set(out, job)
+    return job
+}
+
+/** the same animation from two images of one size, no card: drawn each time under `scratch`, named after the after */
+export async function fileAnimation(before: string, after: string, ask: AnimAsk, scratch: string): Promise<Anim> {
+    const [b, a] = await Promise.all([sizeOf(before), sizeOf(after)])
+    if (b.w !== a.w || b.h !== a.h) throw new Error(`before ${b.w}x${b.h} and after ${a.w}x${a.h} differ in size`)
+    const name = `${asciiName(basename(after).replace(/\.[a-z]+$/i, ''))}-${ask.mode}.${ask.format}`
+    mkdirSync(scratch, { recursive: true })
+    const out = join(scratch, `${process.pid}-${name}`)
+    const ms = await render(resolve(before), resolve(after), out, a, ask)
+    return { file: out, name, ms }
+}
+
+/** draws one animation into `out`; its time in ms */
+async function render(before: string, after: string, out: string, size: { w: number; h: number }, ask: AnimAsk): Promise<number> {
+    const t0 = performance.now()
+    const spec = ask.format === 'mp4' ? MP4 : GIF
+    const w = Math.min(spec.maxW, size.w) & ~1
+    const h = Math.round((size.h * w) / size.w / 2) * 2
+    const work = `${out}.${process.pid}.tmp`
+    mkdirSync(work, { recursive: true })
+    try {
+        const d = cycleOf(ask.mode)
+        const still = (f: string): string[] => ['-loop', '1', '-framerate', String(spec.fps), '-t', String(d), '-i', f]
+        const inputs = [...still(before), ...still(after)]
+        if (ask.labels !== 'none') {
+            const px = Math.max(14, Math.round(w * 0.019))
+            const [was, now] = LABEL_WORDS[ask.labels]
+            labelPng(was, px, join(work, 'before.png'), ask.font)
+            labelPng(now, px, join(work, 'after.png'), ask.font)
+            inputs.push('-i', join(work, 'before.png'), '-i', join(work, 'after.png'))
+        }
+        const g = graph(ask.mode, w, h, spec.fps, ask.labels !== 'none', ask.format === 'mp4' ? 'yuv420p' : 'gbrp')
+        const done = join(work, `out.${ask.format}`)
+        if (ask.format === 'gif') {
+            await ffmpeg([...inputs, '-filter_complex', `${g};[v]split[s0][s1];[s0]palettegen=max_colors=256:stats_mode=full[pal];[s1][pal]paletteuse=dither=bayer:bayer_scale=4[o]`, '-map', '[o]', '-t', String(d), '-r', String(spec.fps), '-loop', '0', done])
+        } else {
+            const one = join(work, 'one.mp4')
+            await ffmpeg([...inputs, '-filter_complex', `${g};[v]format=yuv420p[o]`, '-map', '[o]', '-t', String(d), '-r', String(spec.fps), '-an', '-c:v', 'libx264', '-crf', String(MP4.crf), '-preset', 'veryfast', '-pix_fmt', 'yuv420p', one])
+            await ffmpeg(['-stream_loop', String(LOOPS - 1), '-i', one, '-c', 'copy', '-movflags', '+faststart', done])
+        }
+        renameSync(done, out)
+        return Math.round(performance.now() - t0)
+    } finally {
+        rmSync(work, { recursive: true, force: true })
+    }
+}

package/src/review/auto.ts

@@ -0,0 +1,141 @@
+// auto rules (wiki build/shipkit/review.md, A project's parts): a rule of the repo's review unit answers on a clock, and
+// its answer is raised as an item to a lane, open from the start. One open item a rule and key. The hub's daemon runs
+// them (startAuto), `sk review auto` reads their logs and runs one now
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { stateOf, type ReviewItem } from './model.ts'
+import { raiseItem } from './store.ts'
+import { followedIds } from './threads.ts'
+import type { AutoRule, Raise } from './unit.ts'
+
+/** a `when` slower than this prints a loud line: it runs inside the daemon */
+export const AUTO_BUDGET_MS = 50
+
+/** what one raise came to: a new item, held by the open item of its rule and key, or a dry run's */
+export type Outcome = { raise: Raise; key: string } & ({ raised: string } | { held: string } | { dry: true })
+
+/** one rule's log, `.shipkit/review-auto/<id>.json`: its last run and answer, the last item it raised */
+export interface AutoLog {
+    at: string
+    ms: number
+    answer: string
+    error?: string
+    lastRaised?: { id: string; at: string }
+}
+
+/** the logs sit beside the store, out of its watch */
+export const autoLogDir = (dir: string): string => join(dir, '..', 'review-auto')
+
+export function readAutoLog(dir: string, id: string): AutoLog | null {
+    try {
+        return JSON.parse(readFileSync(join(autoLogDir(dir), `${id}.json`), 'utf8')) as AutoLog
+    } catch {
+        return null
+    }
+}
+
+function writeAutoLog(dir: string, id: string, log: AutoLog): void {
+    const folder = autoLogDir(dir)
+    mkdirSync(folder, { recursive: true })
+    const file = join(folder, `${id}.json`)
+    writeFileSync(`${file}.tmp`, `${JSON.stringify(log, null, 2)}\n`)
+    renameSync(`${file}.tmp`, file)
+}
+
+export function everyMs(every: string): number {
+    const m = /^(\d+(?:\.\d+)?)m$/.exec(every)
+    const n = m ? Number(m[1]) : Number.NaN
+    if (!(n > 0)) throw new Error(`every: « ${every} » is no period, give minutes like '10m'`)
+    return n * 60_000
+}
+
+/** the item of this rule and key that is not closed, the one that holds a new raise */
+function openOf(items: readonly ReviewItem[], rule: string, key: string): ReviewItem | undefined {
+    const followed = followedIds(items)
+    return items.find((x) => {
+        const o = x.item.origin
+        return o.by === 'auto' && o.rule === rule && o.key === key && stateOf(x, followed.has(x.item.id)).state !== 'closed'
+    })
+}
+
+const answerText = (outcomes: readonly Outcome[]): string =>
+    outcomes.length === 0 ? 'nothing' : outcomes.map((o) => ('raised' in o ? `raised ${o.raised}` : 'held' in o ? `held by ${o.held}` : `would raise « ${o.raise.title} »`)).join('; ')
+
+/** one rule evaluated now: its raises written as items, unless an open one holds the key; `dry` writes nothing, the log
+ *  included. A rule that throws is logged and rethrown */
+export async function runRule(dir: string, rule: AutoRule, o: { items: readonly ReviewItem[]; now?: Date; dry?: boolean }): Promise<Outcome[]> {
+    const now = o.now ?? new Date()
+    const before = readAutoLog(dir, rule.id)
+    const t0 = performance.now()
+    let answer: Raise | readonly Raise[] | null
+    try {
+        answer = rule.when({ items: o.items, now })
+    } catch (e) {
+        if (!o.dry) writeAutoLog(dir, rule.id, { ...before, at: now.toISOString(), ms: performance.now() - t0, answer: 'threw', error: String(e) })
+        throw e
+    }
+    const ms = performance.now() - t0
+    if (ms > AUTO_BUDGET_MS) console.error(`FAIL: review auto: rule ${rule.id} took ${ms.toFixed(0)} ms, past ${AUTO_BUDGET_MS} ms: it runs inside the daemon`)
+    const raises: readonly Raise[] = answer === null ? [] : Array.isArray(answer) ? answer : [answer as Raise]
+    const outcomes: Outcome[] = []
+    const taken = new Map<string, string>()
+    for (const raise of raises) {
+        const key = raise.key ?? rule.id
+        const held = taken.get(key) ?? openOf(o.items, rule.id, key)?.item.id
+        if (held !== undefined) outcomes.push({ raise, key, held })
+        else if (o.dry) {
+            outcomes.push({ raise, key, dry: true })
+            taken.set(key, 'this run')
+        } else {
+            const x = await raiseItem(dir, { subject: raise.subject, origin: { by: 'auto', rule: rule.id, key, lane: raise.lane }, title: raise.title, what: raise.what, now })
+            taken.set(key, x.item.id)
+            outcomes.push({ raise, key, raised: x.item.id })
+        }
+    }
+    if (!o.dry) {
+        const raised = outcomes.flatMap((x) => ('raised' in x ? [x.raised] : []))
+        const last = raised.at(-1)
+        const lastRaised = last !== undefined ? { id: last, at: now.toISOString() } : before?.lastRaised
+        writeAutoLog(dir, rule.id, { at: now.toISOString(), ms, answer: answerText(outcomes), ...(lastRaised ? { lastRaised } : {}) })
+    }
+    return outcomes
+}
+
+/** when a rule runs next: once its last run is `every` old, never before `from` */
+export const nextRun = (rule: AutoRule, log: AutoLog | null, from: number): number => Math.max(from, log ? Date.parse(log.at) + everyMs(rule.every) : from)
+
+/** one scheduled run: what it raised printed, a rule that throws printed loud and skipped, never thrown on */
+export async function autoTick(dir: string, rule: AutoRule, items: () => readonly ReviewItem[], say: (l: string) => void = console.log): Promise<void> {
+    try {
+        for (const o of await runRule(dir, rule, { items: items() })) if ('raised' in o) say(`review auto: ${rule.id} raised ${o.raised} to ${o.raise.lane}: ${o.raise.title}`)
+    } catch (e) {
+        console.error(`FAIL: review auto: rule ${rule.id} threw, skipped until its next run: ${String(e)}`)
+    }
+}
+
+/** a schedule of a store's rules: each on its own timer, never holding the process open, the first run once its last is
+ *  `every` old. `stop` clears every timer (the unit changed, the hub closed) */
+export function startAuto(dir: string, rules: readonly AutoRule[], items: () => readonly ReviewItem[]): { stop(): void } {
+    const timers = new Set<ReturnType<typeof setTimeout>>()
+    let stopped = false
+    // a start pays its boot first: no rule runs in its first seconds
+    const from = Date.now() + 5_000
+    for (const rule of rules) {
+        const tick = (): void =>
+            void autoTick(dir, rule, items).then(() => {
+                if (stopped) return
+                const t = setTimeout(tick, everyMs(rule.every))
+                t.unref()
+                timers.add(t)
+            })
+        const t = setTimeout(tick, nextRun(rule, readAutoLog(dir, rule.id), from) - Date.now())
+        t.unref()
+        timers.add(t)
+    }
+    return {
+        stop(): void {
+            stopped = true
+            for (const t of timers) clearTimeout(t)
+        },
+    }
+}