rvlib-shipkit 1.1.1 → 1.3.0

package/src/serve/other-repos.ts

@@ -1,16 +1,11 @@
-// The OTHER house repos on this disk, as the live strip reads them: their
-// runs in flight from their own run record, read only, and their hub url
-// when one serves. Which repos count is houseRepos (project-gutter.ts), the
-// same discovery the project gutter lists, minus this repo.
-//
-// Cheap on purpose, because the strip asks every second: the list is read at
-// most every LIST_TTL_MS, and a repo's record is opened only when its file or
-// its write ahead log moved since the last read.
-import { existsSync, realpathSync } from 'fs'
+// The OTHER house repos on this disk, as a hub serving on its own lists them
+// for the dock (house-runs.ts). Which repos count is houseRepos
+// (project-gutter.ts), the same discovery the project gutter lists, minus
+// this repo. The list is read at most every LIST_TTL_MS, since the dock asks
+// every few seconds.
+import { realpathSync } from 'fs'
 import { homedir } from 'os'
-import type { LiveRow } from '../ledger/live-runs.ts'
-import { readLiveReadonly } from '../ledger/run-log.ts'
-import { houseRepos, hubPortOf, recordOf, recordStamp, type WiredRepo } from './project-gutter.ts'
+import { houseRepos, type WiredRepo } from './project-gutter.ts'
 
 /** how long the list of repos is trusted before the dev root is read again */
 export const LIST_TTL_MS = 30_000
@@ -30,11 +25,10 @@ export function otherHouseRepos(root: string, userHome: string = homedir()): Wir
     return repos.filter((r) => real(r.path) !== me)
 }
 
-/** the other repos and their live rows, re-read only when something moved */
+/** the other repos, the list re-read at most every LIST_TTL_MS */
 export class OtherRepos {
     private list: WiredRepo[] = []
     private listedAt = -Infinity
-    private rows = new Map<string, { stamp: string; rows: LiveRow[] }>()
 
     constructor(private root: string, private now: () => number = Date.now, private userHome: string = homedir()) {}
 
@@ -45,35 +39,4 @@ export class OtherRepos {
         }
         return this.list
     }
-
-    /** every repo's live rows, as its record holds them */
-    read(): { repo: string; rows: LiveRow[] }[] {
-        const out: { repo: string; rows: LiveRow[] }[] = []
-        for (const r of this.repos()) {
-            const path = recordOf(r.path)
-            if (path == null || !existsSync(path)) continue
-            const stamp = recordStamp(path)
-            let hit = this.rows.get(r.path)
-            if (hit == null || hit.stamp !== stamp) {
-                hit = { stamp, rows: readLiveReadonly(path) }
-                this.rows.set(r.path, hit)
-            }
-            out.push({ repo: r.name, rows: hit.rows })
-        }
-        return out
-    }
-
-    /** a repo's hub url when it serves, checked by asking it who it is */
-    async hubOf(repo: string): Promise<string | null> {
-        const r = this.repos().find((x) => x.name === repo)
-        if (r == null) return null
-        const url = `http://localhost:${hubPortOf(r.path)}`
-        try {
-            const res = await fetch(`${url}/hub.json`, { signal: AbortSignal.timeout(500) })
-            const j = (await res.json()) as { hub?: string; root?: string }
-            return j.hub === 'shipkit' && j.root != null && real(j.root) === real(r.path) ? url : null
-        } catch {
-            return null
-        }
-    }
 }

package/src/serve/project-gutter-route.ts

@@ -5,20 +5,23 @@
 // the index moved, a few repos per poll, and a repo's run record is opened
 // only when it moved, so a steady poll spawns ps and lsof and nothing else. The icon route
 // serves only the icon files a discovered repo carries, and POST
-// /api/projects/open opens a discovered repo in VS Code: a request names a
-// repo, never a path. The rail ORDER is one text file for the whole machine
+// /api/projects/open opens a discovered repo in VS Code, POST
+// /api/projects/fork in Fork: a request names a repo, never a path. The rail ORDER is one text file for the whole machine
 // (ORDER_FILE), so every hub shows the same order and a hand edit is seen
 // within one poll; POST /api/projects/order writes it.
