rvlib-shipkit 2.1.0 → 2.2.0

package/src/suite/judge-suites.ts

@@ -335,6 +335,18 @@ export function aloneRunsNeeded(suspects: Timed[], parallelCpu: Record<string, n
  *  every (fail) line under no header of its own: it closes the last file */
 export const BUN_RECAP = /^\s*\d+ tests? failed:\s*$/
 
+/** the banner bun prints under a file header for an error thrown outside
+ *  any test (a top level throw, a throw inside a describe callback), then a
+ *  rule, the code frame, the error, the stack and a closing rule */
+export const BETWEEN_TESTS = '# Unhandled error between tests'
+export const BUN_RULE = /^-{20,}$/
+/** the line that carries an error's message: bun's own `error:` and a named
+ *  error class (`ReferenceError: x is not defined`) */
+const ERROR_LINE = /^\s*(?:error|[A-Z]\w*(?:Error|Exception)): /
+const BETWEEN_WORDS = 'an unhandled error between tests'
+/** the line that opens a file in bun's report: its path and a colon */
+const HEADER = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/
+
 /** the suites with a failing test, read off bun's report: a file that failed
  *  prints its path as a header line, then its `(fail)` lines under it. A
  *  passing file prints nothing at all in a piped run, which is why this reads
@@ -343,39 +355,73 @@ export function failedSuites(output: string): string[] {
     const out = new Set<string>()
     let cur: string | null = null
     for (const line of output.split('\n')) {
-        const head = line.match(/^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/)
+        const head = line.match(HEADER)
         if (head != null) { cur = normSuitePath(head[1]!); continue }
         if (BUN_RECAP.test(line)) { cur = null; continue }
         // a file that cannot load prints no `(fail)` line, only this banner
-        if (cur != null && (/^\(fail\) /.test(line) || line.startsWith('# Unhandled error between tests'))) out.add(cur)
+        if (cur != null && (/^\(fail\) /.test(line) || line.startsWith(BETWEEN_TESTS))) out.add(cur)
     }
     return [...out]
 }
 
+/** the error line inside the banner block that starts at `from`, before its closing rule */
+function blockError(lines: string[], from: number): string | null {
+    let rules = 0
+    for (let j = from; j < lines.length && rules < 2; j++) {
+        const line = lines[j]!.trim()
+        if (BUN_RULE.test(line)) { rules++; continue }
+        if (HEADER.test(line)) return null
+        if (ERROR_LINE.test(line)) return line
+    }
+    return null
+}
+
 /** the FIRST failure of each failing suite, read off the same report as
- *  failedSuites: its `(fail)` line, timing dropped, with the first `error:`
- *  line bun printed before it in that file. What the record keeps so a page
- *  can say why a file is red without a rerun */
+ *  failedSuites: its `(fail)` line, timing dropped, with the first error line
+ *  bun printed before it in that file, or the error inside the banner of one
+ *  that threw outside any test. What the record keeps so a page can say why a
+ *  file is red without a rerun */
 export function failLines(output: string): Map<string, string> {
     const out = new Map<string, string>()
+    const lines = output.split('\n')
     let cur: string | null = null
     let err: string | null = null
-    for (const raw of output.split('\n')) {
-        const line = raw.trimEnd()
-        const head = line.match(/^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/)
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]!.trimEnd()
+        const head = line.match(HEADER)
         if (head != null) { cur = normSuitePath(head[1]!); err = null; continue }
         if (BUN_RECAP.test(line)) { cur = null; continue }
         if (cur == null || out.has(cur)) continue
-        if (err == null && /^\s*error: /.test(line)) err = line.trim()
+        if (err == null && ERROR_LINE.test(line)) err = line.trim()
         const fail = line.match(/^\(fail\) (.*?)(?: \[[\d.]+m?s\])?$/)
         if (fail != null) out.set(cur, clip(err == null ? fail[1]! : `${fail[1]!}: ${err}`))
-        else if (line.startsWith('# Unhandled error between tests')) out.set(cur, clip(err == null ? 'an unhandled error between tests' : `an unhandled error between tests: ${err}`))
+        else if (line.startsWith(BETWEEN_TESTS)) {
+            const thrown = blockError(lines, i + 1) ?? err
+            out.set(cur, clip(thrown == null ? BETWEEN_WORDS : `${BETWEEN_WORDS}: ${thrown}`))
+        }
     }
     return out
 }
 
 const clip = (s: string): string => (s.length > 300 ? `${s.slice(0, 299)}…` : s)
 
