rvlib-shipkit 2.2.0 → 2.4.0

package/src/cli/cmd_Sound.ts

@@ -0,0 +1,209 @@
+// sk sound: the house sound generators, one verb each, for a trailer as much as a game. Each writes --out and says its
+// measures; a trailer's `voice`, `sfx` and `music` words run them through its sound cache (trailer/sound/). Every
+// module loads inside execute: the cli registers this file on every `sk` call
+import { Command, Option } from 'clipanion'
+
+const PAGE = 'Page: wiki build/trailer.md, Sound'
+
+async function run(context: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }, body: (say: (l: string) => void, root: string, cwd: string) => Promise<void>): Promise<number> {
+    const say = (l: string): void => void context.stdout.write(`${l}\n`)
+    const { findRepoRoot } = await import('../ts/config.ts')
+    const cwd = process.cwd()
+    try {
+        await body(say, findRepoRoot(cwd), cwd)
+        return 0
+    } catch (e) {
+        context.stderr.write(`FAIL sound: ${e instanceof Error ? e.message : String(e)}\n`)
+        return 1
+    }
+}
+
+/** the brand's sound section, when the repo has a brand */
+async function brandSound(root: string): Promise<import('../trailer/sound/brand.ts').TrailerSoundInput | undefined> {
+    const { loadBrand } = await import('../assets/run-assets.ts')
+    const b = await loadBrand(root)
+    if (typeof b === 'string') throw new Error(b)
+    return b?.trailer
+}
+
+const COMFY = 'the comfy-ts module folder (default: the brand\'s trailer.comfy)'
+
+/** --out, which every making verb needs */
+function outOf(out: string | undefined): string {
+    if (out === undefined) throw new Error('--out <file>: the file it writes')
+    return out
+}
+
+const num = (name: string, v: string | undefined, fallback: number): number => {
+    if (v === undefined) return fallback
+    const n = Number(v)
+    if (!Number.isFinite(n)) throw new Error(`${name} takes a number, got ${v}`)
+    return n
+}
+
+export class SoundVoiceCommand extends Command {
+    static override paths = [['sound', 'voice']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'one spoken line in a voice: ElevenLabs, or comfy-ts cloning a clip or a designed voice',
+        details: `no voice flag: the brand's trailer.voice (--by <name>: one of its trailer.voices), else the house narrator. ElevenLabs is paid: it says the characters spent and left. The line is trimmed at both ends and set at -16 LUFS. ${PAGE}`,
+        examples: [
+            ['the brand\'s voice', 'sk sound voice "The storm is coming." --out lines/storm.wav'],
+            ['an ElevenLabs voice, its second take', 'sk sound voice "[whispers] Hey." --eleven pNInz6obpgDQGcFmaJgB --seed 2 --out hey.wav'],
+            ['a clip cloned, free', 'sk sound voice "Ahoy." --clone voices/sailor.flac --out ahoy.wav'],
+            ['a voice designed from words, free', 'sk sound voice "Ahoy." --design "an old sailor, gravelly and warm" --out ahoy.wav'],
+        ],
+    })
+    text = Option.String({ required: true, name: 'line' })
+    by = Option.String('--by', { description: 'one of the brand\'s trailer.voices' })
+    eleven = Option.String('--eleven', { description: 'an ElevenLabs voice id (paid)' })
+    model = Option.String('--model', { description: 'the ElevenLabs model (default eleven_v3)' })
+    stability = Option.String('--stability')
+    similarity = Option.String('--similarity')
+    speed = Option.String('--speed')
+    clone = Option.String('--clone', { description: 'a clean 5 to 10 s clip to clone, repo relative' })
+    transcript = Option.String('--transcript', { description: 'what the clip says (default: <clip>.txt)' })
+    design = Option.String('--design', { description: 'a voice designed from its description' })
+    designLine = Option.String('--design-line', { description: 'what the designed voice\'s reference reads' })
+    designSeed = Option.String('--design-seed')
+    engine = Option.String('--engine', { description: 'comfy-ts engine: chatterbox, qwen3, fishs2, cosyvoice3, omnivoice' })
+    language = Option.String('--language', { description: 'en, fr… (ElevenLabs) or English, French… (comfy-ts)' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genVoice }, { voiceOf }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts'), import('../trailer/sound/brand.ts')])
+            const brand = await brandSound(root)
+            const given = [this.eleven, this.clone, this.design].filter((x) => x !== undefined).length
+            if (given > 1) throw new Error('one voice: --eleven, --clone or --design')
+            const n = (k: string, v: string | undefined): number | undefined => (v === undefined ? undefined : num(k, v, 0))
+            const lang = this.language !== undefined ? { language: this.language } : {}
+            const eng = this.engine !== undefined ? { engine: this.engine } : {}
+            let voice
+            if (this.eleven !== undefined) voice = { eleven: this.eleven, ...(this.model ? { model: this.model } : {}), ...strip({ stability: n('--stability', this.stability), similarity: n('--similarity', this.similarity), speed: n('--speed', this.speed) }), ...lang }
+            else if (this.clone !== undefined) voice = { clone: this.clone, ...(this.transcript !== undefined ? { transcript: this.transcript } : {}), ...eng, ...lang }
+            else if (this.design !== undefined) voice = { design: this.design, ...(this.designLine !== undefined ? { line: this.designLine } : {}), ...strip({ seed: n('--design-seed', this.designSeed) }), ...eng, ...lang }
+            else voice = voiceOf(brand, this.by)
+            await genVoice({ root, text: this.text, voice, seed: num('--seed', this.seed, 1), comfy: this.comfy ?? brand?.comfy, elevenKey: brand?.elevenKey, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+const strip = <T extends Record<string, unknown>>(o: T): Partial<T> => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as Partial<T>
+
+export class SoundSfxCommand extends Command {
+    static override paths = [['sound', 'sfx']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a sound effect from a prompt: comfy-ts stable-audio, trimmed, its peak at -3 dBFS',
+        details: `its silence before is cut, its tail cut where it falls 45 dB under its peak with a 30 ms fade; --hit keeps its first hit alone. The GPU box must be up: sk gp start comfyui. ${PAGE}`,
+        examples: [
+            ['a clash cut to its first hit', 'sk sound sfx "a sword clash, metal on metal" --hit --out sfx/clash.wav'],
+            ['four seconds of rain, another take', 'sk sound sfx "rain on a tin roof" --seconds 4 --seed 2 --out sfx/rain.wav'],
+        ],
+    })
+    prompt = Option.String({ required: true, name: 'prompt' })
+    seconds = Option.String('--seconds', { description: 'seconds made (default 2)' })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    hit = Option.Boolean('--hit', false, { description: 'its first hit alone' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genSfx }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            const comfy = this.comfy ?? (await brandSound(root))?.comfy
+            await genSfx({ prompt: this.prompt, seconds: num('--seconds', this.seconds, 2), seed: num('--seed', this.seed, 1), hit: this.hit, comfy, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMusicCommand extends Command {
+    static override paths = [['sound', 'music']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a music bed or a song from a prompt: comfy-ts stable-audio or ace-step, -16 LUFS',
+        details: `stable-audio plays an instrumental bed (up to 300 s); ace-step reads the prompt's first line as its style caption and sings the lines after it ([Verse], [Chorus]), else plays instrumental. The GPU box must be up: sk gp start comfyui. ${PAGE}`,
+        examples: [
+            ['a 30 s bed', 'sk sound music "warm lofi piano bed, slow, soft" --seconds 30 --out music/bed.wav'],
+            ['a sung theme, its third take', 'sk sound music "an epic orchestral theme, brass and choir" --engine ace-step --seed 3 --out music/theme.wav'],
+        ],
+    })
+    prompt = Option.String({ required: true, name: 'prompt' })
+    engine = Option.String('--engine', { description: 'stable-audio (default) or ace-step' })
+    seconds = Option.String('--seconds', { description: 'seconds made (default 30)' })
+    seed = Option.String('--seed', { description: 'the take (default 1)' })
+    comfy = Option.String('--comfy', { description: COMFY })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const [{ resolve }, { genMusic }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            const engine = this.engine ?? 'stable-audio'
+            if (engine !== 'stable-audio' && engine !== 'ace-step') throw new Error(`--engine ${engine}: stable-audio or ace-step`)
+            const comfy = this.comfy ?? (await brandSound(root))?.comfy
+            await genMusic({ prompt: this.prompt.replaceAll('\\n', '\n'), engine, seconds: num('--seconds', this.seconds, 30), seed: num('--seed', this.seed, 1), comfy, out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMidiCommand extends Command {
+    static override paths = [['sound', 'midi']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a MIDI file through the soundfont: FluidSynth, its own room on, -16 LUFS',
+        details: `the machine's fluidsynth and ~/.local/share/soundfonts/GeneralUser-GS.sf2 (SK_SOUNDFONT names another). ${PAGE}`,
+        examples: [['a .mid as a wav', 'sk sound midi theme.mid --out music/theme.wav']],
+    })
+    file = Option.String({ required: true, name: 'file.mid' })
+    out = Option.String('--out', { description: 'the file it writes (required)' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, _root, cwd) => {
+            const [{ resolve }, { genMidi }] = await Promise.all([import('node:path'), import('../trailer/sound/gen.ts')])
+            await genMidi({ file: resolve(cwd, this.file), out: resolve(cwd, outOf(this.out)), say })
+        })
+    }
+}
+
+export class SoundMeasureCommand extends Command {
+    static override paths = [['sound', 'measure']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'a sound as numbers and a picture: length, peak, loudness, onsets, the waveform png',
+        details: `nobody hears a build: read these before you report a sound. The png lands at <file>.png. ${PAGE}`,
+        examples: [['a made sfx', 'sk sound measure sfx/clash.wav']],
+    })
+    file = Option.String({ required: true, name: 'file' })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say, _root, cwd) => {
+            const [{ resolve }, { measure, measureLine, waveformPng }] = await Promise.all([import('node:path'), import('../trailer/sound/audio.ts')])
+            const f = resolve(cwd, this.file)
+            say(`${this.file}: ${measureLine(await measure(f))}`)
+            await waveformPng(f, `${f}.png`)
+            say(`ok: ${f}.png`)
+        })
+    }
+}
+
+export class SoundGmCommand extends Command {
+    static override paths = [['sound', 'gm']]
+    static override usage = Command.Usage({
+        category: 'Sound',
+        description: 'the General MIDI programs, drums and kits a score\'s gm: instruments take',
+        details: `a score track plays one through the soundfont: track piano gm:acoustic-grand, drums k=gm:kick, or gm('strings', { vol, pan, reverb }) in its code. ${PAGE}`,
+        examples: [['every name', 'sk sound gm']],
+    })
+
+    execute(): Promise<number> {
+        return run(this.context, async (say) => {
+            const { gmTable } = await import('../trailer/score/gm.ts')
+            for (const l of gmTable()) say(l)
+        })
+    }
+}
+
+export const SOUND_COMMANDS = [SoundVoiceCommand, SoundSfxCommand, SoundMusicCommand, SoundMidiCommand, SoundMeasureCommand, SoundGmCommand]

package/src/cli/cmd_Time.ts

@@ -0,0 +1,112 @@
+// `sk time`: where the agents' time went in a repo, read from every Claude
+// Code transcript on the machine (every config root, sub-agents included)
+// through the agent time index (agent-time/store.ts). REPORT ONLY: exit 0 with
+// a report, 1 when nothing matched, 2 on a bad flag.
+import { Command, Option } from 'clipanion'
+import { resolve } from 'path'
+
+const BIG_BYTES = 50 * 1024 * 1024
+
+export class TimeCommand extends Command {
+    static override paths = [['time']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'where agent time went in a repo, every account: waits, slow and failing commands, feedback',
+        details: [
+            'Reads every Claude Code transcript under every config root (~/.claude, ~/.claude-<name>), sub-agent runs included, through an index at ~/.shipkit/agent-time.sqlite.',
+            'The first run builds the index (niced, resumable, progress on stderr); later runs read only what changed. The index keeps sessions Claude Code has pruned.',
+            'Views: summary (default), commands, tools, slow, fails, feedback, sessions, turns. A Bash command is grouped by its shape (`git commit`, `bun test <file>`, `sk ci --only lint`).',
+            'Turns: every call costs a model turn before it, so the summary gives the model time before each call, the share of single read calls and the share sent in parallel, for the main sessions and the sub-agents; `turns` lists the runs and the read shapes by the model time they cost.',
+            'Wall time is cut once per moment: tools in flight, a sub-agent in flight, waiting on a background task, waiting on you (an idle gap past 30 minutes is left out), else the model.',
+            'Commands and prompts are masked through the leak guard keyword list and token shapes before they print.',
+        ].join(' '),
+        examples: [
+            ['this repo, the last 7 days', 'sk time'],
+            ['every command shape, 30 days', 'sk time commands --since 30d'],
+            ['what he said while it ran', 'sk time feedback --since all'],
+            ['the runs by their turns, and what the reads cost', 'sk time turns --since 30d'],
+            ['two repos, every recorded session', 'sk time ~/dev/pkm-multi ~/dev/procedural-creatures --since all'],
+            ['every repo on the machine', 'sk time --all'],
+            ['for a script', 'sk time --json'],
+        ],
+    })
+
+    args = Option.Rest()
+    all = Option.Boolean('--all', false, { description: 'every repo with transcripts on this machine' })
+    since = Option.String('--since', '7d', { description: '30m, 2h, 7d, a date, or all' })
+    top = Option.String('--top', '20', { description: 'rows per list in a sub view' })
+    json = Option.Boolean('--json', false, { description: 'the whole report as json' })
+
+    async execute(): Promise<number> {
+        const { VIEWS, render } = await import('../agent-time/render.ts')
+        const { sinceOf } = await import('./kit/calls.ts')
+        const err = this.context.stderr
+        const tty = (err as { isTTY?: boolean }).isTTY === true
+        const views = this.args.filter((a) => (VIEWS as readonly string[]).includes(a))
+        const repoArgs = this.args.filter((a) => !views.includes(a))
+        const bad = repoArgs.find((a) => !a.includes('/') && !a.startsWith('.') && !a.startsWith('~'))
+        if (views.length > 1 || bad != null) {
+            err.write(`FAIL: ${bad == null ? `one view at a time, not ${views.join(' and ')}` : `unknown view '${bad}'`}: ${VIEWS.join(', ')}, or a repo path\n`)
+            return 2
+        }
+        const view = (views[0] ?? 'summary') as (typeof VIEWS)[number]
+        const now = Date.now()
+        const from = this.since === 'all' ? null : sinceOf(this.since, now)
+        if (from === null && this.since !== 'all') {
+            err.write(`FAIL: --since ${this.since}: 30m, 2h, 7d, a date, or all\n`)
+            return 2
+        }
+        const top = Number(this.top)
+        if (!Number.isInteger(top) || top <= 0) {
+            err.write(`FAIL: --top ${this.top}: a positive whole number\n`)
+            return 2
+        }
+
+        const { indexTranscripts, listTranscripts, loadWindow, markGone, openIndex, repoOfProject, agentTimeDbPath } = await import('../agent-time/store.ts')
+        const { discoverConfigRoots, projectSlug } = await import('../reflect/prompt-corpus.ts')
+        const { buildReport } = await import('../agent-time/report.ts')
+        const { loadMasker } = await import('../agent-time/mask.ts')
+
+        const repos = repoArgs.length > 0 ? repoArgs.map((r) => resolve(r)) : [process.cwd()]
+        const slugs = repos.map(projectSlug)
+        const keep = this.all ? () => true : (p: string) => slugs.some((s) => p === s || p.startsWith(`${s}--claude-worktrees-`))
+        const roots = discoverConfigRoots()
+        const db = openIndex()
+        try {
+            const files = listTranscripts(roots, keep)
+            const pending = files.length
+            const tIndex = performance.now()
+            let lastPrint = 0
+            let niced = false
+            const res = indexTranscripts(db, files, (p) => {
+                if (p.bytes < BIG_BYTES) return
+                if (!niced) {
+                    niced = true
+                    try { (require('os') as typeof import('os')).setPriority(0, 15) } catch { /* not allowed: index at the normal priority */ }
+                }
+                const t = performance.now()
+                if (t - lastPrint < (tty ? 200 : 10_000) && p.done < p.files) return
+                lastPrint = t
+                const line = `index: ${p.done}/${p.files} files, ${(p.doneBytes / 1e9).toFixed(1)}/${(p.bytes / 1e9).toFixed(1)} GB, ${Math.round((t - tIndex) / 1000)}s`
+                err.write(tty ? `\r${line}` : `${line}\n`)
+            })
+            if (res.bytes >= BIG_BYTES) err.write(`${tty ? '\n' : ''}index: read ${res.read} of ${pending} files, ${(res.bytes / 1e9).toFixed(2)} GB in ${(res.ms / 1000).toFixed(1)}s (${agentTimeDbPath()})\n`)
+            markGone(db, files, keep)
+            const loaded = loadWindow(db, keep, from ?? 0, now)
+            const labels = this.all ? [...new Set(loaded.files.map((f) => repoOfProject(f.project)))].sort() : slugs.map((s) => repoOfProject(s))
+            if (loaded.files.length === 0) {
+                err.write(`FAIL: no agent session in ${labels.join(', ') || 'any repo'} ${from == null ? 'ever' : `since ${new Date(from).toISOString().slice(0, 10)}`}\n`)
+                err.write(`      looked under: ${roots.map((r) => r.projects).join(' · ')}\n`)
+                err.write(`      fix: widen it, --since all, or name a repo that ran Claude Code sessions\n`)
+                return 1
+            }
+            const report = buildReport(loaded, { repos: labels, from, to: now, repoOf: (p) => repoOfProject(p) }, loadMasker(repos[0] ?? null))
+            if (this.json) this.context.stdout.write(`${JSON.stringify(report)}\n`)
+            else this.context.stdout.write(render(report, view, top))
+            return 0
+        } finally {
+            db.close()
+        }
+    }
+}

package/src/cli/cmd_Trailer.ts

@@ -2,7 +2,7 @@
 // Every module loads inside execute: the cli registers this file on every `sk` call
 import { Command, Option } from 'clipanion'
 
-const DETAILS = `the trailer language: shots with a film line each (clip <file>, image <file>, card, run "<cmd {out}>", url <route> through the shot service, or a film row of the project CLI), titles in the brand's look, cuts, sections in bars, music, sfx and voice; a \`vertical\` header finishes a short with the brand's lockup, watermark and end card. Outputs land in trailer/<trailer>/out/. Page: wiki build/trailer.md`
+const DETAILS = `the trailer language: shots with a film line each (clip <file>, image <file>, card, run "<cmd {out}>", url <route> through the shot service, grid and split of other takes, or a film row of the project CLI), footage blocks, titles in the brand's look, cuts, sections in bars, music, sfx and voice; a \`vertical\` header finishes a short with the brand's lockup, watermark and end card. A repo plugs in one trailer({...}) unit: sounds by id, the world's paths, content checks, a line's own take. Outputs land in trailer/<trailer>/out/. Page: wiki build/trailer.md`
 
 /** --refilm alone: every stale take; --refilm a,b: those shots */
 const refilmOf = (v: string | boolean | undefined): 'stale' | ReadonlySet<string> | null => (v === undefined || v === false ? null : v === true ? 'stale' : new Set(v.split(',')))
@@ -32,17 +32,19 @@ export class TrailerCommand extends Command {
             ['one cut by its file', 'sk trailer trailer/launch/main.trailer'],
             ['film again the takes of two shots', 'sk trailer --refilm intro,menu'],
             ['encoded by x264 for a release', 'sk trailer --final'],
+            ['the music variant b on the same picture', 'sk trailer --variant b'],
         ],
     })
 
     file = Option.String({ required: false })
     refilm = Option.String('--refilm', { tolerateBoolean: true, description: 'film again: every stale take, or the named shots (a,b)' })
     final = Option.Boolean('--final', false, { description: 'encode with x264 for a release (default: the fast draft encoder)' })
