rvlib-shipkit 2.1.1 → 2.3.0

package/src/cli/cmd_Shot.ts

@@ -0,0 +1,63 @@
+// sk shot: a png of any url, or a clip with --video, through the machine's
+// one warm browser (shot/client.ts). A repo's own CLI wraps it with its setup
+// flags; the trailer's `url` film calls the same functions.
+import { relative } from 'path'
+import { Command, Option } from 'clipanion'
+import { clipUrl, shotUrl, type ShotResult } from '../shot/client.ts'
+import { askOf, isClip } from '../shot/shot-ask.ts'
+
+export const renderShot = (r: ShotResult, cwd: string): string[] => {
+    const phases = Object.entries(r.phases)
+        .map(([k, v]) => `${k} ${v}`)
+        .join(', ')
+    const out = relative(cwd, r.out)
+    const lines = [`ok ${out.startsWith('..') ? r.out : out} in ${r.ms} ms (${phases}; ${r.via}) ${r.note}`]
+    for (const e of r.errors.slice(0, 10)) lines.push(`WARN page ${e}`)
+    if (r.errors.length > 10) lines.push(`WARN page ${r.errors.length - 10} more errors`)
+    return lines
+}
+
+export class ShotCommand extends Command {
+    static override paths = [['shot']]
+
+    static override usage = Command.Usage({
+        category: 'Serve',
+        description: 'a png of any url through the warm browser, or an mp4 clip with --video',
+        details:
+            'one warm headless chromium for the whole machine (the `shot` global process, started when down). A still reuses the warm page when it already shows the url, so a warm shot answers in about 0.1 s. A page with `<meta name="shot-ready" content="wait">` is shot once it sets content="ready"; any other page --wait ms after its load. --video films a page that is a canvas through its WebCodecs encoder (H.264 muxed with no second encode), and any other page as chromium paints it (its screencast, encoded by ffmpeg as the frames arrive); --dom films the page even when a canvas fills it',
+        examples: [
+            ['a png of a running dev server', 'sk shot localhost:5173/'],
+            ['a phone screen, at the pixel ratio of a phone', 'sk shot :5173/play --viewport 390,844 --dpr 3 --out shots/phone.png'],
+            ['a 3 s clip', 'sk shot :4808/ --video 3 --out clips/walk.mp4'],
+            ['a clip of a whole web app page, canvas or not', 'sk shot :5173/settings --video 3 --dom'],
+        ],
+    })
+
+    url = Option.String({ required: true, name: 'url' })
+    viewport = Option.String('--viewport', { description: 'w,h in css pixels (default 1280,720)' })
+    dpr = Option.String('--dpr', { description: 'device pixel ratio (default 1)' })
+    out = Option.String('--out', { description: 'the file (default .shipkit/tmp/shots/<url>.png, or .mp4 with --video)' })
+    reload = Option.Boolean('--reload', false, { description: 'load the page again even when the warm page shows this url' })
+    wait = Option.String('--wait', { description: 'ms after load for a page with no ready mark (default 300)' })
+    video = Option.String('--video', { description: 'seconds of clip: an mp4 of the page (its canvas when a canvas fills it)' })
+    fps = Option.String('--fps', { description: 'clip frames per second (default 30)' })
+    long = Option.Boolean('--long', false, { description: 'allow a clip past 30 s' })
+    dom = Option.Boolean('--dom', false, { description: 'clip the page itself even when a canvas fills it' })
+    json = Option.Boolean('--json', false, { description: 'one json line: out, ms, phases, errors, note, via' })
+
+    async execute(): Promise<number> {
+        const cwd = process.cwd()
+        const err = (l: string) => this.context.stderr.write(`${l}\n`)
+        try {
+            const a = askOf({ url: this.url, viewport: this.viewport, dpr: this.dpr, out: this.out, reload: this.reload, wait: this.wait, video: this.video, fps: this.fps, long: this.long, dom: this.dom }, cwd)
+            const r = isClip(a) ? await clipUrl(a, err) : await shotUrl(a, err)
+            if (this.json) this.context.stdout.write(`${JSON.stringify(r)}\n`)
+            else for (const l of renderShot(r, cwd)) this.context.stdout.write(`${l}\n`)
+            return 0
+        } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e)
+            err(msg.startsWith('FAIL') ? msg : `FAIL shot: ${msg}`)
+            return 1
+        }
+    }
+}

package/src/cli/cmd_Start.ts

