rvlib-shipkit 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 2.6.0
+
+- **A trailer's score sounds as the game's browser synth, section for section.** A note that starts inside a 128 frame block takes the phase the browser gives it (it runs at the default 440 Hz until its own frame of that block), so overlapping notes of one pitch, a timpani roll, add or cancel as in the browser; `osc: 'square'` is the browser's own square wave, no longer a sine; the master's compressor and limiter are the browser's kernel (32 frame divisions, adaptive release, the sine warp on the gain). pkm-multi's main4 score: 38 of 38 sections within 0.1 dB of the game's render (were 18), each octave band within 0.15 dB. Every score renders again once.
+
+## 2.5.0
+
+- **A review card hands itself to any agent session.** A small copy icon on the card's header (or C) copies one block: its title and state, its repo, `cd <repo> && sk review show <id>`, its link here and on the phone when the repo has a public host; a toast says what was copied. `sk review show <id> --paste` prints the same block.
+- **The overall comment box sits under the card's header**, after the verdicts, on every card and in every layout.
+- **Push every unpushed repo: `sk fleet push` and a button on the activity page.** Each house repo with commits its remote lacks gets a plain `git push`, never a force; a branch with no upstream goes `-u` to its one remote; a branch that is also behind, a gone upstream or a detached head is skipped with the reason. `--dry` plans only.
+
+- **A new repo's agent/index.md routes with `→`.** The scaffold's table rows, the project CLI's row and its `next:` hint write `→ agent/<page>.md`, the wiki's form for a page to open, instead of a backticked path.
+
 ## 2.3.0
 
 - **A sound is a review view.** `sk review add --audio <sound>`, a sound in `--view`, `add-view <id> "<label>" --audio <sound>`, or a before and after of two sounds: the store keeps the sound and draws its waveform (`wave.png`, `before-wave.png`), and the hub shows each waveform over a player, one row a side. A sound takes reactions and words, never a rectangle; a pair is never a sound and an image.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "2.4.0",
+    "version": "2.6.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
@@ -36,7 +36,7 @@
     },
     "dependencies": {
         "@floating-ui/react": "^0.27.20",
-        "@napi-rs/canvas": "^1.0.2",
+        "@napi-rs/canvas": "^1.1.0",
         "clipanion": "^4.0.0-rc.4",
         "comfy-ts": "^2.9.0",
         "ink": "^7.1.1",

package/src/cli/cmd_Commands.ts

@@ -5,6 +5,7 @@
 // (the kit in cli/kit/) come out of these functions.
 import { Command, Option } from 'clipanion'
 import { spliceMarkedBlock } from '../core/doc-block.ts'
+import { FAMILY_PAGES } from './family-pages.ts'
 import { type Essential, type Film, marksOf, ROW_OF, runText } from './kit/verb.ts'
 
 export type CommandOption = { definition: string; description: string }
@@ -117,12 +118,13 @@ export function renderMarkdown(rows: CommandRow[], bin = 'sk'): string {
 
 /** the eager form: one line per command, its positional arguments and its
  *  description. Flags and examples are `<bin> <command> --help`, so a page every
- *  session loads costs a line per command, not a screen */
-export function renderCompact(rows: CommandRow[], bin = 'sk'): string {
+ *  session loads costs a line per command, not a screen. `pages` puts each
+ *  family's owner page in its heading: `### Trailer → build/trailer.md` */
+export function renderCompact(rows: CommandRow[], bin = 'sk', pages: Readonly<Record<string, string>> | null = null): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
-        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
+        if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}${pages?.[cat] != null ? ` → ${pages[cat]}` : ''}\n`) }
         const sig = r.usage.replace(/^\$0/, bin).replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `${bin} ${r.path}`
         out.push(`- \`${sig}\` — ${r.description}`)
     }
@@ -154,6 +156,15 @@ export function renderEssentials(rows: CommandRow[], bin: string, command: strin
     return `${out.join('\n')}\n`
 }
 
