rvlib-shipkit 1.1.0 → 1.2.0

package/src/home/home-routes.ts

@@ -0,0 +1,208 @@
+// the daemon's api, apart from the page so a test reaches it without a bundle:
+// its own /api/home/* and every repo's hub under /r/<repo>/. The daemon
+// decides WHEN a hub loads and never what is true: every verdict still comes
+// from each repo's own runner and ledger. The machine resources are pm's
+// (run-pm.ts), and the page reaches them through the web at /api/pm/*.
+import { existsSync } from 'fs'
+import { dirname, join } from 'path'
+import { fileURLToPath } from 'url'
+import { installedVersion, isBehind } from '../fleet/scan-fleet.ts'
+import { LIB_VERSION } from '../core/lib-version.ts'
+import { projectGutter, type ProjectRow } from '../serve/project-gutter-route.ts'
+import type { WiredRepo } from '../serve/project-gutter.ts'
+import { sameOrigin } from '../serve/same-origin.ts'
+import type { HomeState } from './home-state.ts'
+import { tailLines } from './supervise.ts'
+import { Hubs, type WorkerView } from './hubs.ts'
+import type { Planner, PlanRow } from '../plan/planner.ts'
+import type { Widgets, WidgetView } from './widgets.ts'
+
+/** how often the daemon looks at every repo */
+export const TICK_MS = 2_000
+
+export type ModernizeView = { status: 'running' | 'done' | 'failed'; code: number | null; tail: string[] }
+
+export type HomeAnswer = {
+    version: string
+    workers: WorkerView[]
+    /** the repos flagged active by hand */
+    active: string[]
+    /** repo → its installed shipkit, for every repo behind this home's */
+    behind: Record<string, string>
+    modernize: Record<string, ModernizeView>
+}
+
+export type HomeDeps = {
+    root: string
+    name: string
+    port: number
+    dir: string
+    hubs: Hubs
+    state: HomeState
+    /** the rail rows, the same measure a hub's rail reads */
+    gutter: ReturnType<typeof projectGutter>
+    /** the machine's one plan, which this tick drives. Absent = nothing runs
+     *  on its own (a test of the routes alone) */
+    plan?: Planner
+    /** the repos it loads, by name; absent = every house repo. A smoke on a
+     *  real machine keeps the others out, so no save there starts a gate */
+    only?: Set<string>
+    /** every house repo's widgets, rendered on the daemon's tick. Absent =
+     *  none (a test of the routes alone) */
+    widgets?: Widgets
+    /** brings a repo current (modernizeCmd); resolves to its exit code */
+    modernize?: (repo: WiredRepo, log: string) => Promise<number>
+}
+
+const CLI = fileURLToPath(new URL('../cli.ts', import.meta.url))
+
+/** what bringing a repo current runs: its first install when it has none,
+ *  else the fleet update, which goes through the repo's own gate */
+export function modernizeCmd(repo: WiredRepo, root: string): { cmd: string[]; cwd: string } {
+    if (!existsSync(join(repo.path, 'node_modules'))) return { cmd: ['bun', 'install'], cwd: repo.path }
+    return { cmd: ['bun', CLI, 'fleet', '--update', '--only', repo.name], cwd: root }
+}
+
+export const runModernize = async (repo: WiredRepo, root: string, log: string): Promise<number> => {
+    const { mkdirSync, openSync, closeSync } = await import('fs')
+    mkdirSync(dirname(log), { recursive: true })
+    const fd = openSync(log, 'w')
+    try {
+        const { cmd, cwd } = modernizeCmd(repo, root)
+        const p = Bun.spawn(cmd, { cwd, stdio: ['ignore', fd, fd] })
+        return await p.exited
+    } finally {
+        closeSync(fd)
+    }
+}
+
+/** active = an agent works in it, VS Code has it open, or it is flagged by hand */
+export function activeSet(rows: ProjectRow[], flagged: string[]): Set<string> {
+    const out = new Set(flagged)
+    for (const r of rows) if ((r.sessions != null && r.sessions > 0) || r.vscode === true) out.add(r.name)
+    return out
+}
+
+/** the monitor area's data: every widget's last html */
+export type WidgetsAnswer = { widgets: WidgetView[]; errors: string[] }
+
+/** the planned page's data: every row of the machine's plan */
+export type PlannedAnswer = { now: number; rows: PlanRow[]; errors: { repo: string; error: string }[]; running: boolean }
+
+export function homeRoutes(d: HomeDeps) {
+    let repos: WiredRepo[] = []
+    let rows: ProjectRow[] = []
+    const modernizing = new Map<string, ModernizeView & { log: string }>()
+    const modernizeLog = (repo: string): string => join(d.dir, 'modernize', `${repo}.log`)
+
+    async function refresh(): Promise<void> {
+        const a = await d.gutter.answer()
+        rows = a.projects
+        repos = a.projects.filter((p) => d.only == null || d.only.has(p.name)).map((p) => ({ name: p.name, path: p.path, icon: null }))
+        d.hubs.sync(repos)
+    }
+
+    let active = new Set<string>()
+    if (d.plan != null) d.plan.active = (name) => active.has(name)
+
+    async function tick(): Promise<void> {
+        await refresh()
+        active = activeSet(rows, d.state.data.active)
+        // the plan's clock: one look per tick, and it starts at most one batch
+        d.plan?.tick()
+        // a widget render never holds the tick back
+        void d.widgets?.tick(repos.map((r) => ({ name: r.name, path: r.path }))).catch((e) => console.error(`WARN the widgets broke: ${(e as Error).message}`))
+        await d.hubs.tick(active)
+    }
+
+    function answer(): HomeAnswer {
+        const behind: Record<string, string> = {}
+        for (const r of repos) {
+            const v = installedVersion(r.path, 'rvlib-shipkit')
+            if (v != null && isBehind(v, LIB_VERSION)) behind[r.name] = v
+        }
+        const modernize: Record<string, ModernizeView> = {}
+        for (const [k, m] of modernizing) modernize[k] = { status: m.status, code: m.code, tail: tailLines(m.log, 40) }
+        return { version: LIB_VERSION, workers: d.hubs.views(repos), active: d.state.data.active, behind, modernize }
+    }
+
+    const find = (name: unknown): WiredRepo | null => repos.find((r) => r.name === name) ?? null
+    const body = async (req: Request): Promise<Record<string, unknown>> => (await req.json().catch(() => ({}))) as Record<string, unknown>
+
+    async function handle(req: Request, srv?: Parameters<Hubs['dispatch']>[2]): Promise<Response | null> {
+        const path = new URL(req.url).pathname
+        // every repo's hub, which makes its own same origin check
+        if (path.startsWith('/r/')) {
+            if (repos.length === 0) await refresh()
+            return d.hubs.dispatch(req, path, srv as Parameters<Hubs['dispatch']>[2])
+        }
+        if (path === '/hub.json')
+            // the identity a client probes (homeUp), through the web or here
+            return Response.json({ hub: 'shipkit-home', name: d.name, root: d.root, version: LIB_VERSION }, { headers: { 'access-control-allow-origin': '*' } })
+        if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
+        if (path.startsWith('/api/projects')) return d.gutter.handle(req, path)
+        // the web asks which page routes to serve: one per house repo
+        if (path === '/api/home/repos.json') {
+            if (repos.length === 0) await refresh()
+            return Response.json({ repos: d.hubs.names() })
+        }
+        if (path === '/api/home/planned.json') {
+            if (repos.length === 0) await refresh()
+            const out: PlannedAnswer = { now: Date.now(), rows: d.plan?.rows() ?? [], errors: d.plan?.errors() ?? [], running: d.plan?.busy() === true }
+            return Response.json(out)
+        }
+        if (path === '/api/home/widgets.json') {
+            const out: WidgetsAnswer = { widgets: d.widgets?.views() ?? [], errors: d.widgets?.errors ?? [] }
+            return Response.json(out)
+        }
+        if (path === '/api/home.json') {
+            if (repos.length === 0) await refresh()
+            return Response.json(answer())
+        }
+        if (req.method !== 'POST') return null
+        if (path === '/api/home/hub') {
+            const b = await body(req)
+            if (repos.length === 0) await refresh()
+            const r = find(b.name)
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            if (b.act === 'ensure') return Response.json(d.hubs.ensure(r))
+            if (b.act === 'stop') return Response.json(d.hubs.stop(r))
+            if (b.act === 'restart') return Response.json(await d.hubs.restart(r))
+            return new Response(`act must be ensure, stop or restart`, { status: 400 })
+        }
+        if (path === '/api/home/planned/run') {
+            const b = await body(req)
+            if (d.plan == null || !d.plan.ask(String(b.repo), String(b.check))) return new Response(`no planned check ${String(b.check)} in ${String(b.repo)}`, { status: 404 })
+            d.plan.tick()
+            return Response.json({ ok: true })
+        }
+        if (path === '/api/home/active') {
+            const b = await body(req)
+            if (find(b.name) == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            d.state.setActive(String(b.name), b.on === true)
+            return Response.json({ active: d.state.data.active })
+        }
+        if (path === '/api/home/modernize') {
+            const b = await body(req)
+            const r = find(b.name)
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            if (modernizing.get(r.name)?.status === 'running') return new Response(`already modernizing ${r.name}`, { status: 409 })
+            const log = modernizeLog(r.name)
+            const m = { status: 'running' as ModernizeView['status'], code: null as number | null, tail: [], log }
+            modernizing.set(r.name, m)
+            void (d.modernize ?? ((repo, l) => runModernize(repo, d.root, l)))(r, log)
+                .then(async (code) => {
+                    m.status = code === 0 ? 'done' : 'failed'
+                    m.code = code
+                    // the hub loads again on what the update installed
+                    if (code === 0) await d.hubs.restart(r)
+                })
+                .catch(() => { m.status = 'failed' })
+            return Response.json({ ok: true })
+        }
+        return null
+    }
+
+    return { handle, tick, answer, refresh }
+}
+

package/src/home/home-start.ts

@@ -0,0 +1,105 @@
+// getting to a running home from anywhere: is pm installed, start it, find
+// the house repo it runs from, open a window on it. `shipkit gui` and the
+// serve handoff both come through here.
+import { existsSync, mkdirSync, readFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join, resolve } from 'path'
+import { gitRoot } from '../core/git-root.ts'
+import { homeRepo, houseIndex } from '../serve/project-gutter.ts'
+import { BUNDLE_ID, canBuildGui, ensureGuiApp } from './gui-app.ts'
+import { LABEL, plistPath } from './home-launchd.ts'
+import { childLog, daemonPort, daemonUp, homeDir, homePort, homeUp, pmLog } from './home-paths.ts'
+
+/** the pm LaunchAgent is installed: on this machine no hub runs outside the home */
+export const homeInstalled = (): boolean => existsSync(plistPath())
+
+/** set, a machine with no LaunchAgent still sends its hubs and gates to the
+ *  home that answers on SHIPKIT_HOME_PORT (a home started by hand, a test) */
+export const USE_HOME_ENV = 'SHIPKIT_USE_HOME'
+
+/** this machine runs its hubs and gates in the home */
+export const homeWanted = (env: Record<string, string | undefined> = process.env, installed: () => boolean = homeInstalled): boolean =>
+    (env[USE_HOME_ENV] != null && env[USE_HOME_ENV] !== '') || installed()
+
+/** how long a start waits for the home to answer */
+export const START_WAIT_MS = 15_000
+
+/** kick the installed pm agent and wait until the role answers: the daemon
+ *  for a terminal client, the web for a window. Throws, loud, when it does
+ *  not: a caller must never fall back to a hub of its own */
+export async function startHome(o: { wait?: number; need?: 'daemon' | 'web' } = {}): Promise<void> {
+    const need = o.need ?? 'daemon'
+    const up = (): Promise<boolean> => (need === 'daemon' ? daemonUp() : homeUp(homePort()))
+    if (await up()) return
+    const p = Bun.spawn(['launchctl', 'kickstart', `gui/${process.getuid?.() ?? 501}/${LABEL}`], { stdout: 'ignore', stderr: 'pipe' })
+    const err = (await new Response(p.stderr).text()).trim()
+    if ((await p.exited) !== 0) throw new Error(`launchctl kickstart ${LABEL} failed: ${err}. Reinstall it with \`shipkit pm install\` from the house repo`)
+    const until = Date.now() + (o.wait ?? START_WAIT_MS)
+    while (Date.now() < until) {
+        if (await up()) return
+        await Bun.sleep(250)
+    }
+    const port = need === 'daemon' ? daemonPort() : homePort()
+    throw new Error(`the ${need} did not answer on :${port} within ${Math.round((o.wait ?? START_WAIT_MS) / 1000)}s: see ${childLog(homeDir(), need)} and ${pmLog()}`)
+}
+
+/** the cli the home runs from its repo: the one that repo's own `hub` script
+ *  runs (an installed copy, or the lib source in the repo that hosts it),
+ *  else this one */
+export function houseCli(root: string, own: string): string {
+    try {
+        const hub = (JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { scripts?: Record<string, string> }).scripts?.['hub'] ?? ''
+        const cli = /(\S*cli\.ts)\b/.exec(hub)?.[1]
+        if (cli != null) {
+            const abs = resolve(root, cli)
+            if (existsSync(abs)) return abs
+        }
+    } catch { /* no package.json: this cli */ }
+    return own
+}
+
+/** the repo that hosts the house wiki, seen from any house repo, or null */
+export function houseRootOf(cwd: string): string | null {
+    const index = houseIndex(homeRepo(cwd), homedir())
+    if (index == null) return null
+    return gitRoot(dirname(index))?.top ?? null
+}
+
+export const CHROME = process.env.CHROME ?? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+/** the window's own Chrome profile: its own dock icon and cookies, apart from the everyday browser */
+export const guiProfile = (): string => join(homeDir(), 'gui-profile')
+const GUI_DISK_CACHE = 32 * 1024 * 1024
+
+/** the command that opens one more home window: a Chrome app window (no tabs,
+ *  no address bar) on its own profile, else the default browser */
+export function windowCmd(url: string, o: { chrome?: string; platform?: string } = {}): string[] {
+    const chrome = o.chrome ?? CHROME
+    const platform = o.platform ?? process.platform
+    // no component downloads and a small disk cache: the profile shows one
+    // page, and those two are most of what grows it (retention.ts caps it)
+    if (existsSync(chrome)) return [chrome, `--app=${url}`, `--user-data-dir=${guiProfile()}`, '--no-first-run', '--no-default-browser-check', '--disable-component-update', `--disk-cache-size=${GUI_DISK_CACHE}`]
+    return platform === 'darwin' ? ['open', url] : ['xdg-open', url]
+}
+
+/** one more home window: the native app where it can be built (its own
+ *  dock icon, the house mark), else a Chrome app window. `warn` hears why the
+ *  native one was not used */
+export function openWindow(url: string, o: { root?: string | null; version?: string; warn?: (l: string) => void } = {}): string[] {
+    if (canBuildGui()) {
+        try {
+            const { app, rebuilt } = ensureGuiApp({ root: o.root ?? houseRootOf(process.cwd()) ?? process.cwd(), version: o.version ?? '0' })
+            // a running copy is the old build: it quits, and the new one opens the window
+            if (rebuilt) Bun.spawnSync(['osascript', '-e', `quit app id "${BUNDLE_ID}"`], { stdout: 'ignore', stderr: 'ignore' })
+            const cmd = ['open', '-a', app, url]
+            Bun.spawn(cmd, { stdio: ['ignore', 'ignore', 'ignore'] })
+            return cmd
+        } catch (e) {
+            o.warn?.(`WARN the shipkit app could not be built, so this window is a Chrome one: ${(e as Error).message}`)
+        }
+    }
+    mkdirSync(guiProfile(), { recursive: true })
+    const cmd = windowCmd(url)
+    // detached: the window outlives the command that opened it
+    Bun.spawn(cmd, { stdio: ['ignore', 'ignore', 'ignore'], detached: true }).unref()
+    return cmd
+}

package/src/home/home-state.ts

@@ -0,0 +1,43 @@
+// what the home remembers across restarts, and only that: the repos flagged
+// active by hand. One row of the machine db (core/machine-db.ts), edited by
+// the page.
+import { importMachineFile, machineGet, machineSet } from '../core/machine-db.ts'
+import { stateFile } from './home-paths.ts'
+
+export type HomeStateData = {
+    /** repos whose hub runs whether or not an agent works in them */
+    active: string[]
+}
+
+const KEY = 'home.active'
+
+export class HomeState {
+    data: HomeStateData
+
+    /** `dir` is the home dir, where the json file an older copy wrote is
+     *  read once into the db */
+    constructor(dir: string) {
+        importMachineFile<string[]>(KEY, stateFile(dir), (t) => HomeState.parse(t).active)
+        this.data = { active: HomeState.clean(machineGet<unknown>(KEY)) }
+    }
+
+    static parse(text: string): HomeStateData {
+        try {
+            return { active: HomeState.clean((JSON.parse(text) as Partial<HomeStateData>).active) }
+        } catch {
+            return { active: [] }
+        }
+    }
+
+    private static clean(v: unknown): string[] {
+        return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+    }
+
+    setActive(name: string, on: boolean): void {
+        const set = new Set(this.data.active)
+        if (on) set.add(name)
+        else set.delete(name)
+        this.data = { ...this.data, active: [...set].sort() }
+        if (!machineSet(KEY, this.data.active)) throw new Error('the machine db could not be written, so the active flag is not saved')
+    }
+}

package/src/home/home-words.ts

@@ -0,0 +1,12 @@
+// the words the home's server and page both need, in a module with no node
+// import, so the page bundle can take it.
+
+/** the blocker the page answers with an install button */
+export const NOT_INSTALLED = 'rvlib-shipkit is not installed here: run `bun install`'
+
+/** the last line of a run a hub streams to a terminal: its exit code follows */
+export const RUN_EXIT = '\u0000shipkit-exit '
+
+/** a line of a run a hub streams to a terminal: the gate job it started, so a
+ *  terminal whose stream is cut follows the rest from the job folder */
+export const RUN_JOB = '\u0000shipkit-job '

package/src/home/hubs.ts

@@ -0,0 +1,286 @@
+// every house repo's hub, IN the home process: one runtime per repo
+// (serve/hub-runtime.ts), loaded at boot one after the other, served under
+// /r/<repo>/ of the home's one server. A repo whose config or deps fail to
+// load reads crashed with the error, and the others keep serving.
+//
+// the one constraint a reader breaks first: nothing here starts a gate. Every
+// run nobody asked for comes from the machine's one plan (plan/planner.ts),
+// which each loaded hub joins. An edit of a repo config reloads that repo's
+// hub alone, once its gate is done: the daemon runs with no bun watch, so one
+// repo's edit never restarts the others (lib-watch.ts).
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import type { WiredRepo } from '../serve/project-gutter.ts'
+import type { HubRuntime, ServeIo } from '../serve/hub-runtime.ts'
+import { configStamp, PING_EVERY_MS } from '../serve/hub-runtime.ts'
+import { capLog, tailLines, type ProcStatus } from './supervise.ts'
+import { hubBase, hubLog } from './home-paths.ts'
+import { NOT_INSTALLED } from './home-words.ts'
+
+/** what the home needs of a loaded hub */
+export type LoadedHub = Pick<HubRuntime, 'handler' | 'start' | 'stop' | 'ping' | 'busy'> & { uses: string[] }
+
+export type HubLoader = (repo: WiredRepo, io: ServeIo, o: { fresh: boolean }) => Promise<LoadedHub>
+
+export type WorkerView = {
+    id: string
+    repo: string
+    status: ProcStatus
+    /** the home's pid while the hub is loaded: it runs in the home */
+    pid: number | null
+    /** epoch ms of the last status change */
+    since: number
+    /** why it is not up, when that is known and `blocked` does not say it */
+    note: string | null
+    /** the home's port, which serves every hub */
+    port: number
+    /** the hub page, on the home's origin */
+    url: string
+    /** why the home cannot load it at all */
+    blocked: string | null
+    /** the last lines of its log, while it is not up */
+    tail: string[]
+    /** the machine resources its config names in serve.uses */
+    uses: string[]
+}
+
+type Entry = {
+    repo: WiredRepo
+    status: ProcStatus
+    since: number
+    note: string | null
+    rt: LoadedHub | null
+    loading: Promise<void> | null
+    /** loads done, so a view tells a reload from the first one */
+    loads: number
+    /** stopped by hand: nothing but a restart loads it again */
+    held: boolean
+    /** its repo.config.ts as the last load read it */
+    stamp: string
+}
+
+/** why the home cannot load this repo's hub, or null when it can */
+export function hubBlocker(path: string): string | null {
+    if (!existsSync(join(path, 'repo.config.ts'))) return 'no repo.config.ts: this repo is not wired to shipkit'
+    return null
+}
+
+/** a load that failed on a fresh clone: its dependencies are not installed */
+function notInstalled(path: string): boolean {
+    if (existsSync(join(path, 'node_modules'))) return false
+    try {
+        const pkg = JSON.parse(readFileSync(join(path, 'package.json'), 'utf8')) as { dependencies?: object; devDependencies?: object }
+        return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).length > 0
+    } catch {
+        return false
+    }
+}
+
+export class Hubs {
+    private entries = new Map<string, Entry>()
+    private queue: Promise<void> = Promise.resolve()
+    private now: () => number
+    private lastPing = -Infinity
+
+    /** `prepare` runs before each load and may edit the repo's config (the
+     *  identity fill): the stamp is taken after it, so its edit is no reload */
+    constructor(private o: { dir: string; port: number; load: HubLoader; prepare?: (repo: WiredRepo, io: ServeIo) => Promise<void>; now?: () => number }) {
+        this.now = o.now ?? Date.now
+    }
+
+    private io(e: Entry): ServeIo {
+        const file = hubLog(this.o.dir, e.repo.name)
+        const put = (l: string): void => {
+            try {
+                mkdirSync(dirname(file), { recursive: true })
+                appendFileSync(file, `${l}\n`)
+            } catch { /* a full disk loses a log line, never the hub */ }
+        }
+        return { print: put, printErr: put }
+    }
+
+    private entry(repo: WiredRepo): Entry {
+        let e = this.entries.get(repo.name)
+        if (e == null) {
+            e = { repo, status: 'down', since: this.now(), note: null, rt: null, loading: null, loads: 0, held: false, stamp: '' }
+            this.entries.set(repo.name, e)
+        }
+        e.repo = repo
+        return e
+    }
+
+    private set(e: Entry, status: ProcStatus, note: string | null = null): void {
+        e.status = status
+        e.note = note
+        e.since = this.now()
+    }
+
+    /** queue a load: one at a time for the machine, in the order asked */
+    private schedule(e: Entry, fresh: boolean): Promise<void> {
+        if (e.loading != null) return e.loading
+        this.set(e, 'starting')
+        const run = this.queue.then(async () => {
+            const blocked = hubBlocker(e.repo.path)
+            if (blocked != null) {
+                this.set(e, 'down', blocked)
+                return
+            }
+            const io = this.io(e)
+            try {
+                if (this.o.prepare != null) await this.o.prepare(e.repo, io).catch((err) => io.printErr(`WARN ${e.repo.name}: ${(err as Error).message}`))
+                e.stamp = configStamp(e.repo.path)
+                const rt = await this.o.load(e.repo, io, { fresh: fresh || e.loads > 0 })
+                // a stop by hand came while it loaded, and wins
+                if (e.held) {
+                    rt.stop({ procs: true })
+                    this.set(e, 'down', 'stopped by hand')
+                    return
+                }
+                rt.start()
+                e.rt = rt
+                e.loads++
+                this.set(e, 'up')
+            } catch (err) {
+                if (e.held) return
+                const msg = (err as Error).message
+                io.printErr(`FAIL: ${e.repo.name}'s hub did not load: ${msg}`)
+                this.set(e, 'crashed', msg)
+            }
+        }).finally(() => { e.loading = null })
+        e.loading = run
+        this.queue = run.catch(() => {})
+        return run
+    }
+
+    /** the list of house repos moved: a new one loads, a gone one stops. The
+     *  first call is the boot: every repo queues, in rail order */
+    sync(repos: WiredRepo[]): void {
+        const names = new Set(repos.map((r) => r.name))
+        for (const [name, e] of this.entries) {
+            if (names.has(name)) continue
+            e.rt?.stop({ procs: true })
+            this.entries.delete(name)
+        }
+        for (const r of repos) {
+            const known = this.entries.has(r.name)
+            const e = this.entry(r)
+            if (!known) void this.schedule(e, false)
+        }
+    }
+
+    /** load it when it is down, and say where it stands */
+    ensure(repo: WiredRepo): WorkerView {
+        const e = this.entry(repo)
+        if (e.status === 'down' && e.rt == null && !e.held && hubBlocker(repo.path) == null) void this.schedule(e, false)
+        return this.view(e)
+    }
+
+    /** held down until a restart; a load in flight is dropped when it lands */
+    stop(repo: WiredRepo): WorkerView {
+        const e = this.entry(repo)
+        e.held = true
+        e.rt?.stop({ procs: true })
+        e.rt = null
+        this.set(e, 'down', 'stopped by hand')
+        return this.view(e)
+    }
+
+    /** stop, then load again with the config read fresh */
+    async restart(repo: WiredRepo): Promise<WorkerView> {
+        const e = this.entry(repo)
+        await e.loading
+        e.held = false
+        e.rt?.stop({ procs: true })
+        e.rt = null
+        await this.schedule(e, true)
+        return this.view(e)
+    }
+
+    /** a request under /r/<repo>/: waits for a load in flight, then the
+     *  repo's own handler answers with the path below its base */
+    async dispatch(req: Request, path: string, srv: Parameters<LoadedHub['handler']['handle']>[2]): Promise<Response> {
+        const m = /^\/r\/([^/]+)(\/.*)?$/.exec(path)
+        if (m == null) return new Response('not found', { status: 404 })
+        const name = decodeURIComponent(m[1]!)
+        const rest = m[2]
+        if (rest == null) return Response.redirect(`${hubBase(name)}/${new URL(req.url).search}`, 308)
+        const e = this.entries.get(name)
+        if (e == null) return new Response(`not a house repo: ${name}`, { status: 404 })
+        await e.loading
+        if (e.rt == null) return new Response(`${name}'s hub is ${e.status}${e.note != null ? `: ${e.note}` : ''}`, { status: 409 })
+        return e.rt.handler.handle(req, rest, srv)
+    }
+
+    /** one pass: logs stay capped, an edited config reloads its hub, and the
+     *  ACTIVE repos get their RED ping every PING_EVERY_MS */
+    async tick(active: Set<string>): Promise<void> {
+        for (const e of this.entries.values()) {
+            capLog(hubLog(this.o.dir, e.repo.name))
+            this.reloadIfEdited(e)
+        }
+        const now = this.now()
+        const up = [...this.entries.values()].filter((e) => e.rt != null && active.has(e.repo.name))
+        if (now - this.lastPing >= PING_EVERY_MS) {
+            this.lastPing = now
+            for (const e of up) await e.rt?.ping()
+        }
+    }
+
+    /** its config moved since it loaded: reload it with the config read
+     *  fresh, its processes left running for the new load to adopt. A gate in
+     *  flight defers it to a later tick */
+    private reloadIfEdited(e: Entry): void {
+        if (e.loading != null || e.held) return
+        const now = configStamp(e.repo.path)
+        if (now === e.stamp || now === '') return
+        // a hub that crashed on its config gets its next try from the edit
+        if (e.rt == null) {
+            if (e.status !== 'crashed') return
+            this.io(e).print(`ok: ${e.repo.name}'s repo.config.ts changed: loading its hub again`)
+            void this.schedule(e, true)
+            return
+        }
+        if (e.rt.busy()) return
+        this.io(e).print(`ok: ${e.repo.name}'s repo.config.ts changed: reloading its hub`)
+        e.rt.stop()
+        e.rt = null
+        void this.schedule(e, true)
+    }
+
+    /** a run is in flight in some hub */
+    busy(): boolean {
+        for (const e of this.entries.values()) if (e.rt?.busy() === true) return true
+        return false
+    }
+
+    /** the repos it knows, loaded or not */
+    names(): string[] {
+        return [...this.entries.keys()]
+    }
+
+    private view(e: Entry): WorkerView {
+        const blocked = hubBlocker(e.repo.path) ?? (e.status === 'crashed' && notInstalled(e.repo.path) ? NOT_INSTALLED : null)
+        return {
+            id: e.repo.name,
+            repo: e.repo.name,
+            status: e.status,
+            pid: e.rt != null ? process.pid : null,
+            since: e.since,
+            note: blocked != null && e.note === blocked ? null : e.note,
+            port: this.o.port,
+            url: `${hubBase(e.repo.name)}/`,
+            blocked,
+            tail: e.status === 'up' ? [] : tailLines(hubLog(this.o.dir, e.repo.name), 30),
+            uses: e.rt?.uses ?? [],
+        }
+    }
+
+    views(repos: WiredRepo[]): WorkerView[] {
+        return repos.map((r) => this.view(this.entry(r)))
+    }
+
+    /** every hub stops, its processes left running for the next home to adopt */
+    stopAll(): void {
+        for (const e of this.entries.values()) e.rt?.stop()
+    }
+}