@@ -1,8 +1,7 @@
 // shipkit start — ensure <root>/<name> exists (+ a CLAUDE.md include),
 // printing the dir on stdout so a shell alias can cd there (a child process
-// can't cd its parent). Thin clipanion surface; logic in start-repo.ts.
+// can't cd its parent). Thin clipanion surface; logic in start-repo.ts, imported when it runs.
 import { Command, Option } from 'clipanion'
-import { startRepo } from '../start-repo.ts'
 
 export class StartCommand extends Command {
     static override paths = [['start']]
@@ -10,13 +9,14 @@ export class StartCommand extends Command {
     static override usage = Command.Usage({
         category: 'Setup',
         description: 'create or enter ~/dev/<name>, ready to work in: a private github repo and a push unless --no-github',
-        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
+        details: 'create (or enter) ~/dev/<name> from ANY cwd, READY to work in. On any dir with no commit history it writes the day-one shape (package.json + src/index.ts + the project CLI on the kit (src/cli.ts, src/cli/cmd_Dev.ts, the cli script and a bin of the repo name) + lint/fmt/typecheck, tsconfig, .vscode tasks + settings, the verify skill, an agent/ wiki, .shipkit/reflections), installs the toolchain, wires shipkit (repo.config.ts via init), and runs the whole bootstrap chain: git init, first commit, PRIVATE github repo, push. Loose files ride in that first commit, and only a repo with real history is left as it is. Writes are create-only for files, additive for package.json scripts and .gitignore. CLAUDE.md is the two-line house template on its own (HOUSE_INCLUDE in src/start-repo.ts: the base wiki include, then `@./agent/index.md`, and --include overrides it), applied only on a machine where the house index exists, and the agent route lands last whenever the repo has agent/index.md. The house lines also opt the repo into the .claude/ policy files (a pre-approved shell allowlist + the attribution silencer), so a start with no house widens no agent permissions. Prints the dir on stdout so a shell alias can cd there. cwd-only sibling: `shipkit init`',
         examples: [
             ['create or enter ~/dev/pong: dir, package.json, shipkit wiring, git, first commit, private github repo, push, the two-line CLAUDE.md', 'sk start pong'],
             ['another house: replace the include lines', "sk start pong --include '@~/wiki/index.md' --include '@./agent/index.md'"],
             ['adopt a pre-existing repo from anywhere', 'sk start my-old-project'],
             ['force the private github repo for a folder that was already there', 'sk start old-notes --github'],
             ['local git and the first commit, never touch github', 'sk start pong --no-github'],
+            ['give an existing repo its project CLI (a started repo has one)', 'sk start my-old-project --cli'],
         ],
     })
 
@@ -27,7 +27,11 @@ export class StartCommand extends Command {
     skip = Option.Array('--skip', { description: 'repo names shipkit never touches: no CLAUDE.md include, no wiring. Omitted: the house list (HOUSE_SKIP in src/start-repo.ts)' })
     github = Option.Boolean('--github', { description: 'ON by default when a repo is being STARTED (a dir this run created, or one with a package.json): it gets a PRIVATE github repo wired as origin, and the first commit is pushed to it. Pass --github to force it for a pre-existing folder, --no-github to keep everything local, the first commit included (SHIPKIT_NO_GITHUB=1 does it for every run)' })
 
+    withCli = Option.Boolean('--cli', false, { description: 'on a repo with history: write the project CLI skeleton (src/cli.ts on the kit, an example family, package.json cli and bin), refused when the repo already has a CLI. A started repo always gets it' })
+
     async execute(): Promise<number> {
-        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip, github: this.github })
+        // loaded here, so the scaffold and the git chain cost nothing to every other command
+        const { startRepo } = await import('../start-repo.ts')
+        return startRepo(this.name, { root: this.root, include: this.include, alsoOk: this.alsoOk, skip: this.skip, github: this.github, cli: this.withCli })
     }
 }

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

