rvlib-shipkit 2.3.0 → 2.5.0

package/src/cli.ts

@@ -1,144 +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 { 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 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)
 }

package/src/core/app-icon.ts

@@ -10,8 +10,9 @@ import { identityOfName, identityOfText, type Identity } from './identity-color.
 import { configName, CONFIG_FILE } from './identity.ts'
 import { LAYOUT } from './layout.ts'
 
-/** the mark an app wears: the repo's own, largest first. Rasters only */
-export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, 'public/logo.png', 'public/favicon.png']
+/** the mark an app wears: the repo's own, largest first; an svg mark is drawn
+ *  as an image too (the canvas decodes it) */
+export const APP_ICON_FILES = [`${LAYOUT.identity}/icon.png`, `${LAYOUT.identity}/icon.svg`, 'public/logo.png', 'public/favicon.png']
 
 export function appIconOf(root: string): string | null {
     for (const f of APP_ICON_FILES) if (existsSync(join(root, f))) return join(root, f)
@@ -133,15 +134,18 @@ export async function drawAppIcon(bytes: Uint8Array, id: Identity): Promise<{ ca
     return { canvas: out, plate: colour }
 }
 
-/** the icon as pngs, one per size asked, drawn once */
-export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX]): Promise<Buffer[]> {
+/** the icon as pngs, one per size asked, drawn once. `plate` crops the macOS
+ *  grid's margin away, the rounded plate edge to edge (the hub's rail) */
+export async function appIconPngs(bytes: Uint8Array, id: Identity, sizes: number[] = [ICON_PX], crop: 'canvas' | 'plate' = 'canvas'): Promise<Buffer[]> {
     const { canvas } = await drawAppIcon(bytes, id)
+    const o = crop === 'plate' ? (ICON_PX - PLATE) / 2 : 0
+    const side = crop === 'plate' ? PLATE : ICON_PX
     return sizes.map((px) => {
-        if (px === ICON_PX) return canvas.toBuffer('image/png')
+        if (px === ICON_PX && crop === 'canvas') return canvas.toBuffer('image/png')
         const small = createCanvas(px, px)
         const ctx = small.getContext('2d')
         ctx.imageSmoothingQuality = 'high'
-        ctx.drawImage(canvas, 0, 0, px, px)
+        ctx.drawImage(canvas, o, o, side, side, 0, 0, px, px)
         return small.toBuffer('image/png')
     })
 }

package/src/core/last-good.ts

@@ -0,0 +1,217 @@
+// the last good copy of the toolkit: what `sk` and the home run while the
+// checkout fails to load. The daemon clones the source after a load that
+// works (home/lib-watch.ts); the boot (cli.ts) runs the copy when the tree
+// fails to load, with one line that names the file.
+//
+// the one constraint a reader breaks first: cli.ts imports this file
+// statically, so it imports node builtins only. A lib import here would let
+// a broken file stop the boot before it can fall back.
+import { constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, relative } from 'path'
+
+/** set on a process that runs the copy: the Held record, as json */
+export const LAST_GOOD_ENV = 'SHIPKIT_LAST_GOOD'
+
+/** why a process runs code older than its tree */
+export type Held = {
+    /** epoch ms the tree was first seen failing */
+    since: number
+    /** the file that fails, relative to the lib (`src/trailer/graph.ts:12`) */
+    file: string
+    error: string
+    /** the lib root whose tree fails */
+    from: string
+    /** epoch ms the copy was taken, null when this process runs its own boot image */
+    copyAt: number | null
+}
+
+/** how long a replaced copy stays, from when it stopped being current: a
+ *  process that runs it may still import a module from it lazily */
+export const OLD_COPY_MS = 10 * 60_000
+
+/** this lib's root (its package.json beside src) */
+export const OWN_LIB = join(import.meta.dir, '../..')
+
+const real = (p: string): string => {
+    try {
+        return realpathSync(p)
+    } catch {
+        return p
+    }
+}
+
+export const lastGoodHome = (env: Record<string, string | undefined> = process.env): string =>
+    env.SHIPKIT_LAST_GOOD_HOME != null && env.SHIPKIT_LAST_GOOD_HOME !== '' ? env.SHIPKIT_LAST_GOOD_HOME : join(homedir(), '.cache/shipkit/last-good')
+
+/** one folder per lib checkout, so a worktree never runs the main checkout's copy */
+export const lastGoodDir = (lib: string, home = lastGoodHome()): string => join(home, Bun.hash(real(lib)).toString(16).padStart(16, '0'))
+
+const STAMP = 'stamp.json'
+/** in a copy that is no longer current: when it stopped being */
+const RETIRED = 'retired'
+
+/** a copy carries a stamp: the lib it was taken from and when */
+export function copyStamp(root: string): { at: number; from: string } | null {
+    try {
+        const j = JSON.parse(readFileSync(join(root, STAMP), 'utf8')) as { at?: number; from?: string }
+        return typeof j.at === 'number' && typeof j.from === 'string' ? { at: j.at, from: j.from } : null
+    } catch {
+        return null
+    }
+}
+
+/** the copy's cli and when it was taken, null when the lib has none */
+export function lastGood(lib: string, home = lastGoodHome()): { cli: string; at: number } | null {
+    const cur = join(lastGoodDir(lib, home), 'current')
+    const s = copyStamp(cur)
+    const cli = join(cur, 'src/cli.ts')
+    return s == null || !existsSync(cli) ? null : { cli, at: s.at }
+}
+
+/** clone the lib's source as the last good copy (APFS clone: about 0.2 s for
+ *  the whole source), its node_modules linked, probe it in its own folder,
+ *  then point `current` at it. Throws when the clone does not load */
+export async function takeLastGood(lib: string, o: { home?: string; now?: number } = {}): Promise<{ dir: string; ms: number }> {
+    const t0 = performance.now()
+    const now = o.now ?? Date.now()
+    const base = lastGoodDir(lib, o.home)
+    const name = `v${now}`
+    const dir = join(base, name)
+    mkdirSync(dir, { recursive: true })
+    const cp = Bun.spawn(['cp', '-c', '-R', join(lib, 'src'), join(dir, 'src')], { stdout: 'ignore', stderr: 'pipe' })
+    if ((await cp.exited) !== 0) {
+        const err = (await new Response(cp.stderr).text()).trim()
+        rmSync(dir, { recursive: true, force: true })
+        throw new Error(`could not clone ${lib}/src: ${err}`)
+    }
+    for (const f of ['package.json', 'tsconfig.json']) if (existsSync(join(lib, f))) copyFileSync(join(lib, f), join(dir, f), constants.COPYFILE_FICLONE)
+    symlinkSync(join(real(lib), 'node_modules'), join(dir, 'node_modules'))
+    writeFileSync(join(dir, STAMP), `${JSON.stringify({ at: now, from: real(lib) })}\n`)
+    // a write that landed during the clone is in it: the copy loads in its own folder, or never becomes current
+    const { probeLoad, bootEntries } = await import('./load-probe.ts')
+    const a = await probeLoad(dir, bootEntries(dir, 'all'))
+    if (!a.ok) {
+        rmSync(dir, { recursive: true, force: true })
+        throw new Error(`the clone fails to load (${a.file}: ${a.error}), so the copy before it stays current`)
+    }
+    // a link renamed over the old one: a reader sees the old copy or the new, never none
+    const link = join(base, `.current-${process.pid}`)
+    rmSync(link, { force: true })
+    symlinkSync(name, link)
+    let was: string | null = null
+    try { was = readlinkSync(join(base, 'current')) } catch { /* the first copy */ }
+    renameSync(link, join(base, 'current'))
+    // a copy ages from when it stopped being current: a process that runs it keeps its modules
+    if (was != null && was !== name && existsSync(join(base, was))) writeFileSync(join(base, was, RETIRED), `${now}\n`)
+    for (const e of readdirSync(base)) {
+        const at = /^v(\d+)$/.exec(e)
+        if (at == null || e === name) continue
+        let since = Number(at[1])
+        try { since = Number(readFileSync(join(base, e, RETIRED), 'utf8')) } catch { /* never current: a clone that failed or was cut */ }
+        if (now - since > OLD_COPY_MS) rmSync(join(base, e), { recursive: true, force: true })
+    }
+    return { dir, ms: performance.now() - t0 }
+}
+
+/** the lib file that imports `name` from `module`, read only on a failure */
+function importerOf(lib: string, name: string, module: string): string | null {
+    const want = real(module).replace(/\.[cm]?[jt]sx?$/, '')
+    const re = new RegExp(`(?:import|export)\\s*(?:type\\s*)?\\{[^}]*\\b${name.replace(/[^\w$]/g, '')}\\b[^}]*\\}\\s*from\\s*['"]([^'"]+)['"]`, 'g')
+    for (const f of new Bun.Glob('src/**/*.{ts,tsx}').scanSync(lib)) {
+        const full = join(lib, f)
+        let text: string
+        try { text = readFileSync(full, 'utf8') } catch { continue }
+        if (!text.includes(name)) continue
+        for (const m of text.matchAll(re)) {
+            if (!m[1]!.startsWith('.')) continue
+            if (real(join(full, '..', m[1]!)).replace(/\.[cm]?[jt]sx?$/, '') === want) return full
+        }
+    }
+    return null
+}
+
+/** the file a load error names, relative to `lib`, and its first line */
+export function loadFailure(e: unknown, lib: string): { file: string; error: string } {
+    const x = (e ?? {}) as { message?: string; position?: { file?: string; line?: number } | null; referrer?: string; stack?: string }
+    const rel = (p: string): string => {
+        const r = relative(real(lib), real(p))
+        return r.startsWith('..') ? p : r
+    }
+    const error = String(x.message ?? e).split('\n')[0]!.slice(0, 200)
+    // bun names the module a missing export was asked of, never the file that asked
+    const miss = /Export named '([^']+)' not found in module '([^']+)'/.exec(error)
+    if (miss != null) {
+        const importer = importerOf(lib, miss[1]!, miss[2]!)
+        return { file: rel(importer ?? miss[2]!), error: `imports '${miss[1]}', which ${rel(miss[2]!)} does not export` }
+    }
+    if (x.position?.file != null) return { file: `${rel(x.position.file)}${x.position.line != null ? `:${x.position.line}` : ''}`, error }
+    if (typeof x.referrer === 'string' && x.referrer !== '') return { file: rel(x.referrer), error }
+    const at = /\(?((?:\/[^\s():]+)+\.[cm]?[jt]sx?):(\d+)/.exec(x.stack ?? '')
+    return { file: at == null ? '?' : `${rel(at[1]!)}:${at[2]}`, error }
+}
+
+const hhmm = (t: number): string => new Date(t).toTimeString().slice(0, 5)
+
+/** when a copy was taken: HH:MM within the last hour of today, else its
+ *  date, time and age, so an old copy is never mistaken for a fresh one */
+export function copyWhen(at: number, now = Date.now()): string {
+    const d = new Date(at)
+    if (d.toDateString() === new Date(now).toDateString() && now - at < 3_600_000) return hhmm(at)
+    const age = now - at
+    const old = age < 48 * 3_600_000 ? `${Math.round(age / 3_600_000)} h old` : `${Math.floor(age / 86_400_000)} d old`
+    const day = `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+    return `${day} ${hhmm(at)}, ${old}`
+}
+
+/** the one line every surface shows (the hub, the overview, a log) */
+export const heldText = (h: Held): string =>
+    `running last good code since ${hhmm(h.since)} because ${h.file} fails to load: ${h.error}${h.copyAt == null ? '' : ` (the copy from ${copyWhen(h.copyAt)})`}`
+
+let held: Held | null = null
+
+/** this process's own state: a refused restart set it, or the boot that ran
+ *  the copy left it in the env */
+export function heldNow(): Held | null {
+    if (held != null) return held
+    const raw = process.env[LAST_GOOD_ENV]
+    if (raw == null || raw === '' || copyStamp(OWN_LIB) == null) return null
+    try {
+        return JSON.parse(raw) as Held
+    } catch {
+        return null
+    }
+}
+
+export function setHeld(h: Held | null): void {
+    held = h
+}
+
+/** the tree this process should go back to: its own, or the one its copy stands in for */
+export const homeLib = (): string => (copyStamp(OWN_LIB)?.from ?? OWN_LIB)
+
+/** the boot of a tree that loads: an env a copy left is not this process's */
+export function bootLoaded(): void {
+    if (copyStamp(OWN_LIB) == null) delete process.env[LAST_GOOD_ENV]
+}
+
+/** the boot of a tree that failed to load: runs the copy (never returns), or
+ *  returns when there is none so the caller throws the error itself */
+export function runLastGood(e: unknown, argv: string[]): void {
+    const f = loadFailure(e, OWN_LIB)
+    // the copy itself failing is the error to show, never a loop
+    if (copyStamp(OWN_LIB) != null) return
+    const copy = lastGood(OWN_LIB)
+    if (copy == null) {
+        process.stderr.write(`FAIL shipkit: ${f.file} fails to load (${f.error}), and this checkout has no last good copy: the home's daemon keeps one\n`)
+        return
+    }
+    const h: Held = { since: Date.now(), file: f.file, error: f.error, from: real(OWN_LIB), copyAt: copy.at }
+    process.stderr.write(`WARN shipkit: ${f.file} fails to load (${f.error}), so this runs the last good copy from ${copyWhen(copy.at)}\n`)
+    const env = Object.fromEntries(Object.entries({ ...process.env, [LAST_GOOD_ENV]: JSON.stringify(h) }).filter((x): x is [string, string] => x[1] != null))
+    const args = [process.execPath, ...process.execArgv, copy.cli, ...argv]
+    const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
+    if (typeof execve === 'function') execve.call(process, process.execPath, args, env)
+    const child = Bun.spawnSync(args, { cwd: process.cwd(), stdout: 'inherit', stderr: 'inherit', stdin: 'inherit', env })
+    process.exit(child.exitCode ?? 1)
+}

package/src/core/load-probe.ts

@@ -0,0 +1,71 @@
+// does a tree load: a child bun imports its entries and says which file
+// fails. Asked before a machine process restarts onto new code, and before
+// the daemon keeps a copy as the last good one. Run as a child so a module
+// that fails, or one whose top level runs, never touches the asking process.
+import { join } from 'path'
+import { loadFailure } from './last-good.ts'
+import type { LoadVerdict } from '../serve/stale-restart.ts'
+
+export type LoadAnswer = { ok: true; ms: number } | { ok: false; ms: number; file: string; error: string }
+
+export type Role = 'daemon' | 'pm' | 'web' | 'serve'
+
+const RUNNER: Record<Role, string> = { daemon: 'src/home/run-daemon.ts', pm: 'src/home/run-pm.ts', web: 'src/home/run-web.ts', serve: 'src/serve/run-serve.ts' }
+
+/** the modules a restart through the cli loads: the boot's (cli.ts
+ *  `loadBoot`: the registry and what runs before it) and the role's runner;
+ *  `all`: every role's, what a copy every process may run must load */
+export const bootEntries = (lib: string, role?: Role | 'all'): string[] => [
+    join(lib, 'src/cli.ts'),
+    ...(role == null ? [] : (role === 'all' ? Object.values(RUNNER) : [RUNNER[role]]).map((r) => join(lib, r))),
+]
+
+/** import `entries` in a child bun from `lib`'s own probe file */
+export async function probeLoad(lib: string, entries: string[]): Promise<LoadAnswer> {
+    const t0 = performance.now()
+    const p = Bun.spawn([process.execPath, join(lib, 'src/core/load-probe.ts'), ...entries], { cwd: lib, stdout: 'pipe', stderr: 'pipe', env: { ...process.env, SHIPKIT_NO_HOME: '1' } })
+    const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    const ms = performance.now() - t0
+    if (code === 0) return { ok: true, ms }
+    try {
+        const j = JSON.parse(out.trim().split('\n').at(-1) ?? '') as { file: string; error: string }
+        return { ok: false, ms, file: j.file, error: j.error }
+    } catch {
+        // the probe file itself did not load
+        const line = err.split('\n').find((l) => /error/i.test(l)) ?? err.trim().split('\n')[0] ?? `exit ${code}`
+        return { ok: false, ms, file: 'src/core/load-probe.ts', error: line.trim().slice(0, 200) }
+    }
+}
+
+/** one probe per state of the tree: asked again only once the key moves */
+export class TreeProbe {
+    private key: string | null = null
+    private verdict: LoadVerdict = 'pending'
+
+    constructor(private readonly run: () => Promise<LoadAnswer>, private readonly keyOf: () => string) {}
+
+    loads(): LoadVerdict {
+        const k = this.keyOf()
+        if (k !== this.key) {
+            this.key = k
+            this.verdict = 'pending'
+            const land = (v: LoadVerdict): void => { if (this.key === k) this.verdict = v }
+            void this.run().then((a) => land(a.ok ? 'ok' : { file: a.file, error: a.error }), (e: Error) => land({ file: '?', error: e.message }))
+        }
+        return this.verdict
+    }
+}
+
+if (import.meta.main) {
+    const lib = join(import.meta.dir, '../..')
+    for (const e of process.argv.slice(2)) {
+        try {
+            const m = (await import(e)) as { loadBoot?: () => Promise<unknown> }
+            if (typeof m.loadBoot === 'function') await m.loadBoot()
+        } catch (x) {
+            console.log(JSON.stringify(loadFailure(x, lib)))
+            process.exit(3)
+        }
+    }
+    process.exit(0)
+}

package/src/core/reexec.ts

@@ -5,7 +5,9 @@
 // code, which keeps the terminal but leaves this process waiting under it.
 import { existsSync } from 'fs'
 
-const argvOf = (): string[] => [process.execPath, ...process.execArgv, ...process.argv.slice(1)]
+/** `entry` in place of the running script: a process on the last good copy
+ *  goes back to the tree's own cli (core/last-good.ts) */
+const argvOf = (entry?: string): string[] => [process.execPath, ...process.execArgv, ...(entry == null ? process.argv.slice(1) : [entry, ...process.argv.slice(2)])]
 
 /** why this invocation cannot run again, null when it can. Asked BEFORE a
  *  caller tears anything down, so a refusal leaves the process serving */
@@ -16,8 +18,8 @@ export function reexecBlocker(): string | null {
 }
 
 /** never returns. `env` defaults to this process's own */
-export function reexecSelf(env: Record<string, string | undefined> = process.env): never {
-    const argv = argvOf()
+export function reexecSelf(env: Record<string, string | undefined> = process.env, entry?: string): never {
+    const argv = argvOf(entry)
     const clean = Object.fromEntries(Object.entries(env).filter((e): e is [string, string] => e[1] != null))
     const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
     if (typeof execve === 'function') execve.call(process, process.execPath, argv, clean)

package/src/fleet/push-fleet.ts

@@ -0,0 +1,80 @@
+// push every house repo that holds commits its remote does not: `sk fleet
+// push` and the activity page's push button run this one path. A plain
+// `git push`, never a force: a branch that also fell behind its remote waits
+// for a pull, a branch with no upstream goes to its one remote with -u, and
+// git itself refuses anything that is not a fast-forward. Local git only, no
+// fetch first: "behind" is as of the last fetch, and the push is what finds
+// out for sure.
+import { parseStatus } from '../home/activity.ts'
+
+export type PushAction = 'push' | 'push-upstream' | 'none' | 'skip'
+export type PushPlan = { name: string; path: string; branch: string | null; remote: string | null; ahead: number; action: PushAction; why: string }
+export type PushResult = PushPlan & { ok: boolean; line: string }
+
+/** at most this many pushes at once */
+const PARALLEL = 4
+const PUSH_MS = 60_000
+
+async function git(cwd: string, args: string[], ms = 15_000): Promise<{ code: number; out: string; err: string }> {
+    // a push that would ask for a password fails instead of hanging the page
+    const p = Bun.spawn(['git', ...args], { cwd, stdout: 'pipe', stderr: 'pipe', env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
+    const timer = setTimeout(() => p.kill(), ms)
+    const [out, err, code] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text(), p.exited])
+    clearTimeout(timer)
+    return { code, out, err }
+}
+
+/** what to do with one repo, from `git status --porcelain=v2 --branch`, its
+ *  remotes and its commit count. Pure: the tests feed it text */
+export function planOf(repo: { name: string; path: string }, status: string, remotes: string[], commits: number): PushPlan {
+    const s = parseStatus(status)
+    const base = { name: repo.name, path: repo.path, branch: s.branch, remote: null as string | null, ahead: s.ahead ?? 0 }
+    if (s.branch == null) return { ...base, action: 'skip', why: s.detached != null ? `detached at ${s.detached}: no branch to push` : 'no commit yet' }
+    if (s.upstream == null) {
+        if (commits === 0) return { ...base, action: 'none', why: 'no commit yet' }
+        const remote = remotes.length === 1 ? remotes[0]! : remotes.includes('origin') ? 'origin' : null
+        if (remote == null) return { ...base, action: 'skip', why: remotes.length === 0 ? 'no remote to push to' : `no upstream, and ${remotes.length} remotes: set one with git push -u <remote> ${s.branch}` }
+        return { ...base, remote, ahead: commits, action: 'push-upstream', why: `no upstream: push -u ${remote} ${s.branch}` }
+    }
+    if (s.gone) return { ...base, action: 'skip', why: `its upstream ${s.upstream} is gone` }
+    const ahead = s.ahead ?? 0
+    const behind = s.behind ?? 0
+    if (ahead === 0) return { ...base, action: 'none', why: 'pushed' }
+    if (behind > 0) return { ...base, action: 'skip', why: `${ahead} ahead and ${behind} behind ${s.upstream}: pull first, never a force` }
+    return { ...base, remote: s.upstream.split('/')[0] ?? null, action: 'push', why: `${ahead} unpushed to ${s.upstream}` }
+}
+
+export async function pushPlan(repo: { name: string; path: string }): Promise<PushPlan> {
+    const [status, remotes, count] = await Promise.all([
+        git(repo.path, ['status', '--porcelain=v2', '--branch']),
+        git(repo.path, ['remote']),
+        git(repo.path, ['rev-list', '--count', 'HEAD']),
+    ])
+    if (status.code !== 0) return { name: repo.name, path: repo.path, branch: null, remote: null, ahead: 0, action: 'skip', why: `git status failed: ${status.err.trim().split('\n')[0]}` }
+    return planOf(repo, status.out, remotes.out.split('\n').filter((r) => r !== ''), Number(count.out.trim()) || 0)
+}
+
+async function pushOne(p: PushPlan): Promise<PushResult> {
+    if (p.action !== 'push' && p.action !== 'push-upstream') return { ...p, ok: p.action === 'none', line: `${p.action === 'none' ? 'ok' : 'skip'}: ${p.name}: ${p.why}` }
+    const args = p.action === 'push' ? ['push'] : ['push', '-u', p.remote!, p.branch!]
+    const r = await git(p.path, args, PUSH_MS)
+    if (r.code === 0) return { ...p, ok: true, line: `ok: ${p.name}: pushed ${p.ahead} commit${p.ahead === 1 ? '' : 's'} (${p.branch})` }
+    const why = r.err.split('\n').map((l) => l.trim()).filter((l) => l !== '' && !l.startsWith('hint:')).slice(-1)[0] ?? `git push exited ${r.code}`
+    return { ...p, ok: false, line: `FAIL: ${p.name}: git ${args.join(' ')}: ${why}` }
+}
+
+/** every repo planned, the ones that need it pushed, a few at a time; `dry`
+ *  plans only. Results come back in the repos' order */
+export async function pushFleet(repos: { name: string; path: string }[], o: { dry?: boolean } = {}): Promise<PushResult[]> {
+    const plans = await Promise.all(repos.map(pushPlan))
+    if (o.dry === true) return plans.map((p) => ({ ...p, ok: p.action !== 'skip', line: `${p.action === 'skip' ? 'skip' : p.action === 'none' ? 'ok' : 'would push'}: ${p.name}: ${p.why}` }))
+    const out: PushResult[] = new Array(plans.length)
+    let next = 0
+    await Promise.all(Array.from({ length: PARALLEL }, async () => {
+        while (next < plans.length) {
+            const i = next++
+            out[i] = await pushOne(plans[i]!)
+        }
+    }))
+    return out
+}