rvlib-shipkit 2.1.1 → 2.3.0

package/src/cli/kit/calls.ts

@@ -0,0 +1,177 @@
+// every run of a CLI, logged: a start line at launch, an end line at any exit
+// with its time, CPU and memory, the same id on both. A start with no end was
+// killed or still runs. JSON lines, one append each, so runs at once never mix.
+// `<cli> calls` reads it back, so a speed pass starts from what agents waited on.
+// `<CLI>_LOG=off` writes nothing, and neither does a run under `bun test`. Past
+// 2 MB the log moves to `<file>.1` and starts again, so it never grows unbounded.
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { LAYOUT } from '../../core/layout.ts'
+
+export type CallStart = {
+    id: string
+    at: string
+    argv: string[]
+    cwd: string
+    pid: number
+    /** `<CLI>_AGENT`, else null: who ran it */
+    agent: string | null
+    /** the run of the same CLI that spawned this one, null for a run of its own */
+    parent: string | null
+}
+
+export type CallEnd = {
+    id: string
+    /** the command's path, null when none matched (a listing, a typo) */
+    cmd: string | null
+    /** from the process start */
+    ms: number
+    /** building the registry: the import of the families the call needed */
+    loadMs: number
+    cpuMs: number
+    rssMb: number
+    code: number
+}
+
+/** where a CLI's calls go: `<root>/.shipkit/logs/<bin>-calls.jsonl` */
+export const callsFile = (root: string, bin: string): string => join(root, LAYOUT.logs, `${bin}-calls.jsonl`)
+
+/** the env prefix of a CLI: `my-tool` → `MY_TOOL` */
+export const envPrefix = (bin: string): string => bin.toUpperCase().replace(/[^A-Z0-9]/g, '_')
+
+/** past this size the log moves to `<file>.1` (replacing the older one) and starts again */
+export const CALLS_MAX_BYTES = 2 * 1024 * 1024
+
+/** a long argument (a pasted text) is cut, so a line stays one append */
+const ARG_MAX = 300
+
+/** logs this run's start, and its end on any exit. The caller names the
+ *  command and the registry load time once it knows them */
+export function logCall(file: string, bin: string, argv: readonly string[], env: NodeJS.ProcessEnv = process.env): { matched(cmd: string | null, loadMs: number): void } {
+    const pre = envPrefix(bin)
+    if (env[`${pre}_LOG`] === 'off' || env.NODE_ENV === 'test') return { matched: () => {} }
+    let warned = false
+    try { if (statSync(file).size > CALLS_MAX_BYTES) renameSync(file, `${file}.1`) } catch { /* no log yet */ }
+    const append = (line: object): void => {
+        try {
+            mkdirSync(dirname(file), { recursive: true })
+            appendFileSync(file, `${JSON.stringify(line)}\n`)
+        } catch (e) {
+            if (!warned) console.error(`WARN ${bin}: the call log could not be written (${file}): ${(e as Error).message}`)
+            warned = true
+        }
+    }
+    const id = `${Date.now().toString(36)}-${process.pid}`
+    const end: Pick<CallEnd, 'cmd' | 'loadMs'> = { cmd: null, loadMs: 0 }
+    const start: CallStart = {
+        id,
+        at: new Date().toISOString(),
+        argv: argv.map((a) => (a.length > ARG_MAX ? `${a.slice(0, ARG_MAX)}…` : a)),
+        cwd: process.cwd(),
+        pid: process.pid,
+        agent: env[`${pre}_AGENT`]?.trim() || null,
+        parent: env[`${pre}_CALL`] ?? null,
+    }
+    append(start)
+    env[`${pre}_CALL`] = id
+    process.on('exit', (code) => {
+        const cpu = process.cpuUsage()
+        append({ id, ...end, ms: Math.round(performance.now()), cpuMs: Math.round((cpu.user + cpu.system) / 1000), rssMb: Math.round(process.resourceUsage().maxRSS / 1024), code } satisfies CallEnd)
+    })
+    return { matched: (cmd, loadMs) => { end.cmd = cmd; end.loadMs = Math.round(loadMs) } }
+}
+
+export type CallsQuery = {
+    /** epoch ms: only the runs that started after */
+    since?: number
+    /** a command path prefix */
+    cmd?: string
+    /** a folder: only the runs started inside it */
+    under?: string
+    /** keep the runs another run of the same CLI spawned */
+    nested?: boolean
+    /** how many slowest runs to list */
+    top?: number
+    /** the id of the run asking, which has no end yet */
+    self?: string
+}
+
+export type CallsRow = { cmd: string; runs: number; noEnd: number; failed: number; p50: number; p95: number; max: number; totalS: number; loadP50: number; rssMax: number }
+export type CallsReport = { runs: number; rows: CallsRow[]; slowest: { ms: number; at: string; agent: string | null; argv: string }[] }
+
+/** `30m`, `2h`, `3d` or a date, as epoch ms; null when unreadable */
+export function sinceOf(s: string, now: number): number | null {
+    const m = /^(\d+)([mhd])$/.exec(s)
+    if (m) return now - Number(m[1]) * { m: 60e3, h: 3600e3, d: 86400e3 }[m[2] as 'm' | 'h' | 'd']
+    const t = Date.parse(s)
+    return Number.isNaN(t) ? null : t
+}
+
+const quantile = (xs: number[], p: number): number => {
+    if (xs.length === 0) return 0
+    const s = [...xs].sort((a, b) => a - b)
+    return s[Math.min(s.length - 1, Math.floor(p * s.length))] ?? 0
+}
+
+/** the call log read back: per command how often, how long, how heavy, and the slowest runs */
+export function callsReport(text: string, q: CallsQuery = {}): CallsReport {
+    const starts = new Map<string, CallStart>()
+    const ends = new Map<string, CallEnd>()
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') continue
+        let r: CallStart | CallEnd
+        try { r = JSON.parse(line) as CallStart | CallEnd } catch { continue }
+        if ('at' in r) starts.set(r.id, r)
+        else ends.set(r.id, r)
+    }
+    type Run = { s: CallStart; e: CallEnd | null; cmd: string }
+    const runs: Run[] = []
+    for (const s of starts.values()) {
+        if (s.id === q.self || Date.parse(s.at) < (q.since ?? 0) || (q.nested !== true && s.parent != null)) continue
+        if (q.under != null && s.cwd !== q.under && !s.cwd.startsWith(`${q.under}/`)) continue
+        const e = ends.get(s.id) ?? null
+        const flag = s.argv.findIndex((a) => a.startsWith('-'))
+        const words = flag === -1 ? s.argv : s.argv.slice(0, flag)
+        const cmd = e?.cmd ?? (words.slice(0, 2).join(' ') || '(none)')
+        if (q.cmd != null && !cmd.startsWith(q.cmd)) continue
+        runs.push({ s, e, cmd })
+    }
+    const byCmd = new Map<string, Run[]>()
+    for (const r of runs) byCmd.set(r.cmd, [...(byCmd.get(r.cmd) ?? []), r])
+    const rows = [...byCmd].map(([cmd, rs]): CallsRow => {
+        const done = rs.flatMap((r) => (r.e ? [r.e] : []))
+        const ms = done.map((e) => e.ms)
+        return {
+            cmd,
+            runs: rs.length,
+            noEnd: rs.length - done.length,
+            failed: done.filter((e) => e.code !== 0).length,
+            p50: quantile(ms, 0.5),
+            p95: quantile(ms, 0.95),
+            max: Math.max(0, ...ms),
+            totalS: Math.round(ms.reduce((a, b) => a + b, 0) / 1000),
+            loadP50: quantile(done.map((e) => e.loadMs), 0.5),
+            rssMax: Math.max(0, ...done.map((e) => e.rssMb)),
+        }
+    })
+    rows.sort((a, b) => b.totalS - a.totalS || b.p95 - a.p95 || a.cmd.localeCompare(b.cmd))
+    const slowest = runs
+        .flatMap((r) => (r.e ? [{ ms: r.e.ms, at: r.s.at, agent: r.s.agent, argv: r.s.argv.join(' ') }] : []))
+        .sort((a, b) => b.ms - a.ms)
+        .slice(0, q.top ?? 10)
+    return { runs: runs.length, rows, slowest }
+}
+
+/** the report as a table, then the slowest runs */
+export function renderCallsReport(bin: string, r: CallsReport, file: string): string {
+    const head = ['command', 'runs', 'no end', 'failed', 'p50 ms', 'p95 ms', 'max ms', 'total s', 'load p50', 'rss max MB']
+    const table = [head, ...r.rows.map((x) => [x.cmd, x.runs, x.noEnd, x.failed, x.p50, x.p95, x.max, x.totalS, x.loadP50, x.rssMax].map(String))]
+    const widths = head.map((_, i) => Math.max(...table.map((t) => (t[i] ?? '').length)))
+    const out = [`${r.runs} runs · ${file}`, 'a run with no end line was killed or still runs; time is from the process start, load is building the registry', '']
+    for (const t of table) out.push(t.map((c, i) => (i === 0 ? c.padEnd(widths[i] ?? 0) : c.padStart(widths[i] ?? 0))).join('  '))
+    if (r.slowest.length > 0) {
+        out.push('', `the ${r.slowest.length} slowest runs`)
+        for (const s of r.slowest) out.push(`${String(s.ms).padStart(8)} ms  ${s.at.slice(0, 19)}  ${s.agent ?? '-'}  ${bin} ${s.argv}`)
+    }
+    return `${out.join('\n')}\n`
+}