+/** the FAIL headline of a run bun ended red with no kill, read off bun's own
+ *  summary (`N fail`, `N error`) and the report in `out`. bun can count an
+ *  error thrown outside any test as `0 fail`, so the errors lead, each with
+ *  the file that threw */
+export function redWords(o: { failedTests: number; errors: number; ran: number; slowest: string; out: string }): string {
+    const thrown = [...failLines(o.out)].filter(([, w]) => w.startsWith(BETWEEN_WORDS))
+    const parts: string[] = []
+    if (o.errors > 0 || thrown.length > 0) {
+        const named = thrown.slice(0, 3).map(([file, w]) => `${file} threw ${w.slice(BETWEEN_WORDS.length + 2) || 'with no message'}`)
+        const more = thrown.length > 3 ? `; ${thrown.length - 3} more` : ''
+        parts.push(`${Math.max(o.errors, thrown.length)} error(s) outside any test ${named.length > 0 ? `(${named.join('; ')}${more})` : '(bun named no file)'}`)
+    }
+    if (o.failedTests > 0) parts.push(`${o.failedTests} test(s) failed`)
+    if (parts.length === 0) parts.push('bun test exited red with no failed test and no error counted')
+    return `${parts.join(', ')}, Ran ${o.ran} tests${o.slowest}`
+}
+
 /** the clause the headline carries for the gate line: the command phase one
  *  ran, and the flags the runner added to the script's own. Per file ignores
  *  stay out, the slow and serial counts already say what they leave out */

package/src/suite/select.ts

@@ -31,7 +31,7 @@ import { blobOid, listingHash } from '../core/read-set.ts'
 import { shipkitRoot } from '../ledger/db.ts'
 import { extractSpecs, resolveSpec } from '../ts/source-graph.ts'
 import { type RvtConfig } from '../ts/config.ts'
-import { inDotDir } from './judge-suites.ts'
+import { BETWEEN_TESTS, BUN_RULE, inDotDir } from './judge-suites.ts'
 
 export const SELECT_VERSION = 5
 
