rvlib-shipkit 2.3.0 → 2.5.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_Trailer.ts

@@ -1,8 +1,10 @@
 // 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'
+import { pageAt } from './family-pages.ts'
 
-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`
+const PAGE = pageAt('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/. Read first: ${PAGE}, then its folder build/trailer/ (the score, the craft, a book of ideas, extending the language)`
 
 /** --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(',')))
@@ -16,6 +18,7 @@ async function run(context: { stdout: NodeJS.WritableStream; stderr: NodeJS.Writ
         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`)
+        if (e instanceof Refused) context.stderr.write(`      fix: the language is ${PAGE}\n`)
         return 1
     }
 }
@@ -32,17 +35,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 = await 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,14 +69,17 @@ 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 = await 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
             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
         })

package/src/cli/family-pages.ts

@@ -0,0 +1,49 @@
+// the wiki page that owns each sk command family, a path from the root of the wiki the lib lives in. The always
+// loaded command page names it in the family's heading, so `sk commands --out` fails on a family missing here
+import { existsSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+export const FAMILY_PAGES: Readonly<Record<string, string>> = {
+    Asks: 'world/human-loop.md',
+    Assets: 'build/generate-assets.md',
+    Gate: 'build/shipkit.md',
+    Health: 'build/shipkit.md',
+    Home: 'build/shipkit/home.md',
+    Refactor: 'build/typescript.md',
+    Review: 'build/shipkit/review.md',
+    Scaffold: 'build/pocketbase.md',
+    Serve: 'build/shipkit/home.md',
+    Setup: 'meta/rv-conventions.md',
+    Sound: 'build/trailer.md',
+    Trailer: 'build/trailer.md',
+    Wiki: 'build/mdwiki.md',
+}
+
+/** a page as a path any repo can read, when the lib runs from inside its wiki (`<wiki>/build/shipkit/rvlib-shipkit`);
+ *  from an install, the page's wiki path */
+export function pageAt(rel: string): string {
+    const abs = join(import.meta.dir, '../../../../..', rel)
+    if (!existsSync(abs)) return `wiki ${rel}`
+    const home = homedir()
+    return abs.startsWith(`${home}/`) ? `~${abs.slice(home.length)}` : abs
+}
+
+type Listed = { contexts?: { commandClass: { usage?: { category?: string | null } } }[]; commands?: number[]; execute(): Promise<number | void>; context: { stdout: { write(s: string): unknown } } }
+
+/** `sk <family> --help` lists the family's commands (clipanion's help for several matches): the family's page
+ *  follows the list. Any other command passes through */
+export function withFamilyPage<C extends object>(command: C, pages: Readonly<Record<string, string>> = FAMILY_PAGES): C {
+    const h = command as C & Listed
+    if (!Array.isArray(h.contexts) || !Array.isArray(h.commands) || h.commands.length < 2) return command
+    const families = new Set(h.commands.map((i) => h.contexts?.[i]?.commandClass.usage?.category ?? ''))
+    const page = families.size === 1 ? pages[[...families][0]!] : undefined
+    if (page == null) return command
+    const list = h.execute.bind(h)
+    h.execute = async () => {
+        const code = await list()
+        h.context.stdout.write(`Read first: ${pageAt(page)}\n`)
+        return code
+    }
+    return command
+}

package/src/cli/kit/builtins.ts

@@ -21,6 +21,7 @@ export function builtinCommands(bin: string): { docs: CommandClass[]; calls: Com
             ],
         })
         static override shapeRule = true