package/src/cli/kit/families.ts

@@ -0,0 +1,67 @@
+// a project CLI is a table of families: the first word of a call loads the
+// family that owns it and nothing else, a word nobody owns (a listing, a typo)
+// loads them all. A family file exports `commands` and imports nothing heavy
+// at its top, so even the full load answers in milliseconds.
+import type { CommandClass } from './verb.ts'
+
+export type Family = {
+    /** the first words its commands start with */
+    roots: string[]
+    load: () => Promise<{ commands: CommandClass[] }>
+    /** its commands read the whole registry (the docs): every family loads with it */
+    all?: true
+}
+
+/** the families a call needs: the one owning its first word, else every one */
+export function familiesFor<F extends Family>(argv: readonly string[], families: readonly F[]): F[] {
+    const own = families.find((f) => f.roots.includes(argv[0] ?? ''))
+    return own != null && own.all !== true ? [own] : [...families]
+}
+
+/** the first words two families both claim: a call would load the wrong one */
+export function rootClashes(families: readonly Family[]): string[] {
+    const seen = new Set<string>()
+    const out = new Set<string>()
+    for (const f of families) for (const r of f.roots) (seen.has(r) ? out : seen).add(r)
+    return [...out]
+}
+
+/** what clipanion tells of a registered command */
+export type ListedDefinition = { path: string; category?: string | null; description?: string | null }
+
+const HELP_WORDS = ['--help', '-h', 'help']
+
+/** a definition's path without the binary name clipanion puts in front */
+export const stripBin = (bin: string, path: string): string => (path.startsWith(`${bin} `) ? path.slice(bin.length + 1) : path)
+
+/** the family word a call asks a listing of: '' for every command, a first
+ *  word for its family, null to run the call. A word that is itself a command runs */
+export function listingOf(bin: string, argv: readonly string[], defs: readonly ListedDefinition[]): string | null {
+    if (argv.length === 0 || (argv.length === 1 && HELP_WORDS.includes(argv[0]!))) return ''
+    if (argv.length > 2 || (argv.length === 2 && !HELP_WORDS.includes(argv[1]!))) return null
+    const word = argv[0]!
+    const paths = defs.map((d) => stripBin(bin, d.path))
+    if (paths.includes(word) || !paths.some((p) => p.startsWith(`${word} `))) return null
+    return word
+}
+
+/** every command of a family (all when ''), one line each, grouped by category */
+export function listing(bin: string, defs: readonly ListedDefinition[], word: string, label?: string): string {
+    const rows = defs
+        .map((d) => ({ path: stripBin(bin, d.path), category: (d.category ?? '').trim() || 'Other', description: (d.description ?? '').trim() }))
+        .filter((r) => !r.path.startsWith('-') && (word === '' || r.path === word || r.path.startsWith(`${word} `)))
+        .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
+    const width = Math.max(0, ...rows.map((r) => r.path.length)) + bin.length + 3
+    const out = word === '' && label != null ? [label, ''] : []
+    let category = ''
+    for (const r of rows) {
+        if (r.category !== category) {
+            if (category !== '') out.push('')
+            out.push(r.category)
+            category = r.category
+        }
+        out.push(`  ${`${bin} ${r.path}`.padEnd(width)}${r.description}`)
+    }
+    out.push('', `${bin} <command> --help: its usage, its examples and its flags`)
+    return `${out.join('\n')}\n`
+}

