rvlib-shipkit 2.2.0 → 2.3.0

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)
+        },
+    }
+}

package/src/review/format.ts

@@ -0,0 +1,150 @@
+// what `sk review inbox`, `show`, `watch`, `next` and `board` print of an item and its answer (wiki build/shipkit/review.md):
+// one record per thread, rectangles normalized and in pixels, a frame note's cut, shot and time into it, and the lines the
+// repo's unit adds (a kind's facts, a source's), handed in as `more` so this module stays pure
+import { aboutText, isFrame, isGallery, isPair, NO_SPEC, placeText, stateOf, unreadBy, verdictOf, type Message, type Rect, type ReviewItem, type Spec, type Subject } from './model.ts'
+import { answererOf, conversationOf, openingOf, type Thread } from './threads.ts'
+
+/** the lines a repo's unit adds under an item's head, and its spec for the words */
+export interface Say {
+    spec: Spec
+    more: (x: ReviewItem) => string[]
+}
+
+const PLAIN: Say = { spec: NO_SPEC, more: () => [] }
+
+const flat = (t: string): string => t.replace(/\s+/g, ' ').trim()
+
+/** a rectangle's clip time, ` at 1.25 s`; nothing on an image */
+const atText = (t: number | undefined): string => (t === undefined ? '' : ` at ${t.toFixed(2)} s`)
+
+/** each reaction to one view or tile: its place by label, its status, its comment */
+const reactionTexts = (x: ReviewItem): string[] =>
+    (verdictOf(x)?.reactions ?? []).map((q) => `${placeText(q, x.item.views)}${q.status ? ` ${q.status}` : ''}${q.comment ? `: ${flat(q.comment)}` : ''}`)
+
+/** one line per feedback, for a monitor: the status, the overall comment, each view's reaction, then each rectangle's comment */
+export function line(x: ReviewItem): string {
+    const f = verdictOf(x)
+    if (!f) return x.item.id
+    const views = x.item.views
+    const many = views.length > 1
+    const rects = f.rects.map((q, i) => `#${i + 1}${many ? ` ${placeText(q, views)}` : ''}${q.side ? ` ${q.side}` : ''}${atText(q.t)} ${flat(q.comment) || '(no comment)'}`)
+    const parts = [...reactionTexts(x), ...rects]
+    return `${x.item.id} ${f.status} "${x.item.title}": ${flat(f.comment) || '(no overall comment)'}${parts.length ? ` | ${parts.join(' | ')}` : ''}`
+}
+
+/** a raised item as the owner names it: `live#85` for a player's report, else its id */
+export const refOf = (x: ReviewItem): string => (x.item.origin.by === 'player' ? `${x.item.origin.server}#${x.item.origin.serverId}` : x.item.id)
+
+/** one owner reply, for a monitor; on an item a card answers, it reads on the card's thread */
+export const replyLine = (x: ReviewItem, m: Message, card: ReviewItem | null = null): string =>
+    `${(card ?? x).item.id} reply "${(card ?? x).item.title}"${card ? ` (on ${refOf(x)})` : ''}: ${flat(m.text ?? '')}${m.image ? ` [image thread/${m.image}]` : ''}`
+
+/** what watch prints of an item, each with the key it prints once under: an unseen feedback (again when sent again), each unseen reply */
+export function watchLines(x: ReviewItem, items: readonly ReviewItem[] = []): { key: string; text: string }[] {
+    const out: { key: string; text: string }[] = []
+    const f = verdictOf(x)
+    if (f && !f.seen) out.push({ key: `${x.item.id}@${f.at}`, text: line(x) })
+    const card = x.item.origin.by === 'agent' ? null : answererOf(x.item.id, items)
+    // the words that raised an item the card answers are what the card answers
+    const opening = card ? openingOf(x) : undefined
+    for (const m of unreadBy(x, 'agent')) if (m !== opening) out.push({ key: `${x.item.id}#${m.id}`, text: replyLine(x, m, card) })
+    return out
+}
+
+/** an auto item waiting on a taker, for its lane's watch: it carries no message to print (what he or a player raised
+ *  prints through its words, an unread reply) */
+export function raisedLine(x: ReviewItem): { key: string; text: string } | null {
+    const o = x.item.origin
+    if (o.by !== 'auto' || stateOf(x, false).state !== 'open') return null
+    return { key: `raised ${x.item.id}`, text: `${x.item.id} raised "${x.item.title}" (auto rule ${o.rule}, key ${o.key}) to ${o.lane}: take it: sk review next --lane ${o.lane}` }
+}
+
+/** an item nobody takes, for a watch and the inbox */
+export const untakenLine = (x: ReviewItem, why: string, lane: string | null): string =>
+    `${x.item.id} untaken "${x.item.title}" (${why}): ask the other sessions (ListAgents, then SendMessage) whether one of them wants it; if none answers, claim it: sk review claim ${x.item.id} --as ${lane ?? '<your lane>'}`
+
+/** one thread as one record: each item the card answers, then the card, its older versions, and with `full` the whole conversation */
+export function threadDetail(t: Thread, dir: string, full = false, say: Say = PLAIN): string {
+    if (t.answers.length === 0 && t.versions.length === 1 && !full) return detail(t.head, dir, false, false, say)
+    const out: string[] = []
+    for (const r of t.answers) out.push(`answers ${refOf(r)}:`, detail(r, dir, false, true, say), '')
+    out.push(detail(t.head, dir, full, false, say))
+    const older = t.versions.slice(1)
+    if (older.length > 0) out.push(`  versions: ${older.map((x) => x.item.id).join(' ')}`)
+    if (full) {
+        const conv = conversationOf(t)
+        if (conv.length > 0) out.push('  thread:')
+        for (const m of conv) out.push(`    ${m.who} ${m.at}${m.on === t.head.item.id ? '' : ` [on ${m.on}]`}: ${flat(m.text ?? '')}${m.image ? ` [image ${dir}/${m.on}/thread/${m.image}]` : ''}`)
+    }
+    return out.join('\n')
+}
+
+/** `m:ss.cc` */
+const clock = (t: number): string => `${Math.floor(t / 60)}:${(t % 60).toFixed(2).padStart(5, '0')}`
+
+/** what the subject says beyond its kind: a frame's cut, shot and time into it */
+function subjectText(s: Subject): string | null {
+    if (isFrame(s)) return `  frame: ${s.trailer}/${s.cut} at ${clock(s.time)} (frame ${s.frame}), shot ${s.shot} at ${s.shotTime.toFixed(2)} s${s.section ? `, section ${s.section}` : ''}`
+    return null
+}
+
+const boxText = (b: { x0: number; y0: number; x1: number; y1: number }): string => `${b.x0},${b.y0}..${b.x1},${b.y1}`
+
+/** a rectangle's world box and the nodes under its middle, when the tool that drew it knew them */
+const rectPlace = (r: Rect): string => (r.world ? ` world ${boxText(r.world)}${r.nodes?.length ? ` nodes ${r.nodes.join(' < ')}` : ''}` : '')
+
+/** a pin or rectangle drawn with the raising words, on the item's image */
+const drawnText = (m: Message): string[] =>
+    (m.rects ?? []).map((q, i) =>
+        q.w === 0 && q.h === 0
+            ? `  pin #${i + 1} ${Math.round(q.x * 100)}%,${Math.round(q.y * 100)}%`
+            : `  #${i + 1} ${q.x.toFixed(3)},${q.y.toFixed(3)} ${q.w.toFixed(3)}x${q.h.toFixed(3)}${rectPlace(q)}: ${q.comment || '(no comment)'}`,
+    )
+
+const raisedBy = (o: ReviewItem['item']['origin']): string =>
+    o.by === 'auto' ? `auto rule ${o.rule} (key ${o.key}) to ${o.lane}` : o.by === 'player' ? `player ${o.player} (${o.server}#${o.serverId})` : o.by === 'owner' ? `owner from ${o.from}${o.lane ? ` to ${o.lane}` : ''}` : o.by
+
+/** one item: a raised one by its state and the raising words, a card by the owner's verdict; `followed`: a later card supersedes or answers it */
+export function detail(x: ReviewItem, dir: string, full = false, followed = false, say: Say = PLAIN): string {
+    const f = verdictOf(x)
+    const r = x.item
+    const head = `  "${r.title}" (${aboutText(r, say.spec)})`
+    const frame = subjectText(r.subject)
+    const sub = [...(frame ? [frame] : []), ...say.more(x)]
+    const replies = unreadBy(x, 'agent').map((m) => `  reply ${m.at}: ${m.text}${m.image ? ` [image ${dir}/${r.id}/thread/${m.image}]` : ''}`)
+    if (r.origin.by !== 'agent') {
+        const st = stateOf(x, followed)
+        const said = x.thread.filter((m) => m.who === 'owner' || m.who === 'player')
+        const words = full ? x.thread.filter((m) => (m.text !== undefined || m.op !== undefined) && m.op !== 'seen') : said.filter((m) => m.text !== undefined && m.op === undefined)
+        const pins = said.filter((m) => m.rects !== undefined).at(-1)
+        const first = r.views[0]
+        const image = first && 'files' in first ? Object.values(first.files) : []
+        return [
+            `${r.id}  ${st.state.toUpperCase()}${st.why ? ` (${st.why})` : ''}  raised by ${raisedBy(r.origin)} ${r.created}${r.commit ? ` at ${r.commit}` : ''}`,
+            head,
+            ...sub,
+            ...(r.origin.by === 'auto' && r.what ? r.what.split('\n').map((l) => `  ${l}`) : []),
+            ...(st.topic ? [`  topic ${st.topic}${st.worker ? `, claimed by ${st.worker}` : ''}${r.origin.by === 'owner' && r.origin.kind ? `, ${r.origin.kind}` : ''}`] : []),
+            ...words.map((m) => `  ${m.who} ${m.at}${m.op ? ` ${m.op}${m.topic ? ` ${m.topic}` : ''}` : ''}: ${m.text ?? m.note ?? ''}${m.fix ? ` (${m.fix.commit})` : ''}`),
+            ...(pins ? drawnText(pins) : []),
+            ...(image.length > 0 ? [`  image: ${image.map((n) => `${dir}/${r.id}/${n}`).join(' ')}`] : []),
+        ].join('\n')
+    }
+    if (!f) return [`${r.id}  NO VERDICT YET`, head, ...sub, ...replies].join('\n')
+    const out = [`${r.id}  ${f.status.toUpperCase()}  ${f.at}`, head, ...sub, `  comment: ${f.comment || '(none)'}`]
+    for (const t of reactionTexts(x)) out.push(`  view ${t}`)
+    const px = (v: number, of: number): number => Math.round(v * of)
+    const views = r.views
+    f.rects.forEach((q, i) => {
+        const v = views[q.view ?? 0] ?? views[0]
+        const size = v && !isGallery(v) ? v.size : { w: 0, h: 0 }
+        const on = q.view ? ` view ${q.view} "${v?.label ?? ''}"` : ''
+        const side = v && !isGallery(v) && isPair(v.files) ? ` ${q.side ?? '?'}` : ''
+        const norm = `${q.x.toFixed(3)},${q.y.toFixed(3)} ${q.w.toFixed(3)}x${q.h.toFixed(3)}`
+        const pix = `${px(q.x, size.w)},${px(q.y, size.h)} ${px(q.w, size.w)}x${px(q.h, size.h)} px`
+        out.push(`  #${i + 1}${on}${side} ${norm} (${pix})${atText(q.t)}: ${q.comment || '(no comment)'}`)
+    })
+    const files = views.flatMap((v) => (isGallery(v) ? v.gallery.map((t) => t.file) : Object.values(v.files)))
+    out.push(`  files: ${files.map((n) => `${dir}/${r.id}/${n}`).join(' ')}`, ...replies)
+    return out.join('\n')
+}