+        static override familyPages = null
     }
     class ProjectCalls extends CallsCommand {
         static override usage = Command.Usage({

package/src/cli/kit/verb.ts

@@ -65,6 +65,10 @@ export type Verb = {
     version?: number | string
     /** with film: `own`, a clip that films as long as it plays (no `--seconds`) */
     length?: 'own'
+    /** with film: the words it takes and their types (trailer/words.ts), each checked at its line of a .trailer */
+    words?: Record<string, unknown>
+    /** with film: the paths its takes film, their world */
+    stamp?: string[]
 }
 
 /** the argv a row runs */
@@ -126,6 +130,8 @@ export function verbs(rows: Verb[]): CommandClass[] {
             static film = v.film
             static filmVersion = v.version
             static filmLength = v.length
+            static filmWords = v.words
+            static filmStamp = v.stamp
             args = Option.Proxy()
             async execute(): Promise<number> {
                 const { root, cwd } = this.context
@@ -154,14 +160,16 @@ export function verbs(rows: Verb[]): CommandClass[] {
 
 /** 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' } = {}
+export function marksOf(c: object): { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } {
+    const o = c as { essential?: unknown; film?: unknown; filmVersion?: unknown; filmLength?: unknown; filmWords?: unknown; filmStamp?: unknown }
+    const out: { essential?: Essential; film?: Film; version?: number | string; length?: 'own'; words?: Record<string, unknown>; stamp?: string[] } = {}
     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'
+        if (typeof o.filmWords === 'object' && o.filmWords !== null) out.words = o.filmWords as Record<string, unknown>
+        if (Array.isArray(o.filmStamp)) out.stamp = o.filmStamp.map(String)
     }
     return out
 }

package/src/cli/registry.ts

@@ -0,0 +1,137 @@
+// the command registry: one command FAMILY per file in this folder
+// (cmd_<Name>.ts), logic in plain modules the commands call. The boot
+// (../cli.ts) loads it with an await import, so a file that fails to load is
+// caught there. A new command registers here.
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { Builtins, Cli, type Command } from 'clipanion'
+import { AskNewCommand, AsksCheckCommand, AsksCommand } from './cmd_Asks.ts'
+import { AssetsAddCommand, AssetsCheckCommand, AssetsFillCommand, AssetsGenCommand, AssetsIdentityCommand } from './cmd_Assets.ts'
+import { BumpCommand } from './cmd_Bump.ts'
+import { CallsCommand } from './cmd_Calls.ts'
+import { TimeCommand } from './cmd_Time.ts'
+import { CheckCommand } from './cmd_Check.ts'
+import { CommandsCommand } from './cmd_Commands.ts'
+import { withFamilyPage } from './family-pages.ts'
+import { aliasArgs, CrossRepoActivityCommand } from './cmd_CrossRepoActivity.ts'
+import { ConfigKeysCommand } from './cmd_ConfigKeys.ts'
+import { GlobalProcessesCommand, GlobalProcessOpenCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cmd_GlobalProcesses.ts'
+import { PlannedCommand } from './cmd_Planned.ts'
+import { InsightsCommand } from './cmd_Insights.ts'
+import { GlobalContextCommand } from './cmd_GlobalContext.ts'
+import { OverviewCommand } from './cmd_Overview.ts'
+import { CiCommand } from './cmd_Ci.ts'
+import { ContractsCommand } from './cmd_Contracts.ts'
+import { FleetCommand } from './cmd_Fleet.ts'
+import { FleetPushCommand } from './cmd_FleetPush.ts'
+import { DaemonCommand, GuiCommand, PmCommand, PmInstallCommand, PmUninstallCommand, WebCommand } from './cmd_Home.ts'
+import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cmd_Hooks.ts'
+import { InitCommand } from './cmd_Init.ts'
+import { KeysCommand } from './cmd_Keys.ts'
+import { MvCommand } from './cmd_Mv.ts'
+import { NeedsCommand } from './cmd_Needs.ts'
+import { PbCollectionCommand } from './cmd_Pb.ts'
+import { ReflectCommand } from './cmd_Reflect.ts'
+import { ReleaseCommand } from './cmd_Release.ts'
+import { ReleasesCommand } from './cmd_Releases.ts'
+import { ChecksCommand, UnitsAliasCommand } from './cmd_Checks.ts'
+import { WhenCommand } from './cmd_When.ts'
+import { CacheAuditCommand } from './cmd_CacheAudit.ts'
+import { TraceAuditCommand } from './cmd_TraceAudit.ts'
+import { ServeCommand } from './cmd_Serve.ts'
+import { SmokeCommand } from './cmd_Smoke.ts'
+import { ShotCommand } from './cmd_Shot.ts'
+import { StatusCommand } from './cmd_Status.ts'
+import { StartCommand } from './cmd_Start.ts'
+import { TRAILER_COMMANDS } from './cmd_Trailer.ts'
+import { SOUND_COMMANDS } from './cmd_Sound.ts'
+import { REVIEW_COMMANDS } from './cmd_Review.ts'
+import { TuiCommand } from './cmd_Tui.ts'
+import { WikiLintCommand, WikiServeCommand } from './cmd_Wiki.ts'
+
+
+/** `sk <family> --help` names the family's page under its list */
+class FamilyHelpCli extends Cli {
+    override process(...args: unknown[]): Command {
+        return withFamilyPage((super.process as (...a: unknown[]) => Command).apply(this, args))
+    }
+}
+
+/** the registry, built but NOT run: a test drives the real binary in process
+ *  instead of paying a cold bun start per assertion (~250ms each), and the
+ *  wiring it exercises is the wiring that ships. */
+export function buildCli(): Cli {
+    const cli = new FamilyHelpCli({
+        binaryLabel: 'shipkit — repo toolkit',
+        binaryName: 'sk',
+        binaryVersion: LIB_VERSION,
+        enableCapture: true, // console output pipes into the command streams (testable)
+        enableColors: true,
+    })
+
+    cli.register(Builtins.HelpCommand)
+    cli.register(Builtins.VersionCommand)
+    cli.register(CiCommand)
+    cli.register(StatusCommand)
+    cli.register(BumpCommand)
+    cli.register(ReleaseCommand)
+    cli.register(ReleasesCommand)
+    cli.register(HooksInstallCommand)
+    cli.register(HooksPreCommitCommand)
+    cli.register(HooksCommitMsgCommand)
+    cli.register(HooksListCommand)
+    cli.register(MvCommand)
+    cli.register(CheckCommand)
+    cli.register(TuiCommand)
+    for (const c of TRAILER_COMMANDS) cli.register(c)
+    for (const c of SOUND_COMMANDS) cli.register(c)
+    for (const c of REVIEW_COMMANDS) cli.register(c)
+    cli.register(ServeCommand)
+    cli.register(PmCommand)
+    cli.register(DaemonCommand)
+    cli.register(WebCommand)
+    cli.register(PmInstallCommand)
+    cli.register(PmUninstallCommand)
+    cli.register(GuiCommand)
+    cli.register(ContractsCommand)
+    cli.register(AsksCommand)
+    cli.register(AsksCheckCommand)
+    cli.register(AskNewCommand)
+    cli.register(WikiServeCommand)
+    cli.register(WikiLintCommand)
+    cli.register(AssetsFillCommand)
+    cli.register(AssetsAddCommand)
+    cli.register(AssetsGenCommand)
+    cli.register(AssetsIdentityCommand)
+    cli.register(AssetsCheckCommand)
+    cli.register(InitCommand)
+    cli.register(StartCommand)
+    cli.register(NeedsCommand)
+    cli.register(FleetCommand)
+    cli.register(FleetPushCommand)
+    cli.register(PbCollectionCommand)
+    cli.register(SmokeCommand)
+    cli.register(ShotCommand)
+    cli.register(ReflectCommand)
+    cli.register(KeysCommand)
+    cli.register(GlobalProcessesCommand)
+    cli.register(GlobalProcessStartCommand)
+    cli.register(GlobalProcessStopCommand)
+    cli.register(GlobalProcessRestartCommand)
+    cli.register(GlobalProcessOpenCommand)
+    cli.register(CrossRepoActivityCommand)
+    cli.register(PlannedCommand)
+    cli.register(InsightsCommand)
+    cli.register(GlobalContextCommand)
+    cli.register(OverviewCommand)
+    cli.register(ChecksCommand)
+    cli.register(WhenCommand)
+    cli.register(CacheAuditCommand)
+    cli.register(TraceAuditCommand)
+    cli.register(UnitsAliasCommand)
+    cli.register(CommandsCommand)
+    cli.register(CallsCommand)
+    cli.register(TimeCommand)
+    cli.register(ConfigKeysCommand)
+
+    return cli
+}