package/src/cli/kit/index.ts

@@ -0,0 +1,8 @@
+// the project CLI kit: what a repo's `src/cli.ts` and its family files import
+// (`rvlib-shipkit/cli-kit`). Command and Option come from here, so a project
+// needs no clipanion of its own and its classes match the kit's.
+export { Command, Option } from 'clipanion'
+export { type Family, familiesFor, listing, listingOf } from './families.ts'
+export { callsFile, logCall } from './calls.ts'
+export { type ProjectCliSpec, projectCli, runProjectCli } from './project-cli.ts'
+export { argvOf, type AskTool, type CommandClass, type Essential, type Film, filmCall, type KitContext, type Run, type Verb, verbs } from './verb.ts'

package/src/cli/kit/pages-check.ts

@@ -0,0 +1,36 @@
+// the body of a project CLI's pages check (the file `sk start` writes in
+// src/cli/): the CLI's `commands --check` says whether both agent pages match
+// the registry, and the repair writes them. The check file itself declares
+// where it runs, so the policy stays readable in the repo.
+import type { FixResult } from '../../check.ts'
+import type { CheckCtx } from '../../core/check-ctx.ts'
+
+/** the first FAIL line of a run, else what it printed on one line */
+const said = (out: string): string => {
+    const lines = out.trim().split('\n')
+    return lines.find((l) => l.startsWith('FAIL')) ?? lines.join('; ')
+}
+
+export function cliPagesCheck(name: string, entry = 'src/cli.ts'): {
+    description: string
+    inputs: string[]
+    run: (c: CheckCtx) => Promise<void>
+    repair: (c: CheckCtx) => Promise<FixResult>
+} {
+    const all = `agent/${name}.md`
+    const essentials = `agent/${name}-essentials.md`
+    const gen = ['bun', entry, 'commands', '--out', all, '--essentials', essentials]
+    return {
+        description: `the ${name} command pages match its registry`,
+        inputs: [entry, entry.replace(/\.ts$/, ''), all, essentials],
+        run: async (c) => {
+            const r = await c.exec([...gen, '--check'], { cwd: c.root, env: { [`${name.toUpperCase().replace(/[^A-Z0-9]/g, '_')}_LOG`]: 'off' } })
+            if (r.code === 0) c.ok(said(r.out))
+            else c.fail(said(r.out), `${name} ${gen.slice(2).join(' ')}`)
+        },
+        repair: async (c) => {
+            const r = await c.exec(gen, { cwd: c.root })
+            return { changed: r.code === 0 && r.out.includes('rewritten'), summary: said(r.out) }
+        },
+    }
+}

