rvlib-shipkit 1.1.0 → 1.2.0

package/src/serve/serve-hub.ts

@@ -1,8 +1,9 @@
-// shipkit serve — the repo's ONE Bun.serve, serving the ONE page (one server per repo, one surface, mobx+react). `/` is
-// the hub app (Bun HTML import — media studio + asks + creds + posts +
-// health + wikis as sections); the studio route table mounts as the media
-// API under /media/*; graph canvases stay as drill-down pages. Route logic
-// only — resolving WHAT to mount from repo.config is run-serve.ts's job.
+// the hub's routes: ONE page (the hub app, a Bun HTML import: media studio,
+// asks, creds, posts, health, wikis as sections), the studio route table as
+// the media API under /media/*, graph canvases as drill-down pages. hubHandler
+// is the routing alone, under a base path; serveHub puts it behind a
+// Bun.serve of its own. Resolving WHAT to mount from repo.config is
+// hub-runtime.ts's job.
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { positionsFile } from 'rvlib-shipkit/src/wiki/graph-positions.ts'
@@ -21,19 +22,23 @@ import type { TestCheckView, TestsRootView } from '../collections/test-time.ts'
 import type { LiveView } from '../ledger/live-timeline.ts'
 
 export type { LiveView }
-import type { HealthSchedule } from './health-schedule.ts'
+import type { PlanRow } from '../plan/planner.ts'
 import type { HubProblems } from './hub-problems.ts'
 import hubIndex from './hub-app/index.html'
+import { homePort, homeUp } from '../home/home-paths.ts'
+import { RUN_EXIT } from '../home/home-words.ts'
+import type { RepoProcesses } from './repo-processes.ts'
 import { projectGutter } from './project-gutter-route.ts'
 import { sameOrigin } from './same-origin.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { WarmCell } from './warm-cell.ts'
 
 export { sameOrigin }
 
 export type HubTool = { path: string; label: string; desc: string }
 
 /** what a running gate streams back to the page */