+    variant = Option.String('--variant', { description: 'a music variant the cut names (music … variant <name>): out/<name>-<variant>.mp4' })
 
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root, this.variant !== undefined ? { variant: this.variant } : {})
             if (!b.sayErrors(l, say, cwd)) return 1
             await b.build(l, { refilm: refilmOf(this.refilm), final: this.final, say, cwd })
             return 0
@@ -64,21 +66,49 @@ export class TrailerCheckCommand extends Command {
     })
 
     file = Option.String({ required: false })
+    variant = Option.String('--variant', { description: 'a music variant the cut names' })
 
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const t0 = performance.now()
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root, this.variant !== undefined ? { variant: this.variant } : {})
             if (!b.sayErrors(l, say, cwd)) return 1
-            const { takesOf, worldStamp } = await import('../trailer/footage.ts')
-            for (const line of b.timeline(l, takesOf(l.t, root), worldStamp(root), cwd)) say(line)
+            for (const line of b.timeline(l, b.takesOfLoaded(l), await b.worldOf(l), cwd)) say(line)
+            for (const line of await b.soundLines(l)) say(`  ${line}`)
+            for (const line of await b.fontLines(l)) say(`  ${line}`)
             say(`ok: checked in ${((performance.now() - t0) / 1000).toFixed(2)} s`)
             return 0
         })
     }
 }
 