package/src/cli/kit/project-cli.ts

@@ -0,0 +1,73 @@
+// a project's own CLI in one call: `runProjectCli({ name, root, families })`.
+// It loads only the family the first word needs, lists one line per command
+// when asked for a listing, logs every run, and adds `commands` (the agent
+// pages, generated) and `calls` (the log, read back). The bar: the bare
+// listing answers in well under a second.
+import { type BaseContext, Builtins, Cli } from 'clipanion'
+import { callsFile, logCall } from './calls.ts'
+import { type Family, familiesFor, listing, listingOf, rootClashes } from './families.ts'
+import type { AskTool, CommandClass, KitContext } from './verb.ts'
+
+export type ProjectCliSpec = {
+    /** the binary name: the listing, the examples, the log file and its env prefix use it */
+    name: string
+    /** the repo root: rows run from it, the call log lives under it */
+    root: string
+    families: Family[]
+    /** one line above the bare listing */
+    label?: string
+    version?: string
+    /** the warm path of `{ tool }` rows */
+    askTool?: AskTool
+}
+
+/** the kit's own families, after the project's */
+function kitFamilies(bin: string): Family[] {
+    const builtins = async () => (await import('./builtins.ts')).builtinCommands(bin)
+    return [
+        { roots: ['commands'], load: async () => ({ commands: (await builtins()).docs }), all: true },
+        { roots: ['calls'], load: async () => ({ commands: (await builtins()).calls }) },
+    ]
+}
+
+/** what the kit adds to clipanion's context */
+export type KitExtra = Omit<KitContext, keyof BaseContext>
+
+/** the cli with the families `argv` needs, and the context its commands run in */
+export async function projectCli(spec: ProjectCliSpec, argv: readonly string[], cwd = process.cwd()): Promise<{ cli: Cli<KitContext>; context: KitExtra }> {
+    const families = [...spec.families, ...kitFamilies(spec.name)]
+    const clash = rootClashes(families)
+    if (clash.length > 0) throw new Error(`${spec.name}: two families claim the first word ${clash.map((w) => `'${w}'`).join(', ')}, give each word one family`)
+    const cli = new Cli<KitContext>({ binaryLabel: spec.label ?? spec.name, binaryName: spec.name, binaryVersion: spec.version, enableCapture: true, enableColors: process.stdout.isTTY === true && (process.env.NO_COLOR ?? '') === '' })
+    cli.register(Builtins.HelpCommand)
+    if (spec.version != null) cli.register(Builtins.VersionCommand)
+    const need = familiesFor(argv, families)
+    const classes: CommandClass[] = []
+    for (const mod of await Promise.all(need.map((f) => f.load()))) for (const c of mod.commands) { cli.register(c); classes.push(c) }
+    return { cli, context: { root: spec.root, cwd, classes, askTool: spec.askTool } }
+}
+
+/** the path of the command a call runs, null when none matches */
+function commandOf(cli: Cli<KitContext>, argv: string[], context: KitExtra): string | null {
+    try {
+        const path = (cli.process(argv, context).constructor as { paths?: string[][] }).paths?.[0]?.join(' ') ?? null
+        return path?.startsWith('-') === true ? 'help' : path
+    } catch {
+        return null
+    }
+}
+
+const closedPipe = (e: unknown): boolean => e instanceof Error && 'code' in e && e.code === 'EPIPE'
+
+/** the whole entry of a project CLI: log, load, then list or run */
+export async function runProjectCli(spec: ProjectCliSpec, argv: string[] = process.argv.slice(2)): Promise<void> {
+    // a reader that closes early (`<cli> | head`) ends the run quietly
+    process.stdout.on('error', (e) => (closedPipe(e) ? process.exit(0) : undefined))
+    const call = logCall(callsFile(spec.root, spec.name), spec.name, argv)
+    const t0 = performance.now()
+    const { cli, context } = await projectCli(spec, argv)
+    call.matched(commandOf(cli, argv, context), performance.now() - t0)
+    const word = listingOf(spec.name, argv, cli.definitions())
+    if (word !== null) { process.stdout.write(listing(spec.name, cli.definitions(), word, spec.label)); return }
+    await cli.runExit(argv, context)
+}