-export type CheckTap = { line: (l: string) => void; check: (e: CheckEvent) => void }
+export type CheckTap = { line: (l: string) => void; check: (e: CheckEvent) => void; job?: (id: string) => void }
 /** the comfy panel, as the hub needs it: the child process it embeds and the
  *  box those workflows generate on (src/comfy/comfy-panel.ts owns both) */
 export type ComfyDeps = {
@@ -45,6 +50,12 @@ export type ComfyDeps = {
 export type HubDeps = {
     root: string
     name: string
+    /** the machine resources the repo declares in serve.uses */
+    uses?: string[]
+    /** the long running processes the repo declares in serve.processes */
+    processes?: RepoProcesses
+    /** a terminal's `shipkit ci` or `check`, run in this process; resolves to its exit code */
+    runCli?: (kind: 'ci' | 'check', opts: Record<string, unknown>, print: (l: string) => void) => Promise<number>
     /** 0 = random (tests); real launches pass repo.config/default */
     port: number
     /** every md graph this hub serves, in card order: /graph/<id>. run-serve
@@ -62,9 +73,12 @@ export type HubDeps = {
      *  into a tree someone is editing. run-serve owns the routing between the
      *  two engines. */
     runChecks: (tap: CheckTap, o?: { only?: string[]; gate?: boolean; by?: InvokedBy; auto?: boolean }) => Promise<number>
-    /** the daily health pass timer (health-schedule.ts). The page reads its
-     *  state to say when a health check runs next; absent = no timer */
-    schedule?: HealthSchedule | null
+    /** this repo's rows of the plan (plan/planner.ts): the page reads them to
+     *  say when a check runs next and why; absent = no plan */
+    planned?: () => PlanRow[]
+    /** a click: this check runs next, through the plan. false = the plan
+     *  does not know it */
+    ask?: (check: string) => boolean
     /** every run on record, shaped for the timeline page. Absent = the page
      *  says there is no record rather than drawing an empty one */
     timeline?: () => Promise<Timeline>
@@ -99,11 +113,40 @@ export type HubDeps = {
      *  file, so every surface built on the config asks for this first, or a
      *  toggle reads as a toggle that did nothing until the next restart */
     refresh?: () => Promise<void>
-    /** RED-only ping tick, called on an interval while serving (null = off) */
+    /** a cheap fingerprint of what the rows and the run record read (file
+     *  stats): a new one marks the warm answers stale. Absent = only a save
+     *  and their age refresh them */
+    stamp?: () => string
+    /** RED-only ping tick, called on an interval by the hub runtime (null = off) */
     pingTick?: ((needs: NeedItem[]) => void) | null
 }
 export type Hub = { server: ReturnType<typeof Bun.serve>; tools: HubTool[]; liveReload: boolean; stop: () => void }
 
+/** one repo's request handling, apart from any server: `shipkit serve` puts it
+ *  behind a Bun.serve of its own, the home behind /r/<repo>/ of its one */
+export type HubHandler = {
+    tools: HubTool[]
+    /** a request whose path is relative to the hub's base ('/api/…', '/hub.json') */
+    handle: (req: Request, path: string, srv: Server) => Promise<Response>
+    /** a tracked file of the repo moved: every warm answer recomputes behind */
+    invalidate: () => void
+    /** compute the warm answers now, the rows first: the hub's load */
+    warm: () => Promise<void>
+    stop: () => void
+}
+
+/** past this age a warm answer recomputes in the background even when no
+ *  save and no stamp said it moved: what no watch sees (a clock, a wiki in
+ *  another repo, a file git ignores). Long, because a recompute holds the
+ *  one process every repo answers from */
+export const WARM_MAX_AGE_MS = 120_000
+
+/** the one flat list of the repo, as /api/resources.json carries it before
+ *  the plan rows and the hub problems, which are read live */
+type Rows = { collections: { id: string; title: string; media: string }[]; resources: Awaited<ReturnType<typeof projectResources>> }
+type Server = ReturnType<typeof Bun.serve>
+type Gutter = ReturnType<typeof projectGutter>
+
 /** the tab refreshes ITSELF through bun's hot reload client, which rides in
  *  the served page: it swaps a hub-app edit in, and reconnects across the
  *  process restart a source edit triggers under `bun --watch`. Bun puts that
@@ -124,27 +167,79 @@ export function hubTools(d: Pick<HubDeps, 'graphs'>): HubTool[] {
 }
 
 // drill-down pages (graph canvases) get one fixed home link back to THE page
-const HOME_LINK = `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
- background:#141619;border:1px solid #282c31;border-radius:3px;padding:5px 9px}</style><a class=skhome href="/" title="hub — THE page">⌂</a>`
-const withHome = (html: string): string => html.replace(/<body([^>]*)>/, `<body$1>${HOME_LINK}`)
+const homeLink = (base: string): string => `<style>.skhome{position:fixed;left:10px;top:10px;z-index:9999;font-size:17px;text-decoration:none;
+ background:#141619;border:1px solid #282c31;border-radius:3px;padding:5px 9px}</style><a class=skhome href="${base}/" title="hub — THE page">⌂</a>`
+const withHome = (html: string, base: string): string => html.replace(/<body([^>]*)>/, `<body$1>${homeLink(base)}`)
 
-export function serveHub(d: HubDeps): Hub {
+/** the hub's routes under `base` ('' on a server of its own, '/r/<repo>' in
+ *  the home). `projects` is the rail, shared when one process serves many */
+export function hubHandler(d: HubDeps, o: { base?: string; projects?: Gutter } = {}): HubHandler {
+    const base = o.base ?? ''
     const tools = hubTools(d)
-    const projects = projectGutter({ root: d.root })
-    const server: ReturnType<typeof Bun.serve> = Bun.serve({
-        hostname: '127.0.0.1',
-        port: d.port,
-        // `/` IS the page — the react app; there is no other surface
-        routes: { '/': hubIndex },
-        async fetch(req): Promise<Response> {
-            const path = new URL(req.url).pathname
+    const projects = o.projects ?? projectGutter({ root: d.root })
+    // the answers a page waits on when a repo shows, kept warm in memory: a
+    // request answers from here and never walks the repo (warm-cell.ts)
+    const warmOpts = { stamp: d.stamp, maxAgeMs: WARM_MAX_AGE_MS }
+    const rows = new WarmCell<Rows>(async () => {
+        await d.refresh?.()
+        const cols = d.collections()
+        return { collections: cols.map((c) => ({ id: c.id, title: c.title, media: c.media })), resources: await projectResources(cols, d.hubProblems?.collector) }
+    }, warmOpts)
+    // the run record and the config are all it reads, and the stamp sees both
+    const timeline = d.timeline == null ? null : new WarmCell(d.timeline, { stamp: d.stamp })
+    const graphs = new Map(d.graphs.map((g) => [g.id, new WarmCell(async () => g.load(), { maxAgeMs: WARM_MAX_AGE_MS })]))
+    const fresh = (req: Request): boolean => new URL(req.url).searchParams.get('fresh') === '1'
+    return {
+        tools,
+        invalidate: () => {
+            rows.invalidate()
+            timeline?.invalidate()
+            for (const g of graphs.values()) g.invalidate()
+        },
+        warm: async () => {
+            await rows.warm()
+            await timeline?.warm()
+            for (const g of graphs.values()) await g.warm()
+        },
+        stop: () => { d.comfy?.stop() },
+        async handle(req, path, srv): Promise<Response> {
             if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the hub page', { status: 403 })
             // identity probe: lets a second launch tell "same repo, another
             // window" from "a DIFFERENT repo hashed onto my port"
             // `root` rides with it so a page can put a file link into his
             // editor: only the server knows where this repo sits on disk
-            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, root: d.root, tools })
+            // `uses` tells the home which machine resources this repo needs,
+            // `base` where this hub's page sits on the server that answers
+            if (path === '/hub.json') return Response.json({ hub: 'shipkit', name: d.name, root: d.root, base, tools, uses: d.uses ?? [] })
             if (path.startsWith('/api/projects')) return (await projects.handle(req, path)) ?? new Response('not found', { status: 404 })
+            // where the machine's home serves, and whether it does: a rail
+            // click opens the home on that repo, or VS Code while none runs
+            if (path === '/api/home-url') return Response.json({ port: homePort(), up: await homeUp() })
+            if (path === '/api/run' && req.method === 'POST' && d.runCli != null) {
+                const b = (await req.json().catch(() => ({}))) as { kind?: string; opts?: Record<string, unknown> }
+                if (b.kind !== 'ci' && b.kind !== 'check') return new Response('kind must be ci or check', { status: 400 })
+                const runCli = d.runCli
+                // a gate can stay silent for minutes (queued, or one long tsc):
+                // Bun would cut the connection after its idle timeout
+                srv.timeout(req, 0)
+                // wire lines as they come, then one EXIT line the client ends on
+                const stream = new ReadableStream<string>({
+                    start(ctl) {
+                        const put = (l: string): void => { try { ctl.enqueue(`${l}\n`) } catch { /* the terminal went away: the run finishes anyway */ } }
+                        void runCli(b.kind as 'ci' | 'check', b.opts ?? {}, put)
+                            .then((code) => put(`${RUN_EXIT}${code}`), (e: Error) => { put(`FAIL: ${e.message}`); put(`${RUN_EXIT}1`) })
+                            .finally(() => { try { ctl.close() } catch { /* closed */ } })
+                    },
+                })
+                return new Response(stream, { headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } })
+            }
+            if (path === '/api/processes.json') return Response.json({ processes: d.processes?.views() ?? [] })
+            if (path === '/api/processes/act' && req.method === 'POST') {
+                const b = (await req.json().catch(() => ({}))) as { id?: string; act?: string }
+                if (b.act !== 'start' && b.act !== 'stop' && b.act !== 'restart') return new Response('act must be start, stop or restart', { status: 400 })
+                const v = d.processes?.act(b.id ?? '', b.act)
+                return v == null ? new Response(`no process '${b.id ?? ''}' in serve.processes`, { status: 404 }) : Response.json(v)
+            }
             // the three surfaces built on the config read the config on disk
             if (path === '/api/needs.json' || path === '/api/resources.json' || path === '/api/checks.json' || path === '/api/collections.json') await d.refresh?.()
             if (path === '/api/needs.json') {
@@ -155,11 +250,11 @@ export function serveHub(d: HubDeps): Hub {
                 // ONE flat list for the whole repo: the page groups it by
                 // path and by type, and a second endpoint would be a second
                 // answer to drift from this one
-                const cols = d.collections()
+                const r = await rows.get({ fresh: fresh(req) })
                 return Response.json({
-                    collections: cols.map((c) => ({ id: c.id, title: c.title, media: c.media })),
-                    resources: await projectResources(cols, d.hubProblems?.collector),
-                    schedule: d.schedule?.state() ?? null,
+                    collections: r.collections,
+                    resources: r.resources,
+                    planned: d.planned?.() ?? null,
                     hub: d.hubProblems?.list() ?? [],
                 })
             }
@@ -236,9 +331,9 @@ export function serveHub(d: HubDeps): Hub {
                 return Response.json({ url: d.repoHub == null ? null : await d.repoHub(repo) })
             }
             if (path === '/api/timeline.json') {
-                if (d.timeline == null) return new Response('this hub keeps no run record', { status: 404 })
+                if (timeline == null) return new Response('this hub keeps no run record', { status: 404 })
                 try {
-                    return Response.json(await d.timeline())
+                    return Response.json(await timeline.get({ fresh: fresh(req) }))
                 } catch (e) {
                     return new Response(`the run record could not be shaped: ${(e as Error).message}`, { status: 500 })
                 }
@@ -319,30 +414,33 @@ export function serveHub(d: HubDeps): Hub {
                 })
                 return new Response(stream, { headers: { 'content-type': 'application/x-ndjson; charset=utf-8', 'cache-control': 'no-store' } })
             }
-            const page = (s: string): Response => new Response(withHome(s), { headers: { 'content-type': 'text/html; charset=utf-8' } })
+            const page = (s: string): Response => new Response(withHome(s, base), { headers: { 'content-type': 'text/html; charset=utf-8' } })
             for (const g of d.graphs) {
                 if (!path.startsWith(`/graph/${g.id}`)) continue
-                const routes = graphRoutes({ load: g.load, title: g.title, file: positionsFile(d.root, g.id), saveUrl: `/graph/${g.id}/positions` })
+                // the graph as the warm cell holds it: a page open never rescans the wiki
+                const held = await graphs.get(g.id)!.get()
+                const routes = graphRoutes({ load: () => held, title: g.title, file: positionsFile(d.root, g.id), saveUrl: `${base}/graph/${g.id}/positions` })
                 if (path === `/graph/${g.id}`) return page(routes.page())
-                if (path === `/graph/${g.id}/graph.json`) return Response.json(g.load())
+                if (path === `/graph/${g.id}/graph.json`) return Response.json(held)
                 if (path === `/graph/${g.id}/positions`) return routes.save(req)
             }
             // the media API namespace — the studio route table, ONE prefix strip
             if (d.studio != null && path.startsWith('/media/')) return d.studio.handle(req, path.slice('/media'.length))
             // stale bookmarks (/assets/, /status, …) land here — name the way home
-            return new Response('not found — the hub page is at /', { status: 404 })
+            return new Response(`not found — the hub page is at ${base}/`, { status: 404 })
         },
-    })
-    // RED-only pings ride the serving process: one tick now (state file
-    // guarantees a restart never re-fires), then every minute
-    let pingTimer: ReturnType<typeof setInterval> | null = null
-    if (d.pingTick != null) {
-        // tick failures are LOUD (console = the serve terminal), never swallowed
-        const tick = (): void => void d.needs().then((n) => d.pingTick?.(n)).catch((e: Error) => console.error(`WARN ping tick broke: ${e.message}`))
-        tick()
-        pingTimer = setInterval(tick, 60_000)
     }
+}
+
+export function serveHub(d: HubDeps, h: HubHandler = hubHandler(d)): Hub {
+    const server: Server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: d.port,
+        // `/` IS the page — the react app; there is no other surface
+        routes: { '/': hubIndex },
+        fetch: (req, srv) => h.handle(req, new URL(req.url).pathname, srv),
+    })
     // the panel process belongs to this hub: leaving it behind means the next
     // launch adopts a server holding the previous run's modules
-    return { server, tools, liveReload: canLiveReload(), stop: () => { if (pingTimer != null) clearInterval(pingTimer); d.schedule?.stop(); d.comfy?.stop(); server.stop(true) } }
+    return { server, tools: h.tools, liveReload: canLiveReload(), stop: () => { h.stop(); server.stop(true) } }
 }