+export class TrailerScoreCommand extends Command {
+    static override paths = [['trailer', 'score']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'the score alone, no picture: its wav, its waveform png, each section\'s level and the loudness',
+        details: `${DETAILS}. The score renders offline in Bun from the file's score, track, drums, code, section and play lines; a section whose notes are silent fails`,
+        examples: [
+            ['the score of the one cut', 'sk trailer score'],
+            ['the score of a named cut', 'sk trailer score trailer/launch'],
+        ],
+    })
+
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            await b.auditionScore(l, { refilm: null, final: false, say, cwd })
+            return 0
+        })
+    }
+}
+
 export class TrailerShotCommand extends Command {
     static override paths = [['trailer', 'shot']]
 
@@ -99,10 +129,238 @@ export class TrailerShotCommand extends Command {
     async execute(): Promise<number> {
         return run(this.context, async (say, root, cwd) => {
             const b = await import('../trailer/build.ts')
-            const l = b.load(b.trailerFile(this.file, root, cwd), root)
+            const l = await b.load(b.trailerFile(this.file, root, cwd), root)
             if (!b.sayErrors(l, say, cwd)) return 1
             await b.previewShot(l, this.name, { refilm: refilmOf(this.refilm), final: false, say, cwd })
             return 0
         })
     }
 }
+
+/** a cut loaded and checked, its errors said; null when it has one */
+async function loaded(file: string | undefined, say: (l: string) => void, root: string, cwd: string) {
+    const b = await import('../trailer/build.ts')
+    const l = await b.load(b.trailerFile(file, root, cwd), root)
+    return b.sayErrors(l, say, cwd) ? l : null
+}
+
+export class TrailerSectionCommand extends Command {
+    static override paths = [['trailer', 'section']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'one section alone with its window of the sound: out/<cut>-<section>.mp4',
+        details: `${DETAILS}. \`start\` is the shots before the first section; only a section the cache misses renders`,
+        examples: [['a section of the one cut', 'sk trailer section drop']],
+    })
+
+    name = Option.String({ required: true })
+    file = Option.String({ required: false })
+    final = Option.Boolean('--final', false, { description: 'encode with x264 for a release' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            await (await import('../trailer/build.ts')).previewSection(l, this.name, { refilm: null, final: this.final, say, cwd })
+            return 0
+        })
+    }
+}
+
+export class TrailerLevelsCommand extends Command {
+    static override paths = [['trailer', 'levels']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'each section\'s mean and peak in the built mp4, and its step from the section before',
+        details: DETAILS,
+        examples: [['the levels of the one cut', 'sk trailer levels']],
+    })
+
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            await (await import('../trailer/passage.ts')).levels(l, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerClipCommand extends Command {
+    static override paths = [['trailer', 'clip']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'a passage of the built cut with its sound, from a section, mark, shot or second',
+        details: `${DETAILS}. --version cuts the same passage of a kept version beside it, read from versions/<v>.trailer`,
+        examples: [
+            ['a section', 'sk trailer clip drop'],
+            ['from a shot to a mark, before and after', 'sk trailer clip hero hit --version v3'],
+        ],
+    })
+
+    from = Option.String({ required: true })
+    rest = Option.Rest({ required: 0 })
+    version = Option.String('--version', { description: 'a kept version (v<n>): the same passage of it beside' })
+    pad = Option.String('--pad', { description: 'seconds of room before and after' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const { existsSync } = await import('node:fs')
+            const { resolve } = await import('node:path')
+            // the second word is a moment unless it names a file or a folder
+            const [a, b] = this.rest
+            const isPath = (w: string | undefined): boolean => w !== undefined && (w.endsWith('.trailer') || existsSync(resolve(cwd, w)))
+            const to = a !== undefined && !isPath(a) ? a : this.from
+            const file = a !== undefined && !isPath(a) ? b : a
+            const l = await loaded(file, say, root, cwd)
+            if (!l) return 1
+            const pad = Number(this.pad ?? 0)
+            if (!Number.isFinite(pad) || pad < 0) throw new Error(`--pad wants seconds, got ${this.pad}`)
+            await (await import('../trailer/passage.ts')).clip(l, this.from, to, pad, this.version, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerKeepCommand extends Command {
+    static override paths = [['trailer', 'keep']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'keep the built cut as a version: versions/v<n>.trailer, its video, strip and takes',
+        details: `${DETAILS}. Refuses a version already kept; prints the index row, commit and tag left to do`,
+        examples: [['keep the one cut', 'sk trailer keep v4']],
+    })
+
+    version = Option.String({ required: true })
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            ;(await import('../trailer/passage.ts')).keep(l, this.version, say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerFootageCommand extends Command {
+    static override paths = [['trailer', 'footage']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'the take file of each shot or footage block, the raw take before the stitch trims it',
+        details: DETAILS,
+        examples: [['two shots of the one cut', 'sk trailer footage intro,hero']],
+    })
+
+    names = Option.String({ required: true })
+    file = Option.String({ required: false })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const l = await loaded(this.file, say, root, cwd)
+            if (!l) return 1
+            ;(await import('../trailer/passage.ts')).footage(l, this.names.split(','), say, cwd)
+            return 0
+        })
+    }
+}
+
+export class TrailerWatchCommand extends Command {
+    static override paths = [['trailer', 'watch']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'build again after each save in the cut\'s folder (ctrl-c stops)',
+        details: DETAILS,
+        examples: [['the one cut', 'sk trailer watch']],
+    })
+
+    file = Option.String({ required: false })
+    final = Option.Boolean('--final', false, { description: 'encode with x264 for a release' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root, cwd) => {
+            const b = await import('../trailer/build.ts')
+            const { watch } = await import('node:fs')
+            const { dirname, relative } = await import('node:path')
+            const file = b.trailerFile(this.file, root, cwd)
+            let busy = false
+            let again = false
+            const once = async (): Promise<void> => {
+                if (busy) {
+                    again = true
+                    return
+                }
+                busy = true
+                try {
+                    const l = await b.load(file, root, { fresh: true })
+                    if (b.sayErrors(l, say, cwd)) await b.build(l, { refilm: null, final: this.final, say, cwd })
+                } catch (e) {
+                    say(`FAIL: ${e instanceof Error ? e.message : String(e)}`)
+                }
+                busy = false
+                if (again) {
+                    again = false
+                    await once()
+                }
+            }
+            await once()
+            say(`watching ${relative(cwd, file)} and its folder's recipes (ctrl-c stops)`)
+            let timer: ReturnType<typeof setTimeout> | null = null
+            watch(dirname(file), (_, f) => {
+                if (!f || f.startsWith('out') || f.startsWith('versions') || f.endsWith('.md')) return
+                if (timer) clearTimeout(timer)
+                timer = setTimeout(() => void once(), 200)
+            })
+            await new Promise(() => undefined)
+            return 0
+        })
+    }
+}
+
+export class TrailerPruneCommand extends Command {
+    static override paths = [['trailer', 'prune']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'trim the trailer cache to what the cuts use, what each folder frees',
+        details: `${DETAILS}. Every build, section and shot runs it after its stitch; a file younger than an hour stays`,
+        examples: [
+            ['what it would free', 'sk trailer prune --dry'],
+            ['free it', 'sk trailer prune'],
+        ],
+    })
+
+    dry = Option.Boolean('--dry', false, { description: 'say what each folder would free, delete nothing' })
+
+    async execute(): Promise<number> {
+        return run(this.context, async (say, root) => {
+            const { prune, sayPruned } = await import('../trailer/prune.ts')
+            for (const line of sayPruned(await prune(root, { dry: this.dry }), this.dry)) say(line)
+            return 0
+        })
+    }
+}
+
+/** every `sk trailer` verb, registered by cli.ts */
+export const TRAILER_COMMANDS = [
+    TrailerCommand,
+    TrailerCheckCommand,
+    TrailerScoreCommand,
+    TrailerShotCommand,
+    TrailerSectionCommand,
+    TrailerLevelsCommand,
+    TrailerClipCommand,
+    TrailerKeepCommand,
+    TrailerFootageCommand,
+    TrailerWatchCommand,
+    TrailerPruneCommand,
+]