package/src/cli/kit/verb.ts

@@ -0,0 +1,167 @@
+// a project CLI command over code that already exists is a ROW, never a second
+// implementation: `verbs([...])` turns rows into clipanion commands that spawn
+// the script, ask the warm tool, or run the command line, from the repo root.
+// A family file imports this module and nothing heavy at its top: the bare
+// listing loads every family.
+import { type BaseContext, Command, type CommandClass as ClipanionClass, Option } from 'clipanion'
+import { existsSync } from 'fs'
+import { isAbsolute, resolve } from 'path'
+
+/** what a kit command sees in `this.context`, beside clipanion's streams */
+export type KitContext = BaseContext & {
+    /** the repo root: every row runs from it */
+    root: string
+    /** where the caller stood: a filmable row's `--out` resolves against it */
+    cwd: string
+    /** every command class registered in this process (the docs read their marks) */
+    classes: CommandClass[]
+    /** the warm path of a `{ tool }` row, when the project has a warm host */
+    askTool?: AskTool
+}
+
+export type CommandClass = ClipanionClass<KitContext>
+
+/** asks a warm process for a tool's answer; null = no warm host, run the cold script */
+export type AskTool = (tool: string, args: string[]) => Promise<number | null>
+
+/** how a row runs */
+export type Run =
+    /** `bun <script> ...pre ...args` */
+    | { bun: string; pre?: string[] }
+    /** the warm host's answer when it runs (`askTool`), else `bun <cold> ...pre ...args` */
+    | { tool: string; cold: string; pre?: string[] }
+    /** any command line, the args appended */
+    | { cmd: string[] }
+
+/** a row that shoots a state: `still` writes one image at `--out`, `clip` a video, its length `--seconds` */
+export type Film = 'still' | 'clip'
+
+/** an everyday command, listed on the essentials page every session loads */
+export type Essential = {
+    /** its arguments as an agent types them: '<x> <y>' */
+    args?: string
+    /** how many of its examples the page shows under its line */
+    examples?: number
+}
+
+export type Verb = {
+    /** the words after the binary: 'world at' */
+    path: string
+    /** the group the listing prints it under */
+    category: string
+    /** one line, under 100 characters */
+    description: string
+    /** the longer text `--help` prints */
+    details?: string
+    /** [label, command line], each line starting with the binary and the row's words */
+    examples: [string, string][]
+    run: Run
+    /** 'own': `--help` also runs the tool with `--help`, which prints its flags and exits 0 */
+    help?: 'own'
+    essential?: Essential
+    /** filmable: takes `--out <path>`, a clip also `--seconds <n>` (a trailer `film` line calls it) */
+    film?: Film
+    /** with film: the row's take version, a bump films every trailer take of the row again */
+    version?: number | string
+    /** with film: `own`, a clip that films as long as it plays (no `--seconds`) */
+    length?: 'own'
+}
+
+/** the argv a row runs */
+export function argvOf(run: Run, args: readonly string[]): string[] {
+    if ('bun' in run) return ['bun', run.bun, ...(run.pre ?? []), ...args]
+    if ('tool' in run) return ['bun', run.cold, ...(run.pre ?? []), ...args]
+    return [...run.cmd, ...args]
+}
+
+/** what a row runs, as the commands page prints it */
+export function runText(run: Run): string {
+    if ('bun' in run) return [run.bun, ...(run.pre ?? [])].join(' ')
+    if ('tool' in run) return `tool ${run.tool} (cold: ${[run.cold, ...(run.pre ?? [])].join(' ')})`
+    return run.cmd.join(' ')
+}
+
+/** the value after `flag` in args (`--out x` or `--out=x`), with its index */
+function flagAt(args: readonly string[], flag: string): { i: number; value: string; joined: boolean } | null {
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i]!
+        if (a === flag && i + 1 < args.length) return { i, value: args[i + 1]!, joined: false }
+        if (a.startsWith(`${flag}=`)) return { i, value: a.slice(flag.length + 1), joined: true }
+    }
+    return null
+}
+
+/** the film contract on one call: a usage error, or the args with `--out`
+ *  made absolute against the caller's cwd and the file the run must leave */
+export function filmCall(film: Film | undefined, args: readonly string[], cwd: string): { error: string } | { args: string[]; out: string | null } {
+    if (film == null) return { args: [...args], out: null }
+    if (film === 'still' && flagAt(args, '--seconds') != null) return { error: '--seconds films a clip, and this row films a still' }
+    const out = flagAt(args, '--out')
+    if (out == null) return { args: [...args], out: null }
+    const abs = isAbsolute(out.value) ? out.value : resolve(cwd, out.value)
+    const next = [...args]
+    if (out.joined) next[out.i] = `--out=${abs}`
+    else next[out.i + 1] = abs
+    return { args: next, out: abs }
+}
+
+const isHelp = (a: string): boolean => a === '--help' || a === '-h'
+
+/** runs an argv from `cwd` with the terminal handed over; its exit code */
+export async function spawnHere(argv: string[], cwd: string): Promise<number> {
+    const p = Bun.spawn(argv, { cwd, env: process.env, stdin: 'inherit', stdout: 'inherit', stderr: 'inherit' })
+    return await p.exited
+}
+
+/** the row each class was made from, so the docs print what it runs */
+export const ROW_OF = new WeakMap<object, Verb>()
+
+/** one clipanion command per row: the args after the path go to the code as typed */
+export function verbs(rows: Verb[]): CommandClass[] {
+    return rows.map((v) => {
+        class VerbCommand extends Command<KitContext> {
+            static override paths = [v.path.split(' ')]
+            static override usage = Command.Usage({ category: v.category, description: v.description, details: v.details, examples: v.examples })
+            static essential = v.essential
+            static film = v.film
+            static filmVersion = v.version
+            static filmLength = v.length
+            args = Option.Proxy()
+            async execute(): Promise<number> {
+                const { root, cwd } = this.context
+                if (this.args.some(isHelp)) {
+                    this.context.stdout.write(this.cli.usage(VerbCommand, { detailed: true }))
+                    if (v.help !== 'own') return 0
+                    this.context.stdout.write(`\nthe tool's own help:\n\n`)
+                    return spawnHere(argvOf(v.run, this.args), root)
+                }
+                const call = filmCall(v.film, this.args, cwd)
+                if ('error' in call) { this.context.stderr.write(`FAIL: ${v.path}: ${call.error}\n`); return 2 }
+                let code: number | null = null
+                if ('tool' in v.run && this.context.askTool != null) code = await this.context.askTool(v.run.tool, [...(v.run.pre ?? []), ...call.args])
+                code ??= await spawnHere(argvOf(v.run, call.args), root)
+                if (code === 0 && call.out != null && !existsSync(call.out)) {
+                    this.context.stderr.write(`FAIL: ${v.path} exited 0 and wrote no ${call.out}\n      fix: a filmable row writes its --out path\n`)
+                    return 1
+                }
+                return code
+            }
+        }
+        ROW_OF.set(VerbCommand, v)
+        return VerbCommand
+    })
+}
+
+/** the marks a command class carries: set by `verbs()` from its row, or
+ *  declared as statics on a hand written class */
+export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } {
+    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown }
+    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own' } = {}
+    if (typeof o.essential === 'object' && o.essential !== null) out.essential = o.essential as Essential
+    if (o.film === 'still' || o.film === 'clip') {
+        out.film = o.film
+        if (typeof o.filmVersion === 'number' || typeof o.filmVersion === 'string') out.version = o.filmVersion
+        if (o.filmLength === 'own') out.length = 'own'
+    }
+    return out
+}