@@ -0,0 +1,361 @@
+// sk trailer: a cut's .trailer file → its mp4, filming only the takes whose film line changed (trailer/build.ts).
+// 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, 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(',')))
+
+async function run(context: { stdout: NodeJS.WritableStream; stderr: NodeJS.WritableStream }, body: (say: (l: string) => void, root: string, cwd: string) => Promise<number>): Promise<number> {
+    const say = (l: string): void => void context.stdout.write(`${l}\n`)
+    const { Refused } = await import('../trailer/build.ts')
+    const { findRepoRoot } = await import('../ts/config.ts')
+    const cwd = process.cwd()
+    try {
+        return await body(say, findRepoRoot(cwd), cwd)
+    } catch (e) {
+        context.stderr.write(`FAIL: ${e instanceof Refused ? `trailer: ${e.message}` : e instanceof Error ? (e.stack ?? e.message) : String(e)}\n`)
+        return 1
+    }
+}
+
+export class TrailerCommand extends Command {
+    static override paths = [['trailer']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'build a cut from its .trailer: film what is missing, stitch, strip, montage',
+        details: DETAILS,
+        examples: [
+            ['the one cut under trailer/', 'sk trailer'],
+            ['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'],
+        ],
+    })
+
+    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)' })
+
+    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.build(l, { refilm: refilmOf(this.refilm), final: this.final, say, cwd })
+            return 0
+        })
+    }
+}
+
+export class TrailerCheckCommand extends Command {
+    static override paths = [['trailer', 'check']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'parse and check a .trailer: every error at its line, the timeline, each take\'s state',
+        details: DETAILS,
+        examples: [
+            ['the one cut under trailer/', 'sk trailer check'],
+            ['one cut by its folder', 'sk trailer check trailer/launch'],
+        ],
+    })
+
+    file = Option.String({ required: false })
+
+    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 = await b.load(b.trailerFile(this.file, root, cwd), root)
+            if (!b.sayErrors(l, say, cwd)) return 1
+            for (const line of b.timeline(l, b.takesOfLoaded(l), await b.worldOf(l), cwd)) 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']]
+
+    static override usage = Command.Usage({
+        category: 'Trailer',
+        description: 'one shot alone with its titles, no sound, and its nine frames on one png',
+        details: DETAILS,
+        examples: [
+            ['a shot of the one cut', 'sk trailer shot intro'],
+            ['a shot of a named cut, its take filmed again', 'sk trailer shot intro trailer/launch --refilm intro'],
+        ],
+    })
+
+    name = Option.String({ required: true })
+    file = Option.String({ required: false })
+    refilm = Option.String('--refilm', { tolerateBoolean: true, description: 'film again: every stale take, or the named shots (a,b)' })
+
+    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.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,
+]

package/src/cli/kit/builtins.ts

@@ -0,0 +1,40 @@
+// the commands every project CLI gets for free: its docs pages and its call
+// log. They are shipkit's own `commands` and `calls` classes, given the
+// project's name in their examples and the project's root for the log.
+import { Command } from 'clipanion'
+import { CallsCommand } from '../cmd_Calls.ts'
+import { CommandsCommand } from '../cmd_Commands.ts'
+import { callsFile } from './calls.ts'
+import type { CommandClass, KitContext } from './verb.ts'
+
+export function builtinCommands(bin: string): { docs: CommandClass[]; calls: CommandClass[] } {
+    class ProjectCommands extends CommandsCommand {
+        static override usage = Command.Usage({
+            category: 'Docs',
+            description: `every ${bin} command as markdown or json; --out writes the commands page`,
+            details: `the registry described by itself. --out rewrites the block between the ${bin}:commands markers, --essentials rewrites the everyday page whole, --check fails while a page lags the registry or a row lacks its category, description or example. --json is how another tool reads this registry.`,
+            examples: [
+                ['the markdown', `${bin} commands`],
+                ['as json, for another tool', `${bin} commands --json`],
+                ['write both agent pages', `${bin} commands --out agent/${bin}.md --essentials agent/${bin}-essentials.md`],
+                ['fail when a page is stale', `${bin} commands --out agent/${bin}.md --essentials agent/${bin}-essentials.md --check`],
+            ],
+        })
+        static override shapeRule = true
+    }
+    class ProjectCalls extends CallsCommand {
+        static override usage = Command.Usage({
+            category: 'Docs',
+            description: `every ${bin} run logged with its time: per command how often, how long, the slowest`,
+            details: `reads .shipkit/logs/${bin}-calls.jsonl under the repo root. A run with no end line was killed or still runs. ${bin.toUpperCase()}_LOG=off writes nothing.`,
+            examples: [
+                ['what agents waited on today', `${bin} calls --since 1d`],
+                ['one family', `${bin} calls --cmd <family>`],
+            ],
+        })
+        override logFile(): string {
+            return callsFile((this.context as unknown as KitContext).root, bin)
+        }
+    }
+    return { docs: [ProjectCommands as unknown as CommandClass], calls: [ProjectCalls as unknown as CommandClass] }
+}