package/src/serve/stale-restart.ts

@@ -20,6 +20,9 @@ export type StaleRestartOpts = {
     /** why the file table leaked, null while it did not. Default: this
      *  process's own table (core/fd-table.ts) */
     leak?: () => string | null
+    /** one line on source that moved under a process with no bun watch, null
+     *  while nothing moved */
+    moved?: () => string | null
     /** a run is in flight: a restart now would kill it */
     busy: () => boolean
     /** never returns when it works. `why` is one line on what went stale */
@@ -62,6 +65,8 @@ export class StaleRestart {
         const disk = this.o.disk()
         // a package.json half written by a bump reads as `?`, and is no verdict
         if (disk !== '?' && disk !== this.o.boot) return { why: `this hub runs shipkit ${this.o.boot} but ${disk} is on disk`, leak: false }
+        const moved = this.o.moved?.() ?? null
+        if (moved != null) return { why: moved, leak: false }
         const leak = (this.o.leak ?? fdTableLeak)()
         return leak == null ? null : { why: leak, leak: true }
     }

package/src/serve/{gate-trigger.ts → tracked-watch.ts}

@@ -1,72 +1,12 @@
-// when the hub runs the quick gate on its own: once at start, then after the
-// tracked files have been quiet for QUIET_MS. The trigger only STARTS ordinary
-// gate runs. Every answer comes out of the one runner, measured or replayed
-// from the ledger like any other run, so nothing here owns a verdict: a missed
-// file event costs a stale problems pane until the next save, never a green.
-//
-// never two runs at once: a request during a run queues exactly one more, run
-// after it ends, however many saves landed meanwhile.
+// the save watch: which files moving under a repo count as the owner's edit.
+// It only says THAT something moved; the plan (plan/planner.ts) then asks the
+// ledger which checks that moved, so a missed file event costs a stale
+// problems pane until the next save, never a green.
 import { watch, type FSWatcher } from 'fs'
 import { GENERATED_IGNORE_LINES } from '../rules/untrack-generated.ts'
 import { gitBin } from '../core/git-bin.ts'
 import { LAYOUT } from '../core/layout.ts'
 
-export const QUIET_MS = 2000
-
-export type Timers = {
-    set: (fn: () => void, ms: number) => unknown
-    clear: (handle: unknown) => void
-}
-
-const realTimers: Timers = {
-    set: (fn, ms) => setTimeout(fn, ms),
-    clear: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
-}
-
-export class GateTrigger {
-    private timer: unknown = null
-    private running: Promise<void> | null = null
-    private pending = false
-    private readonly timers: Timers
-    private readonly quietMs: number
-
-    constructor(private readonly o: { run: () => Promise<unknown>; quietMs?: number; timers?: Timers; onError?: (e: Error) => void }) {
-        this.timers = o.timers ?? realTimers
-        this.quietMs = o.quietMs ?? QUIET_MS
-    }
-
-    /** a tracked file moved: the run starts once nothing has moved for the
-     *  quiet window, so a save burst is one run */
-    touched(): void {
-        if (this.timer != null) this.timers.clear(this.timer)
-        this.timer = this.timers.set(() => {
-            this.timer = null
-            this.request()
-        }, this.quietMs)
-    }
-
-    /** run now, or once more after the run in flight */
-    request(): void {
-        if (this.running != null) { this.pending = true; return }
-        this.running = (async () => {
-            do {
-                this.pending = false
-                try { await this.o.run() } catch (e) { this.o.onError?.(e instanceof Error ? e : new Error(String(e))) }
-            } while (this.pending)
-        })().finally(() => { this.running = null })
-    }
-
-    /** resolves when no run is in flight or queued */
-    async idle(): Promise<void> {
-        while (this.running != null) await this.running
-    }
-
-    stop(): void {
-        if (this.timer != null) this.timers.clear(this.timer)
-        this.timer = null
-    }
-}
-
 /** every path a run of the gate or the hub itself writes, whatever the repo
  *  ignores: the status files, the per run logs under the scratch dir, an atomic write's
  *  temp file, the comfy state the hub writes at boot. A save there is the

package/src/serve/warm-cell.ts

@@ -0,0 +1,95 @@
+// one answer of a hub kept warm in memory: computed when the hub loads,
+// recomputed in the background when something says it moved (a save, a
+// stamp, its age), and served from memory. A request never pays for the
+// walk behind it, except the very first one and one that asks for `fresh`.
+//
+// the one constraint a reader breaks first: `get()` answers what is in
+// memory even when it is known stale. Whoever just changed the truth (an
+// act, the end of a run) asks for `fresh`, which waits on a compute that
+// started after its call.
+
+export type WarmCellOpts = {
+    /** a cheap fingerprint of what the answer reads (file stats): a new one
+     *  marks the answer stale */
+    stamp?: () => string
+    /** past this age the answer is recomputed in the background even when
+     *  nothing said it moved: what no watch sees (a clock, another repo) */
+    maxAgeMs?: number
+    now?: () => number
+}
+
+export class WarmCell<T> {
+    private value: { v: T; at: number; stamp: string } | null = null
+    private running: Promise<T> | null = null
+    /** bumped by invalidate: a compute that started before it is stale */
+    private gen = 0
+    private runGen = -1
+
+    constructor(private readonly compute: () => Promise<T>, private readonly o: WarmCellOpts = {}) {}
+
+    private now(): number {
+        return this.o.now?.() ?? Date.now()
+    }
+
+    /** a compute, shared by every caller while it runs */
+    private run(): Promise<T> {
+        if (this.running != null) return this.running
+        const gen = this.gen
+        const stamp = this.o.stamp?.() ?? ''
+        this.runGen = gen
+        const p = (async (): Promise<T> => {
+            try {
+                // never synchronously: `running` is set before this settles
+                const v = await Promise.resolve().then(() => this.compute())
+                this.value = { v, at: this.now(), stamp }
+                return v
+            } finally {
+                this.running = null
+                // what said it moved while this ran is not in this answer
+                if (this.gen !== gen) this.kick()
+            }
+        })()
+        this.running = p
+        return p
+    }
+
+    /** a compute in the background: on a failure the last answer stays */
+    private kick(): void {
+        void this.run().catch(() => {})
+    }
+
+    get stale(): boolean {
+        const v = this.value
+        if (v == null) return true
+        if (this.o.maxAgeMs != null && this.now() - v.at > this.o.maxAgeMs) return true
+        return this.o.stamp != null && this.o.stamp() !== v.stamp
+    }
+
+    /** the answer in memory, a stale one kicking a recompute behind it. With
+     *  nothing in memory yet, or `fresh`, it waits on a compute */
+    async get(o: { fresh?: boolean } = {}): Promise<T> {
+        if (o.fresh === true) {
+            // a compute that started before this call may miss what the
+            // caller just changed: wait for it, then for one of our own
+            if (this.running != null) await this.running.catch(() => {})
+            return this.run()
+        }
+        const v = this.value
+        // nothing in memory, a failed compute included: wait on a new one
+        if (v == null) return this.run()
+        if (this.running == null && (this.stale || this.gen !== this.runGen)) this.kick()
+        return v.v
+    }
+
+    /** something this answer reads moved: recompute in the background */
+    invalidate(): void {
+        this.gen++
+        if (this.running == null) this.kick()
+    }
+
+    /** compute now unless an answer is already in memory: the hub's load */
+    async warm(): Promise<void> {
+        if (this.value != null) return
+        await this.run().catch(() => {})
+    }
+}