-import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'fs'
 import { readFile, stat } from 'fs/promises'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import {
-    asksDirOf, branchOf, countSessions, descriptionOf, dirtyCount, gateOf, gitStamp, houseRepos, iconStamp, ICON_TYPES, lastActivity,
+    asksDirOf, branchOf, countSessions, descriptionOf, dirtyCount, gateFrom, checkStateOf, gitStamp, houseRepos, iconStamp, ICON_TYPES, lastActivity,
     lastRunAt, lastSessionAt, liveUrlOf, mergeOrder, openAsks, openFolders, parseClaudePids, parseDescribe, parseLsofCwd, parseOrder,
-    recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type Gate, type WiredRepo,
+    recordOf, recordStamp, RELEASE_TAGS, renderOrder, versionOf, vscodeStoragePath, type CheckState, type Gate, type LastRow, type WiredRepo,
 } from './project-gutter.ts'
 import { readLastStatusReadonly } from '../ledger/run-log.ts'
+import { identityOfText, identityProblem, type Identity } from '../core/identity-color.ts'
+import { writeIdentity } from '../core/identity.ts'
+import { writeArchived } from '../core/archived.ts'
 
 export type { Gate }
 
@@ -60,14 +63,23 @@ export type ProjectRow = {
     dirty: number | null
     /** the last gate its own run record holds */
     gate: Gate
+    /** every check's last outcome as one colour, warnings included */
+    checks: CheckState
     release: Release
     /** the deployed url `smoke.base` declares, or null */
     live: string | null
+    /** the colours its repo.config.ts declares (SK024), null when it declares none */
+    identity: Identity | null
     /** epoch ms of the newest of: the last commit, the last shipkit run, the
      *  newest Claude Code transcript. null when none of them exists */
     activity: number | null
+    /** epoch ms of the last commit on HEAD, null when git cannot say */
+    commit: number | null
 }
-export type ProjectsAnswer = { projects: ProjectRow[]; ms: number; at: number }
+/** a repo whose repo.config.ts says `archived: true`: only the archived page lists it */
+export type ArchivedRow = { name: string; icon: string | null }
+
+export type ProjectsAnswer = { projects: ProjectRow[]; archived: ArchivedRow[]; ms: number; at: number }
 
 /** a command's exit code and stdout, or null when its binary is missing */
 export type Run = (cmd: string[], cwd?: string) => Promise<{ code: number; out: string } | null>