package/src/cli.ts

@@ -7,6 +7,8 @@ import { Builtins, Cli } from 'clipanion'
 import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cli/cmd_Asks.ts'
 import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cli/cmd_Assets.ts'
 import { BumpCommand } from './cli/cmd_Bump.ts'
+import { CallsCommand } from './cli/cmd_Calls.ts'
+import { TimeCommand } from './cli/cmd_Time.ts'
 import { CheckCommand } from './cli/cmd_Check.ts'
 import { CommandsCommand } from './cli/cmd_Commands.ts'
 import { aliasArgs, CrossRepoActivityCommand } from './cli/cmd_CrossRepoActivity.ts'
@@ -35,8 +37,11 @@ import { CacheAuditCommand } from './cli/cmd_CacheAudit.ts'
 import { TraceAuditCommand } from './cli/cmd_TraceAudit.ts'
 import { ServeCommand } from './cli/cmd_Serve.ts'
 import { SmokeCommand } from './cli/cmd_Smoke.ts'
+import { ShotCommand } from './cli/cmd_Shot.ts'
 import { StatusCommand } from './cli/cmd_Status.ts'
 import { StartCommand } from './cli/cmd_Start.ts'
+import { TRAILER_COMMANDS } from './cli/cmd_Trailer.ts'
+import { REVIEW_COMMANDS } from './cli/cmd_Review.ts'
 import { TuiCommand } from './cli/cmd_Tui.ts'
 import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
 