package/src/review/http.ts

@@ -0,0 +1,23 @@
+// the hub's http helpers the review and trailer routes share: an error answer, the cache headers, a file with byte ranges
+import { extname } from 'node:path'
+
+export const TYPES: Record<string, string> = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.webm': 'video/webm', '.mp4': 'video/mp4' }
+export const NO_STORE = { 'Cache-Control': 'no-store' }
+/** an item's files never change once written, nor a kept render under its version: a phone keeps what it fetched */
+export const KEEP = { 'Cache-Control': 'private, max-age=86400' }
+
+export const bad = (e: unknown, status = 400): Response => Response.json({ error: e instanceof Error ? e.message : String(e) }, { status, headers: NO_STORE })
+
+/** a file with byte ranges: a player seeks through them */
+export async function ranged(req: Request, path: string, headers: Record<string, string> = KEEP): Promise<Response> {
+    const file = Bun.file(path)
+    if (!(await file.exists())) return bad(`no ${path.split('/').pop()}`, 404)
+    const size = file.size
+    const head = { 'Content-Type': TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream', 'Accept-Ranges': 'bytes', ...headers }
+    const range = /^bytes=(\d*)-(\d*)$/.exec(req.headers.get('range') ?? '')
+    if (!range) return new Response(file, { headers: { ...head, 'Content-Length': String(size) } })
+    const start = range[1] ? Number(range[1]) : Math.max(0, size - Number(range[2]))
+    const end = range[1] && range[2] ? Math.min(Number(range[2]), size - 1) : size - 1
+    if (start >= size || start > end) return new Response(null, { status: 416, headers: { 'Content-Range': `bytes */${size}` } })
+    return new Response(file.slice(start, end + 1), { status: 206, headers: { ...head, 'Content-Range': `bytes ${start}-${end}/${size}`, 'Content-Length': String(end - start + 1) } })
+}

package/src/review/marks.ts

@@ -0,0 +1,43 @@
+// the owner's marks kept in the store (wiki build/shipkit/review.md, Verbs on the store): a mark is a `rate` message of his
+// on a subject (stars, a mark word, a part's stars, a note); the latest is the mark, the older ones its history. Pure
+import { partyOf, subjectKey, type Message, type ReviewItem, type Spec } from './model.ts'
+
+/** one subject's mark now: its latest whole rate, each part's latest stars, the note said with it */
+export interface SubjectMark {
+    key: string
+    kind: string
+    rate: { stars?: number; mark?: string }
+    parts: Record<string, number>
+    text?: string
+    at: string
+    /** how many marks it was given, the latest included */
+    history: number
+}
+
+/** every subject's mark, the latest first; a mark cleared (no stars, no mark) leaves its subject out */
+export function marksOf(items: readonly ReviewItem[], spec: Spec): SubjectMark[] {
+    const rates: { key: string; kind: string; m: Message }[] = []
+    for (const x of items) {
+        const key = subjectKey(x.item.subject, spec)
+        if (key === null) continue
+        for (const m of x.thread) if (m.rate !== undefined && partyOf(m.who) === 'owner') rates.push({ key, kind: x.item.subject.kind, m })
+    }
+    rates.sort((a, b) => a.m.at.localeCompare(b.m.at) || a.m.id.localeCompare(b.m.id))
+    const out = new Map<string, SubjectMark>()
+    for (const { key, kind, m } of rates) {
+        const r = m.rate ?? {}
+        const e = out.get(key) ?? { key, kind, rate: {}, parts: {}, at: m.at, history: 0 }
+        e.history++
+        e.at = m.at
+        if (r.part) {
+            if (r.stars) e.parts[r.part] = r.stars
+            else delete e.parts[r.part]
+        } else {
+            e.rate = { ...(r.stars ? { stars: r.stars } : {}), ...(r.mark ? { mark: r.mark } : {}) }
+            if (m.text !== undefined) e.text = m.text
+            else delete e.text
+        }
+        out.set(key, e)
+    }
+    return [...out.values()].filter((e) => e.rate.stars !== undefined || e.rate.mark !== undefined || Object.keys(e.parts).length > 0).sort((a, b) => b.at.localeCompare(a.at))
+}

package/src/review/media.ts

@@ -0,0 +1,45 @@
+// the media facts the store and the trailer view read: a clip's length, size and rate (ffprobe), one still of a clip at
+// a time (ffmpeg, through the trailer core's one spawn), an image's size (sharp, loaded only by a writer)
+import { ffmpeg } from '../trailer/ffmpeg.ts'
+
+const FFPROBE = Bun.which('ffprobe') ?? '/opt/homebrew/bin/ffprobe'
+
+export interface Probe {
+    duration: number
+    video: { width: number; height: number; fps: number } | null
+    audio: boolean
+}
+
+/** `30000/1001` → 29.97 */
+const rate = (r: string | undefined): number => {
+    const [a = 0, b = 1] = (r ?? '').split('/').map(Number)
+    return b > 0 && a > 0 ? a / b : 0
+}
+
+/** one ffprobe of a media file; throws when ffprobe cannot read it or finds no length */
+export function probe(file: string): Probe {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-show_entries', 'stream=codec_type,width,height,r_frame_rate:format=duration', '-of', 'json', file], { stdout: 'pipe', stderr: 'pipe' })
+    if (r.exitCode !== 0) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`)
+    const j = JSON.parse(r.stdout.toString()) as { streams?: { codec_type?: string; width?: number; height?: number; r_frame_rate?: string }[]; format?: { duration?: string } }
+    const duration = Number(j.format?.duration)
+    if (!(duration > 0)) throw new Error(`ffprobe ${file}: no length`)
+    const v = j.streams?.find((s) => s.codec_type === 'video')
+    return {
+        duration,
+        video: v?.width && v.height ? { width: v.width, height: v.height, fps: rate(v.r_frame_rate) } : null,
+        audio: j.streams?.some((s) => s.codec_type === 'audio') ?? false,
+    }
+}
+
+/** the first frame at or after `seconds` of a clip, as a png */
+export async function stillAt(video: string, seconds: number, png: string): Promise<void> {
+    await ffmpeg(['-ss', Math.max(0, seconds).toFixed(5), '-i', video, '-frames:v', '1', '-update', '1', '-f', 'image2', '-c:v', 'png', png])
+}
+
+/** an image's size in pixels */
+export async function sizeOf(file: string): Promise<{ w: number; h: number }> {
+    const { default: sharp } = await import('sharp')
+    const m = await sharp(file).metadata()
+    if (!m.width || !m.height) throw new Error(`${file}: no image size`)
+    return { w: m.width, h: m.height }
+}