+/** a family with no owner page, and a page for a family no command has: one line each */
+export function familyProblems(rows: CommandRow[], pages: Readonly<Record<string, string>>): string[] {
+    const families = new Set(rows.map((r) => r.category))
+    return [
+        ...[...families].filter((f) => pages[f] == null).map((f) => `family ${f}: no owner page in src/cli/family-pages.ts`),
+        ...Object.keys(pages).filter((f) => !families.has(f)).map((f) => `family ${f}: src/cli/family-pages.ts names a page for a family no command has`),
+    ]
+}
+
 /** what a project CLI's registry must hold for its pages and its listing to
  *  teach right: a category, a description under the cap, and an example that
  *  starts with the command's own words. One line per breach */
@@ -209,6 +220,9 @@ export class CommandsCommand extends Command {
      *  a breach), and its --out creates a missing page */
     static shapeRule = false
 
+    /** each family's owner page, named in the compact page's headings; a project CLI has none */
+    static familyPages: Readonly<Record<string, string>> | null = FAMILY_PAGES
+
     json = Option.Boolean('--json', false, { description: 'machine-readable rows, with film and essential where a command carries them' })
     out = Option.String('--out', { description: 'host file carrying the <bin>:commands markers. The block between them is rewritten' })
     check = Option.Boolean('--check', false, { description: 'with --out or --essentials: exit 1 if a page is stale, write nothing' })
@@ -225,10 +239,17 @@ export class CommandsCommand extends Command {
             classes,
         )
         const write = (s: string): void => void this.context.stdout.write(s)