@@ -79,12 +91,18 @@ export type GutterDeps = {
     run?: Run
     /** opens a folder in VS Code; throws with the reason it could not */
     open?: (path: string) => void
+    /** opens a folder in Fork, the git client; throws with the reason it could not */
+    fork?: (path: string) => void
     warn?: (line: string) => void
     now?: () => number
     /** where the rail order lives, default ~/ORDER_FILE */
     orderFile?: string
     /** the Claude Code `projects` folders, default the `projects` folder of every ~/.claude config root */
     transcriptRoots?: string[]
+    /** the check ids a repo declares today (the daemon's plan), so a check
+     *  it no longer declares never colours it. Absent or null = not known,
+     *  every recorded check counts */
+    declared?: (name: string) => ReadonlySet<string> | null
 }
 
 const runCmd: Run = async (cmd, cwd) => {
@@ -107,6 +125,21 @@ function openInCode(path: string): void {
     throw new Error('the `code` command is not on PATH: in VS Code, run "Shell Command: Install \'code\' command in PATH"')
 }
 
+/** where Fork is installed, the places macOS keeps apps */
+export const FORK_APPS = ['/Applications/Fork.app', join(homedir(), 'Applications', 'Fork.app')]
+
+/** the command that opens a folder in Fork; throws when Fork is not installed */
+export function forkCommand(path: string, installed: (app: string) => boolean = existsSync, platform: string = process.platform): string[] {
+    if (platform !== 'darwin') throw new Error('opening in Fork is macOS only here')
+    const app = FORK_APPS.find(installed)
+    if (app == null) throw new Error(`Fork is not installed (looked in ${FORK_APPS.join(', ')})`)
+    return ['open', '-a', app, path]
+}
+
+function openInFork(path: string): void {
+    Bun.spawn(forkCommand(path), { stdio: ['ignore', 'ignore', 'ignore'] }).unref()
+}
+
 const epochMs = (out: string | undefined): number | null => {
     const secs = Number(out?.trim())
     return Number.isFinite(secs) && secs > 0 ? secs * 1000 : null
@@ -126,6 +159,15 @@ const readText = (file: string): string => {
     }
 }
 
+/** the house repos in the rail's order, archived ones left out: the rows of
+ *  the project list without the facts the list measures, for a caller that
+ *  needs only names and paths (`shipkit cross-repo-activity`) */
+export function railRepos(root: string, userHome: string = homedir(), orderFile: string = join(userHome, ORDER_FILE)): WiredRepo[] {
+    const repos = houseRepos(root, userHome).repos
+    const by = new Map(repos.map((r) => [r.name, r]))
+    return mergeOrder(parseOrder(readText(orderFile)), repos.map((r) => r.name)).map((n) => by.get(n)!)
+}
+
 export function projectGutter(d: GutterDeps) {
     let home = d.root
     const userHome = d.home ?? homedir()
@@ -141,21 +183,25 @@ export function projectGutter(d: GutterDeps) {
     }
 
     let repos: WiredRepo[] = []
+    let archivedRepos: WiredRepo[] = []
     let last: ProjectsAnswer | null = null
     let inFlight: Promise<ProjectsAnswer> | null = null
     let folders: { mtime: number; list: string[] } | null = null
     const releases = new Map<string, { stamp: string | null; at: number; release: Release; commitAt: number | null; dirty: number | null }>()
-    const gates = new Map<string, { stamp: string; gate: Gate }>()
-    /** a repo's last gate, its record opened only when it moved */
-    const gateOfRepo = (path: string): Gate => {
-        const record = recordOf(path)
-        if (record == null) return null
+    const records = new Map<string, { stamp: string; rows: LastRow[] }>()
+    /** a repo's last gate and check colour, its record opened only when it
+     *  moved, counted over the checks it declares today */
+    const gateOfRepo = (r: WiredRepo): { gate: Gate; checks: CheckState } => {
+        const record = recordOf(r.path)
+        if (record == null) return { gate: null, checks: null }
         const stamp = recordStamp(record)
-        const hit = gates.get(path)
-        if (hit != null && hit.stamp === stamp) return hit.gate
-        const gate = gateOf(readLastStatusReadonly(record))
-        gates.set(path, { stamp, gate })
-        return gate
+        let hit = records.get(r.path)
+        if (hit == null || hit.stamp !== stamp) {
+            hit = { stamp, rows: readLastStatusReadonly(record) }
+            records.set(r.path, hit)
+        }
+        const checks = checkStateOf(hit.rows, d.declared?.(r.name) ?? null)
+        return { gate: gateFrom(checks), checks }
     }
     const orderFile = d.orderFile ?? join(userHome, ORDER_FILE)
     const transcriptRoots = (): string[] => {
@@ -247,12 +293,15 @@ export function projectGutter(d: GutterDeps) {
         return paths.map((p) => ({ release: releases.get(p)?.release ?? null, commitAt: releases.get(p)?.commitAt ?? null, dirty: releases.get(p)?.dirty ?? null }))
     }
 
+    const iconUrl = (r: WiredRepo): string | null => (r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`)
+
     async function measure(): Promise<ProjectsAnswer> {
         const t0 = performance.now()
         const house = houseRepos(d.root, userHome)
         home = house.home
         if (house.index == null) warnOnce('house', `WARN project gutter: ${home} includes no house wiki index, so no sibling shares one and the gutter is empty`)
         repos = house.repos
+        archivedRepos = house.archived
         const [open, cwds, facts] = await Promise.all([vscodeFolders(), sessionCwds(), gitFacts(repos.map((r) => r.path))])
         const transcripts = lastSessionAt(transcriptRoots(), repos.map((r) => r.path))
         const counts = cwds == null ? null : countSessions(cwds, repos.map((r) => r.path))
@@ -262,10 +311,11 @@ export function projectGutter(d: GutterDeps) {
             const asks = openAsks(join(r.path, asksDirOf(config, r.path)))
             // the README is read only when package.json says nothing
             const description = descriptionOf(pkg, '') ?? descriptionOf('', readText(join(r.path, 'README.md')))
+            const state = gateOfRepo(r)
             return {
                 name: r.name,
                 path: r.path,
-                icon: r.icon == null ? null : `/api/projects/icon/${encodeURIComponent(r.name)}?v=${iconStamp(join(r.path, r.icon))}`,
+                icon: iconUrl(r),
                 current: r.path === home,
                 vscode: open == null ? null : open.some((f) => f === r.path),
                 sessions: counts?.get(r.path) ?? null,
@@ -275,13 +325,17 @@ export function projectGutter(d: GutterDeps) {
                 version: versionOf(pkg),
                 branch: branchOf(readText(join(r.path, '.git', 'HEAD'))),
                 dirty: facts[i]!.dirty,
-                gate: gateOfRepo(r.path),
+                gate: state.gate,
+                checks: state.checks,
                 release: facts[i]!.release,
                 live: liveUrlOf(config),
+                identity: identityOfText(config),
                 activity: lastActivity(facts[i]!.commitAt, lastRunAt(r.path), transcripts.get(r.path)),
+                commit: facts[i]!.commitAt,
             }
         })
-        return { projects: inOrder(projects, parseOrder(readText(orderFile))), ms: Math.round(performance.now() - t0), at: now() }
+        const archived = archivedRepos.map((r) => ({ name: r.name, icon: iconUrl(r) }))
+        return { projects: inOrder(projects, parseOrder(readText(orderFile))), archived, ms: Math.round(performance.now() - t0), at: now() }
     }
 
     /** the last answer while it is younger than POLL_MS, one measure otherwise,
@@ -296,6 +350,8 @@ export function projectGutter(d: GutterDeps) {
     }
 
     const find = (name: string): WiredRepo | undefined => repos.find((r) => r.name === name)
+    /** a live repo or an archived one: the icon and the archive toggle reach both */
+    const findAny = (name: string): WiredRepo | undefined => find(name) ?? archivedRepos.find((r) => r.name === name)
 
     /** saves the rail order: the names given, then every discovered repo they
      *  leave out. Written whole through a temp file, so a reader never sees
@@ -315,12 +371,43 @@ export function projectGutter(d: GutterDeps) {
         if (path === '/api/projects.json') return Response.json(await answer())
         if (path.startsWith('/api/projects/icon/')) {
             if (repos.length === 0) await answer()
-            const r = find(decodeURIComponent(path.slice('/api/projects/icon/'.length)))
+            const r = findAny(decodeURIComponent(path.slice('/api/projects/icon/'.length)))
             if (r?.icon == null) return new Response('no icon', { status: 404 })
             return new Response(Bun.file(join(r.path, r.icon)), {
                 headers: { 'content-type': ICON_TYPES[r.icon.split('.').pop()!] ?? 'application/octet-stream', 'cache-control': 'max-age=86400' },
             })
         }
+        if (path === '/api/projects/identity' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown; colorLight?: unknown; colorDark?: unknown }
+            const r = find(String(b.name))
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            // a colour left out keeps the config's own, so only the sent ones are checked
+            const bad = identityProblem({ colorLight: b.colorLight ?? '#000000', colorDark: b.colorDark ?? '#000000' })
+            if (bad != null) return new Response(bad, { status: 400 })
+            try {
+                const id = writeIdentity(r.path, { colorLight: b.colorLight as string | undefined, colorDark: b.colorDark as string | undefined })
+                if (last != null) last = { ...last, projects: last.projects.map((p) => (p.name === r.name ? { ...p, identity: id } : p)) }
+                return Response.json({ identity: id })
+            } catch (e) {
+                return new Response((e as Error).message, { status: 409 })
+            }
+        }
+        if (path === '/api/projects/archived' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown; archived?: unknown }
+            const r = findAny(String(b.name))
+            if (r == null) return new Response(`not a house repo: ${String(b.name)}`, { status: 404 })
+            if (typeof b.archived !== 'boolean') return new Response('archived must be true or false', { status: 400 })
+            try {
+                const on = writeArchived(r.path, b.archived)
+                // the repo moves between the two lists: the next answer measures again
+                last = null
+                return Response.json({ archived: on })
+            } catch (e) {
+                return new Response((e as Error).message, { status: 409 })
+            }
+        }
         if (path === '/api/projects/order' && req.method === 'POST') {
             if (repos.length === 0) await answer()
             const b = (await req.json().catch(() => ({}))) as { names?: unknown }
@@ -331,6 +418,20 @@ export function projectGutter(d: GutterDeps) {
                 return new Response(`the order could not be saved to ${orderFile}: ${(e as Error).message}`, { status: 500 })
             }
         }
+        if (path === '/api/projects/fork' && req.method === 'POST') {
+            if (repos.length === 0) await answer()
+            const b = (await req.json().catch(() => ({}))) as { name?: unknown }
+            const name = typeof b.name === 'string' ? b.name : ''
+            if (archivedRepos.some((r) => r.name === name)) return new Response(`${name} is archived: unarchive it first`, { status: 409 })
+            const r = find(name)
+            if (r == null) return new Response(`not a house repo: ${JSON.stringify(b.name ?? '')}`, { status: 404 })
+            try {
+                ;(d.fork ?? openInFork)(r.path)
+            } catch (e) {
+                return new Response((e as Error).message, { status: 400 })
+            }
+            return Response.json({ ok: true })
+        }
         if (path === '/api/projects/open' && req.method === 'POST') {
             if (repos.length === 0) await answer()
             const b = (await req.json().catch(() => ({}))) as { name?: string }

package/src/serve/project-gutter.ts

@@ -2,7 +2,7 @@
 // read of each one: which folders VS Code has open, which Claude Code
 // sessions run in which repo, its open asks, its distance to the last
 // release, its declared live url, its run record and its hub port. The
-// project gutter and the live strip both list repos through houseRepos, so
+// project gutter and the dock both list repos through houseRepos, so
 // the two surfaces show the same repos by construction. The parsers read
 // text they are handed, so sample output pins them; project-gutter-route.ts
 // and other-repos.ts own the spawns, the reads and the caches.
@@ -13,6 +13,7 @@ import { gitRoot } from '../core/git-root.ts'
 import { DB_FILE } from '../ledger/db.ts'
 import { defaultHubPort } from './hub-port.ts'
 import { LAYOUT } from '../core/layout.ts'
+import { isArchived } from '../core/archived.ts'
 
 export type WiredRepo = { name: string; path: string; icon: string | null }
 
@@ -72,11 +73,16 @@ export function wiredRepos(parent: string, index: string, home: string): WiredRe
 
 /** the house repos around the repo at `root`: its main checkout (`home`),
  *  the house index its own includes name, and every sibling that includes the
- *  same index, `home` among them. No index = no repos */
-export function houseRepos(root: string, userHome: string): { home: string; index: string | null; repos: WiredRepo[] } {
+ *  same index, `home` among them. No index = no repos. An archived repo
+ *  (`archived: true`, core/archived.ts) is never in `repos`, so nothing that
+ *  lists through here processes it: it is in `archived`, which only the
+ *  archived page reads */
+export function houseRepos(root: string, userHome: string): { home: string; index: string | null; repos: WiredRepo[]; archived: WiredRepo[] } {
     const home = homeRepo(root)
     const index = houseIndex(home, userHome)
-    return { home, index, repos: index == null ? [] : wiredRepos(dirname(home), index, userHome) }
+    const all = index == null ? [] : wiredRepos(dirname(home), index, userHome)
+    const archived = all.filter((r) => isArchived(r.path))
+    return { home, index, repos: all.filter((r) => !archived.includes(r)), archived }
 }
 
 /** the checkout a linked worktree belongs to, so a hub started in a worktree
@@ -289,15 +295,31 @@ export function branchOf(head: string): string | null {
 /** `git status --porcelain`: one line per changed or untracked path */
 export const dirtyCount = (porcelain: string): number => porcelain.split('\n').filter((l) => l.trim() !== '').length
 
-/** the last gate as its record holds it: green, or the checks whose last
- *  outcome failed. No row at all = unknown */
-export type Gate = 'green' | { reds: string[] } | null
-export function gateOf(rows: { id: string; status: string }[]): Gate {
-    if (rows.length === 0) return null
-    const reds = rows.filter((r) => r.status === 'fail').map((r) => r.id).sort()
-    return reds.length === 0 ? 'green' : { reds }
+/** a check's last outcome as the run record keeps it */
+export type LastRow = { id: string; status: string; at?: number }
+
+/** every check's last outcome in one colour: red when one failed, orange
+ *  when one only warned, green when all passed or skipped, with when each
+ *  red or warning was recorded. Only the ids the repo declares today count
+ *  (`declared`; null = not known, every row counts), so a renamed or deleted
+ *  check never holds a repo red. No row left = unknown */
+export type CheckState = { state: 'red' | 'orange' | 'green'; reds: string[]; warns: string[]; since: Record<string, number> } | null
+export function checkStateOf(rows: LastRow[], declared: ReadonlySet<string> | null = null): CheckState {
+    const live = declared == null ? rows : rows.filter((r) => declared.has(r.id))
+    if (live.length === 0) return null
+    const reds = live.filter((r) => r.status === 'fail').map((r) => r.id).sort()
+    const warns = live.filter((r) => r.status === 'warn').map((r) => r.id).sort()
+    const since: Record<string, number> = {}
+    for (const r of live) if ((r.status === 'fail' || r.status === 'warn') && typeof r.at === 'number') since[r.id] = r.at
+    return { state: reds.length > 0 ? 'red' : warns.length > 0 ? 'orange' : 'green', reds, warns, since }
 }
 
+/** the last gate: green, or the checks whose last outcome failed, read off
+ *  the same state. Unknown when no declared row is left */
+export type Gate = 'green' | { reds: string[] } | null
+export const gateFrom = (c: CheckState): Gate => (c == null ? null : c.reds.length === 0 ? 'green' : { reds: c.reds })
+export const gateOf = (rows: LastRow[], declared: ReadonlySet<string> | null = null): Gate => gateFrom(checkStateOf(rows, declared))
+
 /** the tag shapes a release leaves: `v1.2.3`, `name@1.2.3` (the shipkit
  *  defaults) and a bare `1.2.3`. A date or a merge marker is no release */
 export const RELEASE_TAGS = ['v[0-9]*', '*@[0-9]*', '[0-9]*.[0-9]*']

package/src/serve/readme-route.ts

@@ -0,0 +1,57 @@
+// the repo's README for the hub page's empty state, and the images it points
+// at. A file answers only when it is an image AND sits inside the repo root
+// once symlinks resolve: the route must never become a way to read the disk
+import { existsSync, realpathSync, statSync } from 'fs'
+import { extname, isAbsolute, join, relative, resolve } from 'path'
+
+const README_NAMES = ['README.md', 'readme.md', 'Readme.md', 'README.markdown', 'README']
+
+const IMAGE_TYPES: Record<string, string> = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.avif': 'image/avif',
+    '.ico': 'image/x-icon',
+}
+
+/** the README file name at the root, null when the repo has none */
+export function findReadme(root: string): string | null {
+    return README_NAMES.find((n) => existsSync(join(root, n)) && statSync(join(root, n)).isFile()) ?? null
+}
+
+/** an image under the root, or null for anything else: another type, a
+ *  missing file, `..`, an absolute path, a symlink that leaves the root */
+export function readmeAsset(root: string, rel: string): { path: string; type: string } | null {
+    if (rel === '' || isAbsolute(rel) || rel.includes('\0')) return null
+    const type = IMAGE_TYPES[extname(rel).toLowerCase()]
+    if (type == null) return null
+    const abs = resolve(root, rel)
+    if (!existsSync(abs)) return null
+    const real = realpathSync(abs)
+    const inside = relative(realpathSync(root), real)
+    if (inside === '' || inside.startsWith('..') || isAbsolute(inside)) return null
+    if (!statSync(real).isFile()) return null
+    return { path: real, type }
+}
+
+/** `/api/readme.json` and `/api/readme-file/<path>`, null for any other path */
+export async function readmeRoutes(root: string, path: string): Promise<Response | null> {
+    if (path === '/api/readme.json') {
+        const file = findReadme(root)
+        return Response.json({ file, md: file == null ? null : await Bun.file(join(root, file)).text() })
+    }
+    const prefix = '/api/readme-file/'
+    if (!path.startsWith(prefix)) return null
+    let rel: string
+    try {
+        rel = decodeURIComponent(path.slice(prefix.length))
+    } catch {
+        return new Response('bad path encoding', { status: 400 })
+    }
+    const asset = readmeAsset(root, rel)
+    if (asset == null) return new Response(`not an image inside this repo: ${rel}`, { status: 404 })
+    return new Response(Bun.file(asset.path), { headers: { 'content-type': asset.type, 'cache-control': 'no-cache' } })
+}

package/src/serve/repo-processes.ts

@@ -0,0 +1,89 @@
+// the long running processes a repo declares in `serve.processes` (a dev
+// server, a watcher), supervised by its hub with the same supervisor the home
+// uses for resources. Each runs detached with a pid record in the machine db
+// (named by its path under .shipkit/tmp, where an older copy kept a pid file),
+// so a hub restart in place adopts it, and only a real stop of the hub stops it.
+import { join, resolve } from 'path'
+import { Proc, realDeps, tailLines, type ProcView, type SuperviseDeps } from '../home/supervise.ts'
+import type { ProcessDecl } from '../repo-config.ts'
+import { LAYOUT } from '../core/layout.ts'
+
+export type ProcessView = ProcView & { url: string | null; auto: boolean; cmd: string; tail: string[] }
+
+export const processDir = (root: string): string => join(root, LAYOUT.tmp, 'processes')
+
+const probeUrl = async (url: string): Promise<boolean> => {
+    try {
+        // any answer means it serves: a dev server may 404 its root
+        await fetch(url, { signal: AbortSignal.timeout(1_500) })
+        return true
+    } catch {
+        return false
+    }
+}
+
+export class RepoProcesses {
+    private procs: { decl: ProcessDecl; proc: Proc }[]
+
+    constructor(root: string, decls: ProcessDecl[], o: { deps?: SuperviseDeps; probe?: (url: string) => Promise<boolean> } = {}) {
+        const dir = processDir(root)
+        this.procs = decls.map((decl) => ({
+            decl,
+            proc: new Proc({
+                id: decl.id,
+                cmd: decl.cmd,
+                cwd: resolve(root, decl.cwd ?? '.'),
+                log: join(dir, `${decl.id}.log`),
+                pidKey: join(dir, `${decl.id}.pid`),
+                probe: decl.url == null ? undefined : () => (o.probe ?? probeUrl)(decl.url!),
+            }, o.deps ?? realDeps),
+        }))
+    }
+
+    /** the auto ones start with the hub; an adopted one is left as it runs */
+    async startAuto(): Promise<void> {
+        await Promise.all(this.procs.filter((p) => p.decl.auto === true && p.proc.pid == null).map((p) => p.proc.ensure()))
+    }
+
+    act(id: string, act: 'start' | 'stop' | 'restart'): ProcessView | null {
+        const p = this.procs.find((x) => x.decl.id === id)
+        if (p == null) return null
+        if (act === 'stop' || act === 'restart') p.proc.stop()
+        if (act === 'start') void p.proc.ensure()
+        if (act === 'restart') this.restartWhenGone(p.proc)
+        return this.view(p)
+    }
+
+    private restartWhenGone(proc: Proc): void {
+        const wait = async (): Promise<void> => {
+            for (let i = 0; i < 40 && proc.status === 'stopping'; i++) {
+                await Bun.sleep(250)
+                await proc.tick()
+            }
+            proc.start()
+        }
+        void wait()
+    }
+
+    async tick(): Promise<void> {
+        await Promise.all(this.procs.map((p) => p.proc.tick()))
+    }
+
+    /** a real stop of the hub: every process it started stops with it */
+    stopAll(): void {
+        for (const p of this.procs) if (p.proc.pid != null) p.proc.stop()
+    }
+
+    private view(p: { decl: ProcessDecl; proc: Proc }): ProcessView {
+        const v = p.proc.view()
+        return { ...v, url: p.decl.url ?? null, auto: p.decl.auto === true, cmd: p.decl.cmd.join(' '), tail: v.status === 'up' ? [] : tailLines(p.proc.spec.log, 20) }
+    }
+
+    views(): ProcessView[] {
+        return this.procs.map((p) => this.view(p))
+    }
+
+    get size(): number {
+        return this.procs.length
+    }
+}