package/src/shipkit-files.ts

@@ -0,0 +1,114 @@
+// THE `<name>.shipkit.ts` file: a repo drops one anywhere and default-exports
+// what it declares, and the kind says who reads it.
+//
+//   check({...})          a gate check, read by discovery like a `.check.ts`
+//   globalProcess({...})  a long running process for the whole machine: pm
+//                         supervises it, the home page switches it
+//   widget({...})         html the daemon renders every few seconds, mounted
+//                         on the home page
+//
+// the one constraint a reader breaks first: every kind is IMPORTED by the
+// process that reads it (discovery, pm's config child, the daemon), so a file
+// keeps its top level cheap and puts heavy work inside a function.
+import { check, type CheckDef } from './check.ts'
+
+export { check }
+
+/** one button beside a global process: a command, or a function of the file */
+export type ProcessAction = {
+    /** the words on the button */
+    label: string
+    /** argv, run from the repo root, output appended to the process log */
+    cmd?: string[]
+    /** a function run in its own bun process that imports this file, from
+     *  the repo root. Its output lands in the process log too */
+    run?: () => void | Promise<void>
+}
+
+export type GlobalProcessDef = {
+    /** kebab-case, unique on the machine: what a repo names in `serve.uses` */
+    id: string
+    /** the name on the switch (default the id) */
+    label?: string
+    /** one line: what it is for */
+    description?: string
+    /** the machine it runs on, as a hint beside the switch */
+    where?: string
+    /** argv, run from the repo root (or `cwd`). Without `down` it IS the
+     *  service: pm keeps it running, restarts it on a crash, signals it on
+     *  stop. With `down` it is a bring-up that exits once the service answers */
+    cmd: string[]
+    /** argv that takes a bring-up down again. Absent: `cmd` is the service */
+    down?: string[]
+    /** where both run, repo-relative (default the repo root) */
+    cwd?: string
+    /** the url it serves: shown as a link, probed when `probe` is absent */
+    url?: string
+    /** an http url that answers 2xx while it is up (default `url`). A
+     *  bring-up needs one of the two: its probe is the only truth */
+    probe?: string
+    /** a button each beside the switch, by key */
+    actions?: Record<string, ProcessAction>
+    /** with `url`: open it as a shipkit app window. Starting it from the
+     *  page opens that window once it answers, in one go */
+    app?: boolean
+}
+
+export type WidgetDef = {
+    /** kebab-case, unique in its repo */
+    id: string
+    /** the heading over it (default the id) */
+    title?: string
+    /** how often the daemon renders it again (default 5000, at least 1000) */
+    everyMs?: number
+    /** the html it shows, rendered in the daemon. A throw shows as its error */
+    render: () => string | Promise<string>
+}
+
+export type GlobalProcessUnit = GlobalProcessDef & { kind: 'globalProcess' }
+export type WidgetUnit = WidgetDef & { kind: 'widget' }
+
+export const UNIT_KINDS = ['globalProcess', 'widget'] as const
+
+const KEBAB = /^[a-z0-9][a-z0-9-]*$/
+const words = (v: unknown): boolean => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')
+const httpUrl = (v: unknown): boolean => typeof v === 'string' && /^https?:\/\//.test(v)
+
+/** why a global process declaration cannot run, or null */
+export function globalProcessProblem(d: GlobalProcessDef): string | null {
+    const at = `globalProcess '${String(d.id)}'`
+    if (!KEBAB.test(d.id ?? '')) return `${at}: id must be kebab-case`
+    if (!words(d.cmd)) return `${at}: cmd is a list of words`
+    if (d.down != null && !words(d.down)) return `${at}: down is a list of words`
+    if (d.url != null && !httpUrl(d.url)) return `${at}: url must be an http url`
+    if (d.probe != null && !httpUrl(d.probe)) return `${at}: probe must be an http url`
+    if (d.down != null && d.probe == null && d.url == null) return `${at}: a bring-up (one with down) needs probe or url, the only truth of whether it is up`
+    if (d.app === true && d.url == null) return `${at}: app needs a url to open`
+    for (const [k, a] of Object.entries(d.actions ?? {})) {
+        if (!KEBAB.test(k)) return `${at}: action '${k}' must be kebab-case`
+        if ((a.cmd != null) === (a.run != null)) return `${at}: action '${k}' declares exactly one of cmd or run`
+        if (a.cmd != null && !words(a.cmd)) return `${at}: action '${k}'.cmd is a list of words`
+    }
+    return null
+}
+
+export function globalProcess(d: GlobalProcessDef): GlobalProcessUnit {
+    const why = globalProcessProblem(d)
+    if (why != null) throw new Error(why)
+    return { ...d, kind: 'globalProcess' }
+}
+
+export function widget(d: WidgetDef): WidgetUnit {
+    if (!KEBAB.test(d.id ?? '')) throw new Error(`widget '${String(d.id)}': id must be kebab-case`)
+    if (typeof d.render !== 'function') throw new Error(`widget '${d.id}': render is a function returning html`)
+    if (d.everyMs != null && !(d.everyMs >= 1000)) throw new Error(`widget '${d.id}': everyMs is at least 1000`)
+    return { ...d, kind: 'widget' }
+}
+
+/** the kind a default export says it is: a unit, else a check */
+export function unitKind(d: unknown): 'globalProcess' | 'widget' | 'check' {
+    const k = (d as { kind?: unknown } | null)?.kind
+    return k === 'globalProcess' || k === 'widget' ? k : 'check'
+}
+
+export type { CheckDef }