+        const pages = (this.constructor as typeof CommandsCommand).familyPages
+        const render = (): string => (this.compact ? renderCompact(rows, bin, pages) : renderMarkdown(rows, bin))
         if (this.out == null && this.essentials == null) {
-            write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows, bin)}\n`)
+            write(this.json ? `${JSON.stringify(rows)}\n` : `${render()}\n`)
             return 0
         }
+        if (this.out != null && this.compact && pages != null) {
+            const bad = familyProblems(rows, pages)
+            for (const b of bad) write(`FAIL: ${b}\n`)
+            if (bad.length > 0) { write('      fix: one row per family in src/cli/family-pages.ts, the wiki page that owns it\n'); return 1 }
+        }
         if ((this.constructor as typeof CommandsCommand).shapeRule) {
             const bad = shapeProblems(rows, bin)
             for (const b of bad) write(`FAIL: ${b}\n`)
@@ -250,7 +271,7 @@ export class CommandsCommand extends Command {
         const project = (this.constructor as typeof CommandsCommand).shapeRule
         if (!existsSync(this.out) && (!project || this.check)) { write(`FAIL: ${this.out} does not exist\n`); return 1 }
         const host = existsSync(this.out) ? readFileSync(this.out, 'utf8') : newCommandsPage(bin, this.out)
-        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows, bin), bin)
+        const next = spliceBlock(host, render(), bin)
         if (next == null) { write(`FAIL: ${this.out} has no ${begin} / ${end} markers\n`); return 1 }
         if (next === host) { write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return code }
         if (this.check) {

package/src/cli/cmd_FleetPush.ts

@@ -0,0 +1,47 @@
+// shipkit fleet push — every house repo that holds commits its remote does
+// not, pushed: a plain git push, never a force (fleet/push-fleet.ts, the same
+// path as the activity page's push button). A repo that fell behind waits for
+// a pull, and says so.
+import { Command, Option } from 'clipanion'
+import { homedir } from 'os'
+import { gitRoot } from '../core/git-root.ts'
+import { pushFleet } from '../fleet/push-fleet.ts'
+import { houseRepos } from '../serve/project-gutter.ts'
+import { listFlag } from './list-flag.ts'
+
+export class FleetPushCommand extends Command {
+    static override paths = [['fleet', 'push']]
+
+    static override usage = Command.Usage({
+        category: 'Health',
+        description: 'push every house repo with unpushed commits: a plain git push, never a force',
+        examples: [
+            ['push what is unpushed, everywhere', 'sk fleet push'],
+            ['what would go out', 'sk fleet push --dry'],
+            ['some repos only', 'sk fleet push --only my-app --only other'],
+        ],
+    })
+
+    dry = Option.Boolean('--dry', false, { description: 'plan only: say what would be pushed and what is skipped, push nothing' })
+    only = Option.Array('--only', { description: 'limit to these repo names (repeatable)' })
+    all = Option.Boolean('--all', false, { description: 'also print the repos that have nothing to push' })
+
+    async execute(): Promise<number> {
+        const root = gitRoot(process.cwd())?.top ?? process.cwd()
+        let repos = houseRepos(root, homedir()).repos.map((r) => ({ name: r.name, path: r.path }))
+        const only = listFlag(this.only)
+        if (only.length > 0) repos = repos.filter((r) => only.includes(r.name))
+        const w = (l: string) => this.context.stdout.write(`${l}\n`)
+        if (repos.length === 0) {
+            w(`skip: no house repo found from ${root}`)
+            return 0
+        }
+        const res = await pushFleet(repos, { dry: this.dry })
+        for (const r of res) if (this.all || r.action !== 'none') w(r.line)
+        const pushed = res.filter((r) => r.ok && (r.action === 'push' || r.action === 'push-upstream')).length
+        const failed = res.filter((r) => !r.ok && r.action !== 'skip').length
+        const skipped = res.filter((r) => r.action === 'skip').length
+        w(`${failed > 0 ? 'FAIL' : 'ok'}: ${repos.length} repos, ${this.dry ? `${res.filter((r) => r.action === 'push' || r.action === 'push-upstream').length} would push` : `${pushed} pushed`}, ${skipped} skipped${failed > 0 ? `, ${failed} failed` : ''}`)
+        return failed > 0 ? 1 : 0
+    }
+}

package/src/cli/cmd_GlobalProcesses.ts

@@ -28,7 +28,7 @@ export type GlobalProcessesAnswer = {
 export type GlobalProcessesDeps = {
     pm: () => Promise<PmAnswer | null>
     /** the daemon's identity, for its version; null when it does not answer */
-    daemon?: () => Promise<{ version: string } | null>
+    daemon?: () => Promise<{ version: string; held?: string | null } | null>
     /** the declared units, read like pm reads them; null when no house is found */
     declared: () => Promise<Pick<PmConfig, 'processes' | 'errors'> | null>
     /** the project list's order */
@@ -43,18 +43,18 @@ const localPorts = () => ({ pm: pmPort(), daemon: daemonPort(), web: homePort()
  *  pm does not answer */
 export async function globalProcessesAnswer(d: GlobalProcessesDeps): Promise<GlobalProcessesAnswer> {
     const [pm, daemon] = await Promise.all([d.pm(), d.daemon?.() ?? null])
-    const core = { daemonVersion: daemon?.version ?? null, ports: localPorts() }
+    const core = { daemonVersion: daemon?.version ?? null, daemonHeld: daemon?.held ?? null, ports: localPorts() }
     if (pm != null) return { pm: { pid: pm.pid, version: pm.version }, now: d.now, groups: processGroups(pm, d.order, core), errors: pm.unitErrors, house: true }
     const c = await d.declared()
     return { pm: null, now: d.now, groups: [coreGroup(null, core), ...groupRows((c?.processes ?? []).map(declaredRow), d.order)], errors: c?.errors ?? [], house: c != null }
 }
 
 /** the daemon's identity at /hub.json, or null */
-export async function askDaemon(url = daemonUrl()): Promise<{ version: string } | null> {
+export async function askDaemon(url = daemonUrl()): Promise<{ version: string; held: string | null } | null> {
     try {
         const r = await fetch(`${url}/hub.json`, { signal: AbortSignal.timeout(3_000) })
-        const j = r.ok ? ((await r.json()) as { hub?: string; version?: string }) : null
-        return j?.hub === 'shipkit-home' && typeof j.version === 'string' ? { version: j.version } : null
+        const j = r.ok ? ((await r.json()) as { hub?: string; version?: string; held?: string | null }) : null
+        return j?.hub === 'shipkit-home' && typeof j.version === 'string' ? { version: j.version, held: j.held ?? null } : null
     } catch {
         return null
     }

package/src/cli/cmd_Review.ts

@@ -345,8 +345,14 @@ export class ReviewLsCommand extends Command {
 
 export class ReviewShowCommand extends Command {
     static override paths = [['review', 'show']]
-    static override usage = Command.Usage({ category: 'Review', description: 'one item and its thread: the verdict, rectangles, reactions, the whole conversation', details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3).` })
+    static override usage = Command.Usage({
+        category: 'Review',
+        description: 'one item and its thread: the verdict, rectangles, reactions, the whole conversation',
+        details: `${DETAILS}\n\nTakes an item id or a player report's ref (live#3). --paste prints the short block that hands the card to another agent session (the hub's copy button gives the same).`,
+        examples: [['hand a card to another session', 'sk review show <id> --paste']],
+    })
     id = Option.String()