@@ -67,6 +72,8 @@ export function buildCli(): Cli {
     cli.register(MvCommand)
     cli.register(CheckCommand)
     cli.register(TuiCommand)
+    for (const c of TRAILER_COMMANDS) cli.register(c)
+    for (const c of REVIEW_COMMANDS) cli.register(c)
     cli.register(ServeCommand)
     cli.register(PmCommand)
     cli.register(DaemonCommand)
@@ -91,6 +98,7 @@ export function buildCli(): Cli {
     cli.register(FleetCommand)
     cli.register(PbCollectionCommand)
     cli.register(SmokeCommand)
+    cli.register(ShotCommand)
     cli.register(ReflectCommand)
     cli.register(KeysCommand)
     cli.register(GlobalProcessesCommand)
@@ -109,6 +117,8 @@ export function buildCli(): Cli {
     cli.register(TraceAuditCommand)
     cli.register(UnitsAliasCommand)
     cli.register(CommandsCommand)
+    cli.register(CallsCommand)
+    cli.register(TimeCommand)
     cli.register(ConfigKeysCommand)
 
     return cli
@@ -117,14 +127,17 @@ export function buildCli(): Cli {
 // only when this file IS the process, so importing it costs nothing. A repo's
 // installed copy first hands the command to the house source (handoff.ts). One copy
 // of the lib per process: a repo config that imports its own install lands on
-// this one (one-lib.ts), so the machine's version runs in every repo. Then pm
-// is started when it is down (autostart.ts), before the command runs
+// this one (one-lib.ts), so the machine's version runs in every repo. The run
+// is logged (cli/kit/calls.ts, read back by `sk calls`). Then pm is started
+// when it is down (autostart.ts), before the command runs
 if (import.meta.main) {
     const argv = aliasArgs(process.argv.slice(2))
     const { handoff } = await import('./home/handoff.ts')
     handoff(argv)
     const { installOneLib } = await import('./core/one-lib.ts')
     installOneLib()
+    const { callsFile, logCall } = await import('./cli/kit/calls.ts')
+    logCall(callsFile((await import('os')).homedir(), 'sk'), 'sk', argv)
     const { autostart } = await import('./home/autostart.ts')
     await autostart(argv)
     void buildCli().runExit(argv)

package/src/collections/collection-types.ts

@@ -31,7 +31,12 @@ export const NO_CHECK = 'in no check'
  *  section a row lives under (hub-app/tree-build.ts KIND_SECTION). There is no
  *  catch all kind: a row belongs to an owner, and what belongs to the hub
  *  itself is its status (serve/hub-problems.ts), never a row */
-export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process'] as const
+export const RESOURCE_TYPES = ['ask', 'secret', 'asset', 'post', 'workflow', 'wiki', 'contract', 'check', 'test', 'reflection', 'process', 'card', 'cut'] as const
+
+/** the collection of the review cards that wait on him (collections/review.ts) */
+export const REVIEW_COL = 'review'
+/** the collection of the trailer cuts, one row a cut (collections/review.ts) */
+export const TRAILER_COL = 'trailers'
 
 export type ResourceType = (typeof RESOURCE_TYPES)[number]
 

package/src/collections/providers.ts

@@ -27,6 +27,7 @@ import { mdBody } from './md-body.ts'
 import { socialPostsCollection } from './posts.ts'
 import { assetState, secretState, type SecretLevel, type SecretProbe } from './state-rules.ts'
 import { reflectionsCollection } from './reflections.ts'
+import { reviewCollection, trailersCollection } from './review.ts'
 import { testsCollection } from './tests.ts'
 import { checksCollection } from './checks.ts'
 import { LAYOUT } from '../core/layout.ts'
@@ -417,5 +418,7 @@ export function buildCollections(root: string, c: RepoConfig, kit: ResolvedKit |
         socialPostsCollection(root),
         reflectionsCollection(root),
         testsCollection(root, c),
+        // only where the repo has a review store or a trailer folder: the section of a repo with none is greyed
+        ...[reviewCollection(root), trailersCollection(root)].filter((x): x is Collection => x !== null),
     ]
 }