package/src/shipkit.ts

@@ -15,7 +15,8 @@ export { contractsConfigFrom, activeContracts, applyContractsResult } from './co
 export { serveHub, hubTools } from './serve/serve-hub.ts'
 export type { Hub, HubDeps, HubTool } from './serve/serve-hub.ts'
 export type { GraphMount } from './wiki/graph-mount.ts'
-export { runServe, resolveHubDeps, defaultHubPort, baseWikiRoot } from './serve/run-serve.ts'
+export { runServe } from './serve/run-serve.ts'
+export { resolveHubDeps, defaultHubPort, baseWikiRoot, loadHub } from './serve/hub-runtime.ts'
 export { projectNeeds, redCount } from './collections/collection-types.ts'
 export type { Collection, Instance, NeedItem, NeedSeverity, CurationVerb } from './collections/collection-types.ts'
 export { buildCollections } from './collections/providers.ts'

package/src/suite/kept-timings.ts

@@ -15,7 +15,7 @@
 import { copyFileSync, mkdirSync, readFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { atomicWrite } from '../core/locked-write.ts'
-import { shipkitRoot } from '../ledger/store.ts'
+import { shipkitRoot } from '../ledger/db.ts'
 
 /** where a unit's durations live, beside everything else the repo remembers */
 export const timingsHome = (root: string, unit: string): string => join(shipkitRoot(root), 'suite-timings', `${unit === '' ? 'root' : unit}.json`)

package/src/wiki/graph-positions.ts

@@ -4,7 +4,7 @@
 import { mkdirSync, readFileSync } from 'fs'
 import { dirname, join } from 'path'
 import { atomicWrite } from '../core/locked-write.ts'
-import { shipkitRoot } from '../ledger/store.ts'
+import { shipkitRoot } from '../ledger/db.ts'
 import type { MdGraph } from './md-graph.ts'
 
 export type Positions = Record<string, [number, number]>