+    paste = Option.Boolean('--paste', false, { description: 'the block another agent session acts on: title, repo, this command, the links' })
 
     async execute(): Promise<number> {
         return run(this.context, async (h) => {
@@ -357,6 +363,15 @@ export class ReviewShowCommand extends Command {
             const all = readAllCached(h.dir)
             const x = all.items.find((y) => y.item.id === id)
             if (!x) throw new Error(`no item ${this.id}`)
+            if (this.paste) {
+                const { dirname } = await import('node:path')
+                const { pasteHosts, cardUrl } = await import('../review/paste.ts')
+                const { pasteBlock, STATUS_LABEL } = await import('../review/model.ts')
+                const { statusOf } = await import('../review/threads.ts')
+                const w = await pasteHosts(dirname(dirname(h.dir)))
+                h.out(pasteBlock(x.item, STATUS_LABEL[statusOf(x, all.items)], { root: w.root, open: cardUrl(w.open, x.item.id), phone: w.phone ? cardUrl(w.phone, x.item.id) : null }))
+                return 0
+            }
             const t = threadOfItem(x.item.id, threadsOf(all.items))
             h.out(t && (t.head.item.id === x.item.id || t.answers.length > 0) ? threadDetail(t, h.dir, true, h.say) : detail(x, h.dir, true, false, h.say))
             return 0

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
     }
 }

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/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
+}

package/src/cli.ts

@@ -1,146 +1,58 @@
 #!/usr/bin/env bun
-// shipkit — clipanion entry: one command FAMILY per file in cli/ (cmd_<Name>.ts),
-// logic in plain modules the commands call. runExit sets the exit code
-// without force-exiting, so serve commands keep the process alive.
-import { LIB_VERSION } from './core/lib-version.ts'
-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'
-import { ConfigKeysCommand } from './cli/cmd_ConfigKeys.ts'
-import { GlobalProcessesCommand, GlobalProcessOpenCommand, GlobalProcessRestartCommand, GlobalProcessStartCommand, GlobalProcessStopCommand } from './cli/cmd_GlobalProcesses.ts'
-import { PlannedCommand } from './cli/cmd_Planned.ts'
-import { InsightsCommand } from './cli/cmd_Insights.ts'
-import { GlobalContextCommand } from './cli/cmd_GlobalContext.ts'
-import { OverviewCommand } from './cli/cmd_Overview.ts'
-import { CiCommand } from './cli/cmd_Ci.ts'
-import { ContractsCommand } from './cli/cmd_Contracts.ts'
-import { FleetCommand } from './cli/cmd_Fleet.ts'
-import { DaemonCommand, GuiCommand, PmCommand, PmInstallCommand, PmUninstallCommand, WebCommand } from './cli/cmd_Home.ts'
-import { HooksCommitMsgCommand, HooksInstallCommand, HooksListCommand, HooksPreCommitCommand } from './cli/cmd_Hooks.ts'
-import { InitCommand } from './cli/cmd_Init.ts'
-import { KeysCommand } from './cli/cmd_Keys.ts'
-import { MvCommand } from './cli/cmd_Mv.ts'
-import { NeedsCommand } from './cli/cmd_Needs.ts'
-import { PbCollectionCommand } from './cli/cmd_Pb.ts'
-import { ReflectCommand } from './cli/cmd_Reflect.ts'
-import { ReleaseCommand } from './cli/cmd_Release.ts'
-import { ReleasesCommand } from './cli/cmd_Releases.ts'
-import { ChecksCommand, UnitsAliasCommand } from './cli/cmd_Checks.ts'
-import { WhenCommand } from './cli/cmd_When.ts'
-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 { SOUND_COMMANDS } from './cli/cmd_Sound.ts'
-import { REVIEW_COMMANDS } from './cli/cmd_Review.ts'
-import { TuiCommand } from './cli/cmd_Tui.ts'
-import { WikiLintCommand, WikiServeCommand } from './cli/cmd_Wiki.ts'
+// the way in: the launcher, a repo's install handing off, the commit hooks
+// and pm's roles all run this file. It loads the registry (cli/registry.ts)
+// and the boot steps with await import, so a file of the tree that fails to
+// load is caught here and the last good copy runs instead, with one line
+// (core/last-good.ts). An error once the command runs is the command's own.
+//
+// the one constraint a reader breaks first: no static import but
+// core/last-good.ts, else a broken file stops this file before it can fall
+// back (tests/cli-boot.test.ts).
+import { bootLoaded, runLastGood } from './core/last-good.ts'
 
+/** a long running role's runner, which its command loads by await import:
+ *  loaded here, a role pm starts on a broken tree runs the copy too */
+const loadRole = (cmd: string | undefined): Promise<unknown> | null =>
+    cmd === 'daemon' ? import('./home/run-daemon.ts')
+    : cmd === 'web' ? import('./home/run-web.ts')
+    : cmd === 'pm' ? import('./home/run-pm.ts')
+    : cmd === 'serve' ? import('./serve/run-serve.ts')
+    : null
 
-/** 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 Cli({
-        binaryLabel: 'shipkit — repo toolkit',
-        binaryName: 'sk',
-        binaryVersion: LIB_VERSION,
-        enableCapture: true, // console output pipes into the command streams (testable)
-        enableColors: true,
-    })
+/** every module the boot runs, loaded, with the runner of the role `cmd`
+ *  names. The load probe asks it too (core/load-probe.ts), so a restart is
+ *  tried on exactly this */
+export const loadBoot = (cmd?: string) =>
+    Promise.all([
+        import('./cli/registry.ts'),
+        import('./cli/cmd_CrossRepoActivity.ts'),
+        import('./home/handoff.ts'),
+        import('./core/one-lib.ts'),
+        import('./cli/kit/calls.ts'),
+        import('./home/autostart.ts'),
+        loadRole(cmd),
+    ])
 
-    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(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
-}
-
-// 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. 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
+// only when this file IS the process. 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).
+// 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')
+    const raw = process.argv.slice(2)
+    let m
+    try {
+        m = await loadBoot(raw[0])
+    } catch (e) {
+        runLastGood(e, raw)
+        throw e
+    }
+    bootLoaded()
+    const [{ buildCli }, { aliasArgs }, { handoff }, { installOneLib }, { callsFile, logCall }, { autostart }] = m
+    const argv = aliasArgs(raw)
     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)
 }