@@ -403,9 +403,6 @@ export function selectSuites(o: {
     return { all: false, run, why: reasons, changed: o.changed.size }
 }
 
-const BETWEEN_TESTS = '# Unhandled error between tests'
-const RULE = /^-{20,}$/
-
 /** the repo modules named in the frames of every error bun printed between
  *  tests (a module whose top level threw), repo-relative to `top` */
 export function loadErrorModules(out: string, top: string): string[] {
@@ -419,7 +416,7 @@ export function loadErrorModules(out: string, top: string): string[] {
         let rules = 0
         for (let j = i + 1; j < lines.length && rules < 2; j++) {
             const line = lines[j]!
-            if (RULE.test(line.trim())) { rules++; continue }
+            if (BUN_RULE.test(line.trim())) { rules++; continue }
             const m = /^\s+at .*?\(?((?:\/|[A-Za-z]:\\)[^():]+):\d+(?::\d+)?\)?\s*$/.exec(line)
             if (m == null) continue
             const base = roots.find((r) => m[1]!.startsWith(`${r}/`))

package/src/suite/suite-cli.ts

@@ -20,7 +20,7 @@ import { SUITE_READS_ENV, SUITE_ROOT_ENV, SUITE_SELECT_ENV } from './reads-env.t
 import { changedKeys, dropStaticEdges, extras, isBunSuite, envFilesOf, foldReads, loadErrorModules, loadState, preloadsOf, saveState, selectStatePath, selectSuites, snapshot, suiteFiles, taintedSuites, walkGraph, type GraphEntry, type Selection, type SelectState } from './select.ts'
 import { gitRoot } from '../core/git-root.ts'
 import { loadConfig } from '../ts/config.ts'
-import { aloneRunsNeeded, bunfigTest, type BunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, interruptedSuites, overWords, ranAs, retryAlone, smallerRun, stallWords, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers } from './judge-suites.ts'
+import { aloneRunsNeeded, bunfigTest, type BunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, interruptedSuites, overWords, ranAs, retryAlone, smallerRun, stallWords, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers, redWords } from './judge-suites.ts'
 
 type Phase = { code: number; signal: string | null; stalled: boolean; out: string; timings: Record<string, number>; cpuMs: number | null }
 
@@ -196,6 +196,7 @@ async function runSuites(argv: string[], ctx: SelectCtx): Promise<number> {
         const phases = [p1, ...(p2 != null ? [p2] : [])]
         const ran = phases.reduce((n, p) => n + lastCount(p.out, /Ran (\d+) tests?/g), 0)
         const failedTests = phases.reduce((n, p) => n + lastCount(p.out, /^\s*(\d+) fail$/gm), 0)
+        const errors = phases.reduce((n, p) => n + lastCount(p.out, /^\s*(\d+) errors?$/gm), 0)
         const timings = Object.assign({}, ...phases.map((p) => p.timings)) as Record<string, number>
         const crashed = crashedWorkers(p1.out)
         const red = new Set([...phases.flatMap((p) => failedSuites(p.out)), ...crashed.map((c) => c.file)])
@@ -290,7 +291,7 @@ async function runSuites(argv: string[], ctx: SelectCtx): Promise<number> {
             ...killed.map((k) => `FAIL: ${k}`),
             ...(vacuous ? ['FAIL: ran 0 tests: a suite with no test in it proves nothing, write a real one'] : []),
             ...(!vacuous && (failedTests > 0 || (phases.some((p) => p.code !== 0 && p.signal == null) && killed.length === 0))
-                ? [`FAIL: ${failedTests} test(s) failed, Ran ${ran} tests${slowest}`] : []),
+                ? [`FAIL: ${redWords({ failedTests, errors, ran, slowest, out: phases.map((p) => p.out).join('\n') })}`] : []),
             ...(over.length > 0
                 ? [`FAIL: ${over.length} suite(s) over the ${budget}ms budget: ${over.map((c) => overWords(c, load, budget)).join(', ')} (run alone, load ${load.load1.toFixed(1)} on ${load.cores} cores before the run). Make each fast, or declare it in ${declaredIn}.slow with what it catches and why it cannot be fast`]
                 : []),

package/src/trailer/adapter.ts

@@ -0,0 +1,23 @@
+// what a repo adds to the trailer core, all optional. Filming is never here: a film line calls the project CLI's
+// film rows (vocab.ts). A `trailer({...})` unit in any `<name>.shipkit.ts` resolves the sounds that are not files.
+// Discovered like every unit file (load-unit.ts), and read only when a cut names such a sound
+
+export interface TrailerSounds {
+    /** a music id to an audio file of at least `seconds`, cached by the repo */
+    music?(id: string, o: { take?: string; seconds: number }): Promise<string>
+    /** an sfx id to an audio file */
+    sfx?(id: string): Promise<string>
+    /** a voice line, found by its text, to an audio file */
+    voice?(text: string): Promise<string>
+}
+
+export interface TrailerDef {
+    sound?: TrailerSounds
+}
+
+export type TrailerUnit = TrailerDef & { kind: 'trailer' }
+
+export function trailer(d: TrailerDef): TrailerUnit {
+    for (const [k, f] of Object.entries(d.sound ?? {})) if (typeof f !== 'function') throw new Error(`trailer: sound.${k} is a function returning an audio file`)
+    return { ...d, kind: 'trailer' }
+}

package/src/trailer/build.ts

@@ -0,0 +1,344 @@
+// a cut's .trailer file → its mp4: load (parse, resolve every file and sound), film what is missing, draw the titles,
+// stitch the pieces, lay the strip, write the montage page. `sk trailer` and its verbs call these
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { type FilmVerb, type Film, parseTrailer, type Shot, starts, total, type Trailer, type TrailerError, musicCues, NO_MUSIC } from './grammar.ts'
+import type { BrandLike, TrailerLook } from './look.ts'
+import { fresh, isTake, type Refilm, type Take, takesToFilm } from './plan.ts'
+import type { Stitched } from './stitch.ts'
+import { projectCli, readVocab } from './vocab.ts'
+
+export type Say = (line: string) => void
+
+export class Refused extends Error {}
+const refuse = (why: string): never => {
+    throw new Refused(why)
+}
+
+/** every `.trailer` under `trailer/<trailer>/` */
+export function trailerFiles(root: string): string[] {
+    const dir = join(root, 'trailer')
+    if (!existsSync(dir)) return []
+    return readdirSync(dir)
+        .filter((d) => statSync(join(dir, d)).isDirectory())
+        .flatMap((d) => readdirSync(join(dir, d)).filter((f) => f.endsWith('.trailer')).map((f) => join(dir, d, f)))
+        .sort()
+}
+
+/** the .trailer a command names: a file, a folder's main.trailer (or its one .trailer), or the one under trailer/ */
+export function trailerFile(arg: string | undefined, root: string, cwd: string): string {
+    if (arg !== undefined) {
+        const p = resolve(cwd, arg)
+        if (existsSync(p) && statSync(p).isDirectory()) {
+            if (existsSync(join(p, 'main.trailer'))) return join(p, 'main.trailer')
+            const own = readdirSync(p).filter((f) => f.endsWith('.trailer'))
+            return own.length === 1 ? join(p, own[0]!) : refuse(own.length === 0 ? `${arg} has no .trailer` : `${arg} has several cuts, name one: ${own.join(', ')}`)
+        }
+        return existsSync(p) ? p : refuse(`no file ${arg}`)
+    }
+    const all = trailerFiles(root)
+    if (all.length === 1) return all[0]!
+    return refuse(all.length === 0 ? 'no .trailer under trailer/<trailer>/: write trailer/<name>/main.trailer (wiki build/trailer.md)' : `several cuts, name one: ${all.map((f) => relative(cwd, f)).join(', ')}`)
+}
+
+/** a sound or a media word that names a file rather than an id */
+export const isFileWord = (w: string): boolean => w.includes('/') || /\.[a-z0-9]{2,5}$/i.test(w)
+
+export interface Loaded {
+    root: string
+    file: string
+    dir: string
+    t: Trailer
+    errors: TrailerError[]
+    /** the project CLI's argv, null when the repo has none */
+    cli: string[] | null
+    verbs: FilmVerb[] | null
+}
+
+/** a file a line names: beside the .trailer first, then from the repo root */
+export function fileOf(path: string, l: Pick<Loaded, 'dir' | 'root'>): string | null {
+    if (isAbsolute(path)) return existsSync(path) ? path : null
+    for (const f of [join(l.dir, path), join(l.root, path)]) if (existsSync(f)) return f
+    return null
+}
+
+/** the file parsed and checked against the repo: every error at its line, all at once */
+export function load(file: string, root: string): Loaded {
+    const text = readFileSync(file, 'utf8')
+    const cli = projectCli(root)
+    let verbs: FilmVerb[] | null = null
+    const errors: TrailerError[] = []
+    let parsed = parseTrailer(text, { verbs: null })
+    // the project CLI is asked only when a film line does not read as a core film
+    const lines = text.split('\n')
+    if (cli !== null && parsed.errors.some((e) => /^\s*film\s/.test(lines[e.line - 1] ?? ''))) {
+        try {
+            verbs = readVocab(root, cli)
+            parsed = parseTrailer(text, { verbs })
+        } catch (e) {
+            errors.push({ line: 1, message: (e as Error).message })
+        }
+    }
+    const t = parsed.trailer
+    const l: Loaded = { root, file, dir: dirname(file), t, errors: [...errors, ...parsed.errors], cli, verbs }
+    if (l.errors.length === 0) l.errors.push(...checkFiles(l))
+    l.errors.sort((a, b) => a.line - b.line)
+    return l
+}
+
+/** the clips, images and sound files the lines name, each found where it should be */
+function checkFiles(l: Loaded): TrailerError[] {
+    const out: TrailerError[] = []
+    const need = (line: number, what: string, path: string): void => {
+        if (!fileOf(path, l)) out.push({ line, message: `${what}: no file ${path} beside the .trailer or from the repo root` })
+    }
+    for (const s of l.t.shots) {
+        if (s.film?.kind === 'clip' || s.film?.kind === 'image') need(s.film.line, `film ${s.film.kind}`, s.film.path)
+        for (const x of s.sfx) if (isFileWord(x.id)) need(x.line, 'sfx', x.id)
+        for (const v of s.voices) if (v.file) need(v.line, 'voice file', v.file)
+    }
+    for (const m of [l.t.music, ...l.t.shots.map((s) => s.music)]) if (m && m.song !== NO_MUSIC && isFileWord(m.song)) need(m.line, 'music', m.song)
+    const v = l.t.vertical
+    if (v && typeof v.outro === 'object') need(v.line, 'vertical outro', v.outro.clip)
+    return out
+}
+
+/** the ids that are not files: what only the repo's trailer unit resolves */
+export function soundIds(t: Trailer): { line: number; kind: 'music' | 'sfx' | 'voice'; id: string }[] {
+    return [
+        ...[t.music, ...t.shots.map((s) => s.music)].flatMap((m) => (m && m.song !== NO_MUSIC && !isFileWord(m.song) ? [{ line: m.line, kind: 'music' as const, id: m.song }] : [])),
+        ...t.shots.flatMap((s) => [
+            ...s.sfx.filter((x) => !isFileWord(x.id)).map((x) => ({ line: x.line, kind: 'sfx' as const, id: x.id })),
+            ...s.voices.filter((v) => v.text !== undefined).map((v) => ({ line: v.line, kind: 'voice' as const, id: v.text! })),
+        ]),
+    ]
+}
+
+export function sayErrors(l: Loaded, say: Say, cwd: string): boolean {
+    for (const e of l.errors) say(`${relative(cwd, l.file)}:${e.line}: ${e.message}`)
+    return l.errors.length === 0
+}
+
+const ago = (iso: string): string => {
+    const m = Math.round((Date.now() - Date.parse(iso)) / 60_000)
+    return m < 60 ? `${m} min ago` : m < 48 * 60 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} days ago`
+}
+
+const filmText = (f: Film | null): string => {
+    if (!f) return 'nothing'
+    if (f.kind === 'clip' || f.kind === 'image') return `${f.kind} ${f.path}`
+    if (f.kind === 'run') return `run "${f.cmd}"${f.still ? ' still' : ''}`
+    if (f.kind === 'cli') return f.argv.join(' ')
+    if (f.kind === 'url') return `url ${f.route}${f.viewport ? ` viewport ${f.viewport.join('x')}` : ''}${f.still ? ' still' : ''}`
+    return 'card'
+}
+
+/** the timeline, one line a shot, each take's state against the world */
+export function timeline(l: Loaded, takes: readonly Take[], world: string | null, cwd: string): string[] {
+    const st = starts(l.t)
+    const out = [`${relative(cwd, l.file)}: ${l.t.shots.length} shots, ${total(l.t).toFixed(2)} s, ${l.t.size.join('x')} at ${l.t.fps} fps`]
+    l.t.shots.forEach((s, i) => {
+        const tk = takes.find((x) => x.shot === s)
+        const state = !isTake(s.film)
+            ? (s.film?.kind === 'card' ? 'drawn' : `a file`)
+            : !tk?.stamp
+              ? 'NOT FILMED'
+              : world === null || fresh(tk.stamp, world)
+                ? 'filmed'
+                : `filmed on an older world, ${ago(tk.stamp.filmedAt)} (--refilm ${s.name})`
+        const sec = s.section ? `  [section ${s.section.name} at ${+s.section.at.toFixed(3)} s]` : ''
+        const fit = s.written !== undefined ? ` (fitted, written ${s.written} s)` : ''
+        out.push(`  ${String(i + 1).padStart(2)} ${st[i]!.toFixed(2).padStart(6)} s  ${s.name.padEnd(20)} ${s.length.toFixed(2).padStart(5)} s${fit}  ${state}${sec}`)
+    })
+    return out
+}
+
+const secs = (x: number): string => `${+x.toFixed(2)} s`
+const clockText = (x: number): string => `${Math.floor(x / 60)}:${(x % 60).toFixed(2).padStart(5, '0')}`
+const cell = (s: string): string => s.replaceAll('|', '\\|').replaceAll('\n', ' ')
+
+/** the cut as a table an agent or a human reads: `out/<cut>.montage.md`, written by every build */
+export function montage(t: Trailer, file: string): string {
+    const st = starts(t)
+    const m = t.music
+    const heard = (s: Shot): string =>
+        [s.music ? `music ${s.music.song}` : '', ...s.sfx.map((x) => `sfx ${x.id} at ${secs(x.at)}`), ...s.voices.map((v) => `voice ${v.text ? `"${v.text}"` : v.file} at ${secs(v.at)}`)].filter(Boolean).join('<br>')
+    return [
+        `# Montage: ${t.name}`,
+        '',
+        `Written from \`${file}\` by every \`sk trailer\` build: edit the .trailer, never this file.`,
+        '',
+        `${secs(total(t))}, ${t.size[0]}x${t.size[1]} at ${t.fps} fps, ${t.shots.length} shots${m ? `, music \`${m.song}\` from ${clockText(m.from)}` : ', no music'}${t.sections.length ? `, ${t.sections.length} sections: ${t.sections.map((x) => x.name).join(', ')}` : ''}${t.fadeIn ? `, opens from black over ${secs(t.fadeIn)}` : ''}.`,
+        '',
+        '| # | at | shot | length | film | on screen | heard | cut out |',
+        '|---|---|---|---|---|---|---|---|',
+        ...t.shots.map((s, i) =>
+            `| ${i + 1} | ${clockText(st[i] ?? 0)} | ${s.name} | ${secs(s.length)} | ${cell(filmText(s.film) + (s.from ? `, from ${secs(s.from)}` : '') + (s.frame ? `, frame ${s.frame}` : '') + (s.push ? `, push ${s.push}` : ''))} | ${cell(s.titles.map((ti) => `${ti.style} "${ti.text}" at ${secs(ti.at)}`).join('<br>'))} | ${cell(heard(s))} | ${s.cut.kind === 'hard' ? 'hard' : `${s.cut.kind} ${secs(s.cut.seconds)}`} |`,
+        ),
+        '',
+    ].join('\n')
+}
+
+export interface BuildOptions {
+    refilm: Refilm
+    final: boolean
+    say: Say
+    cwd: string
+}
+
+/** film the takes missing (and what --refilm names), two at once; every shot is tried, the failures said together */
+async function filmAll(l: Loaded, world: string, refilm: Refilm, say: Say, only?: ReadonlySet<string>): Promise<Take[]> {
+    const { filmTake, takesOf } = await import('./footage.ts')
+    const takes = takesOf(l.t, l.root)
+    const ask = takesToFilm(takes, world, refilm, only)
+    const failed: string[] = []
+    const lane = async (): Promise<void> => {
+        for (let group = ask.shift(); group; group = ask.shift()) {
+            try {
+                const got = await filmTake(group[0]!, { root: l.root, t: l.t, world, cli: l.cli, say })
+                for (const tk of group) {
+                    const i = takes.indexOf(tk)
+                    takes[i] = { ...tk, stamp: got.stamp }
+                }
+            } catch (e) {
+                failed.push(e instanceof Error ? e.message : String(e))
+            }
+        }
+    }
+    await Promise.all([lane(), lane()])
+    if (failed.length > 0) throw new Refused(`${failed.length} shot(s) did not film:\n${failed.join('\n')}`)
+    return takes
+}
+
+/** everything the stitch reads but its output: sources, titles, sounds, the look */
+async function stitchInput(l: Loaded, takes: readonly Take[], shots: readonly Shot[], silent: boolean) {
+    const [{ cardPng, placeOf, titlePng }, { lookOf }, { duration }, { trailerCache }, { loadBrand, identityLogo }] = await Promise.all([
+        import('./titles.ts'),
+        import('./look.ts'),
+        import('./ffmpeg.ts'),
+        import('./footage.ts'),
+        import('../assets/run-assets.ts'),
+    ])
+    const brand = await loadBrand(l.root)
+    if (typeof brand === 'string') throw new Refused(brand)
+    const look = lookOf(brand, await identityLogo(l.root))
+    const base = { look, brand }
+    const titles = trailerCache(l.root, 'titles')
+    const sources = shots.map((s) => {
+        const f = s.film!
+        if (f.kind === 'card') return { image: cardPng(titles, l.t.size, look) }
+        if (f.kind === 'image') return { image: fileOf(f.path, l)! }
+        if (f.kind === 'clip') {
+            const file = fileOf(f.path, l)!
+            return { footage: file, seconds: duration(file) }
+        }
+        const tk = takes.find((x) => x.shot.name === s.name)!
+        return tk.stamp!.seconds === 0 ? { image: tk.file } : { footage: tk.file, seconds: tk.stamp!.seconds }
+    })
+    const drawn = await Promise.all(shots.map((s) => Promise.all(s.titles.map((ti) => titlePng(titles, l.root, ti.text, ti.style, l.t.size, placeOf(ti), look)))))
+    if (silent) return { ...base, sources, titles: drawn, music: [], sfx: shots.map(() => []), voices: shots.map(() => []) }
+    const ids = soundIds(l.t)
+    const unit = ids.length > 0 ? await (await import('./load-unit.ts')).loadTrailerUnit(l.root) : null
+    const resolveId = async (kind: 'music' | 'sfx' | 'voice', id: string, line: number, seconds = 0, take?: string): Promise<string> => {
+        const f = kind === 'music' ? unit?.sound?.music && ((x: string) => unit.sound!.music!(x, { take, seconds })) : kind === 'sfx' ? unit?.sound?.sfx : unit?.sound?.voice
+        if (!f) throw new Refused(`${relative(l.root, l.file)}:${line}: ${kind} ${id} is no file, and no trailer unit resolves ${kind} ids (a <name>.shipkit.ts default-exporting trailer({ sound }))`)
+        return f(id)
+    }
+    const music = await Promise.all(musicCues(l.t).map(({ cue, at, end }) => (isFileWord(cue.song) ? fileOf(cue.song, l)! : resolveId('music', cue.song, cue.line, cue.from + end - at, cue.take))))
+    const sfx = await Promise.all(shots.map((s) => Promise.all(s.sfx.map(async (x) => {
+        const file = isFileWord(x.id) ? fileOf(x.id, l)! : await resolveId('sfx', x.id, x.line)
+        return { file, seconds: duration(file) }
+    }))))
+    const voices = await Promise.all(shots.map((s) => Promise.all(s.voices.map(async (v) => {
+        const file = v.file ? fileOf(v.file, l)! : await resolveId('voice', v.text!, v.line)
+        return { file, seconds: duration(file) }
+    }))))
+    return { ...base, sources, titles: drawn, music, sfx, voices }
+}
+
+/** a vertical cut finished: what the brand's vertical look draws over the stitched cut, the outro, the end card. The
+ *  finish is cached on the pieces and the mix it reads, so a build that changed nothing encodes nothing */
+async function finishVertical(l: Loaded, input: { look: TrailerLook; brand: BrandLike | null }, done: Stitched, cut: string, out: string, final: boolean): Promise<{ note: string; seconds: number }> {
+    const [{ finishArgs, finishSeconds, verticalOf }, { drawEnd, drawMark, drawWear }, { cachedAs }, { duration, hasAudio }, { trailerCache }] = await Promise.all([
+        import('./vertical.ts'),
+        import('./vertical-draw.ts'),
+        import('./stitch.ts'),
+        import('./ffmpeg.ts'),
+        import('./footage.ts'),
+    ])
+    const v = l.t.vertical!
+    const vl = verticalOf(input.brand, input.look, basename(l.root), v.mark)
+    const dir = trailerCache(l.root, 'titles')
+    const clip = typeof v.outro === 'object' ? fileOf(v.outro.clip, l)! : null
+    const [wear, mark, end] = await Promise.all([
+        drawWear(dir, l.root, input.look, vl, l.t.size, l.t.fps),
+        clip ? drawMark(dir, l.root, input.look, vl, l.t.size) : null,
+        v.outro === 'none' ? null : drawEnd(dir, l.root, input.look, vl, l.t.size),
+    ])
+    const a = {
+        cut,
+        seconds: duration(cut),
+        size: l.t.size,
+        fps: l.t.fps,
+        wear,
+        mark,
+        outro: clip ? { clip, seconds: duration(clip), audio: hasAudio(clip) } : null,
+        end: end && { ...end, seconds: vl.end!.seconds },
+        encoder: final ? ('final' as const) : ('draft' as const),
+    }
+    const clipStat = clip ? [statSync(clip).size, statSync(clip).mtimeMs] : null
+    const key = new Bun.CryptoHasher('sha1').update(JSON.stringify([finishArgs(a, 'out.mp4'), done.pieces.map((p) => p.file), done.mix, clipStat])).digest('hex').slice(0, 16)
+    const { files, made } = await cachedAs(join(trailerCache(l.root, 'pieces'), 'vertical'), `${l.t.name}-vertical`, key, ['mp4'], ([o]) => finishArgs(a, o!))
+    copyFileSync(files[0]!, out)
+    return { note: made ? 'the vertical finished' : 'the vertical cached', seconds: finishSeconds(a) }
+}
+
+/** trailer/<trailer>/out/, its own `.gitignore` holding `*`: a build output is never committed by accident */
+function outDir(l: Loaded): string {
+    const dir = join(l.dir, 'out')
+    mkdirSync(dir, { recursive: true })
+    if (!existsSync(join(dir, '.gitignore'))) writeFileSync(join(dir, '.gitignore'), '*\n')
+    return dir
+}
+
+/** the whole cut: out/<cut>.mp4, its strip and montage page; the timeline and what was rendered, said */
+export async function build(l: Loaded, o: BuildOptions): Promise<string> {
+    const t0 = performance.now()
+    const [{ worldStamp, trailerCache }, { stitch, strip, rendered }, { ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const world = worldStamp(l.root)
+    const takes = await filmAll(l, world, o.refilm, o.say)
+    const tFilm = performance.now()
+    const input = await stitchInput(l, takes, l.t.shots, false)
+    const out = join(outDir(l), `${l.t.name}.mp4`)
+    // a vertical cut stitches into the cache, and its finish writes the mp4
+    const cut = l.t.vertical ? join(trailerCache(l.root, 'pieces'), `${l.t.name}-cut.mp4`) : out
+    const done = await stitch({ ...input, t: l.t, out: cut, cache: trailerCache(l.root, 'pieces'), encoder: o.final ? 'final' : 'draft' })
+    const finished = l.t.vertical ? await finishVertical(l, input, done, cut, out, o.final) : null
+    const stripFile = join(outDir(l), `${l.t.name}.strip.png`)
+    await strip(done.pieces, stripFile)
+    writeFileSync(join(outDir(l), `${l.t.name}.montage.md`), montage(l.t, basename(l.file)))
+    for (const line of timeline(l, takes, world, o.cwd)) o.say(line)
+    o.say(`ok: ${out} (${(finished?.seconds ?? total(l.t)).toFixed(2)} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s: filming ${((tFilm - t0) / 1000).toFixed(1)} s, ${rendered(done)}${finished ? `, ${finished.note}` : ''}`)
+    o.say(`ok: ${stripFile}`)
+    return out
+}
+
+/** one shot alone with its titles, no sound: out/shot-<name>.mp4 and its nine frames on out/shot-<name>.png */
+export async function previewShot(l: Loaded, name: string, o: BuildOptions): Promise<void> {
+    const t0 = performance.now()
+    const s = l.t.shots.find((x) => x.name === name) ?? refuse(`no shot ${name} in ${relative(o.cwd, l.file)}: ${l.t.shots.map((x) => x.name).join(', ')}`)
+    const [{ worldStamp, trailerCache }, { stitch }, { sheetOf, ffmpegMissing }] = await Promise.all([import('./footage.ts'), import('./stitch.ts'), import('./ffmpeg.ts')])
+    const missing = ffmpegMissing()
+    if (missing) throw new Refused(missing)
+    const one: Trailer = { ...l.t, name: `${l.t.name}-shot-${name}`, music: null, fadeIn: 0, shots: [{ ...s, cut: { line: s.line, kind: 'hard', seconds: 0 }, sfx: [], voices: [], music: null }] }
+    const takes = await filmAll(l, worldStamp(l.root), o.refilm, o.say, new Set([name]))
+    const input = await stitchInput(l, takes, one.shots, true)
+    const out = join(outDir(l), `shot-${name}.mp4`)
+    await stitch({ ...input, t: one, out, cache: trailerCache(l.root, 'pieces'), silent: true })
+    const sheet = out.replace(/\.mp4$/, '.png')
+    await sheetOf(out, s.length, sheet)
+    o.say(`ok: ${out} (${s.length} s) in ${((performance.now() - t0) / 1000).toFixed(1)} s`)
+    o.say(`ok: ${sheet}`)
+}

package/src/trailer/ffmpeg.ts

@@ -0,0 +1,50 @@
+// the one way the trailer spawns ffmpeg and ffprobe: a run that fails loud with ffmpeg's own words, a probe, the nine
+// frame sheet. The binaries resolve once, with the homebrew path for processes started without it
+import { spawn } from 'node:child_process'
+import { basename } from 'node:path'
+
+const FFMPEG = Bun.which('ffmpeg') ?? '/opt/homebrew/bin/ffmpeg'
+const FFPROBE = Bun.which('ffprobe') ?? '/opt/homebrew/bin/ffprobe'
+
+/** ffmpeg and ffprobe on this machine, or what to install */
+export function ffmpegMissing(): string | null {
+    for (const [name, bin] of [['ffmpeg', FFMPEG], ['ffprobe', FFPROBE]] as const) if (!Bun.which(bin)) return `${name} not found: brew install ffmpeg`
+    return null
+}
+
+const niced = (cmd: string[], nice?: number): string[] => (nice ? ['nice', '-n', String(nice), ...cmd] : cmd)
+
+const failure = (args: readonly string[], err: string, code: number | null): Error =>
+    new Error(`ffmpeg → ${basename(args.at(-1) ?? '')}: ${err.trim().split('\n').slice(-6).join('\n') || `exit ${code}`}`)
+
+/** ffmpeg with `args` after `-hide_banner -nostdin -y -loglevel error`; resolves to its stderr, rejects with it */
+export function ffmpeg(args: readonly string[], o: { nice?: number } = {}): Promise<string> {
+    return new Promise((ok, fail) => {
+        const cmd = niced([FFMPEG, '-hide_banner', '-nostdin', '-y', '-loglevel', 'error', ...args], o.nice)
+        const p = spawn(cmd[0]!, cmd.slice(1), { stdio: ['ignore', 'ignore', 'pipe'] })
+        let err = ''
+        p.stderr.on('data', (d: Buffer) => (err += d.toString()))
+        p.on('error', (e) => fail(new Error(`${FFMPEG}: ${e.message}; brew install ffmpeg`)))
+        p.on('close', (code) => (code === 0 ? ok(err) : fail(failure(args, err, code))))
+    })
+}
+
+/** one ffprobe of a media file: its length in seconds; throws when ffprobe cannot read it or finds no length */
+export function duration(file: string): number {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })
+    const d = Number(r.stdout.toString().trim())
+    if (r.exitCode !== 0 || !(d > 0)) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || 'no length'}`)
+    return d
+}
+
+/** the media file carries a sound stream */
+export function hasAudio(file: string): boolean {
+    const r = Bun.spawnSync([FFPROBE, '-v', 'error', '-select_streams', 'a', '-show_entries', 'stream=index', '-of', 'csv=p=0', file], { stdout: 'pipe', stderr: 'pipe' })
+    if (r.exitCode !== 0) throw new Error(`ffprobe ${file}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`)
+    return r.stdout.toString().trim() !== ''
+}
+
+/** nine frames of a clip evenly spaced, three by three on one png: how a shot is judged */
+export async function sheetOf(clip: string, seconds: number, png: string): Promise<void> {
+    await ffmpeg(['-i', clip, '-vf', `fps=${(9 / seconds).toFixed(4)},scale=480:-2,tile=3x3`, '-frames:v', '1', png])
+}