rvlib-shipkit 1.1.0 → 1.2.0

package/src/home/run-web.ts

@@ -0,0 +1,37 @@
+// `shipkit web`: the page on the home port, in front of the daemon and pm. It
+// loads no repo and no config, so it starts in a moment and a daemon restart
+// never moves it: the page stays up and says the daemon is down. An edit of
+// its own code, the page included, restarts it in place (lib-watch.ts).
+import homePage from '../serve/hub-app/home.html'
+import { fileURLToPath } from 'url'
+import { daemonPort, daemonUrl, homePort, homeUp, pmUrl } from './home-paths.ts'
+import { reloadOnOwnCode } from './lib-watch.ts'
+import { serveWeb } from './serve-web.ts'
+import type { HomeIo } from './run-daemon.ts'
+
+export async function runWeb(io: HomeIo, o: { port?: number } = {}): Promise<number> {
+    const port = o.port ?? homePort()
+    try {
+        const web = serveWeb({ port, daemon: daemonUrl(daemonPort()), pm: pmUrl(), page: homePage })
+        const code = reloadOnOwnCode({ role: 'web', entry: fileURLToPath(import.meta.url), bundles: true, before: () => web.stop(), io })
+        io.print(`home → http://localhost:${web.server.port} (the daemon: ${daemonUrl()}, pm: ${pmUrl()}), reloads on ${code.files} lib files`)
+        for (const sig of ['SIGINT', 'SIGTERM'] as const)
+            process.on(sig, () => {
+                code.stop()
+                web.stop()
+                process.exit(0)
+            })
+        await new Promise(() => {})
+        return 0
+    } catch (e) {
+        if (e instanceof Error && /in use|EADDRINUSE/.test(e.message)) {
+            if (await homeUp(port)) {
+                io.print(`home → http://localhost:${port} (already running)`)
+                return 0
+            }
+            io.printErr(`FAIL: port ${port} is taken by another process. Set SHIPKIT_HOME_PORT to a free one`)
+            return 1
+        }
+        throw e
+    }
+}

package/src/home/serve-daemon.ts

@@ -0,0 +1,31 @@
+// the daemon's one server, on its internal port: the home's api and every
+// house repo's hub under /r/<repo>/ (home-routes.ts), and no page. The web
+// (serve-web.ts) serves the page and proxies here, so a browser only ever
+// sees the web origin. A terminal client (via-hub.ts, attach.ts) talks here
+// directly, so a gate never depends on the web.
+import { homeRoutes, TICK_MS, type HomeDeps } from './home-routes.ts'
+
+export function serveDaemon(d: HomeDeps & { daemonPort: number }) {
+    const routes = homeRoutes(d)
+    const fetch = async (req: Request, srv: Bun.Server<unknown>): Promise<Response> =>
+        (await routes.handle(req, srv)) ?? new Response('not found', { status: 404 })
+    const server = Bun.serve({ port: d.daemonPort, hostname: '127.0.0.1', fetch })
+    let stopped = false
+    let running = false
+    const timer = setInterval(() => {
+        if (running || stopped) return
+        running = true
+        void routes.tick().catch((e) => console.error(`WARN the daemon tick broke: ${(e as Error).message}`)).finally(() => { running = false })
+    }, TICK_MS)
+    void routes.tick().catch(() => {})
+    return {
+        server,
+        routes,
+        stop: () => {
+            stopped = true
+            clearInterval(timer)
+            d.hubs.stopAll()
+            server.stop(true)
+        },
+    }
+}

package/src/home/serve-web.ts

@@ -0,0 +1,172 @@
+// the web: ONE Bun.serve on the home port. It serves the one page bundle (the
+// overview at `/`, the plan at `/planned`, a repo's hub page at `/r/<repo>/`,
+// all views of one app) and proxies every api,
+// graph and media request to the daemon, streams included, and /api/pm/* to
+// pm. A browser only ever sees this origin.
+//
+// the one constraint a reader breaks first: the same origin guard runs HERE,
+// against this origin, and the proxied request reaches the daemon with no
+// origin header. The daemon's own guard then refuses any page that calls its
+// port directly, and lets this door through.
+import { sameOrigin } from '../serve/same-origin.ts'
+import { hubBase } from './home-paths.ts'
+
+/** the page routes: ONE app for the overview, the plan, and the hub page of
+ *  each known repo, which moves between them in place (home-st.ts) */
+export function pageRoutes<T>(names: string[], page: T): Record<string, T> {
+    const out: Record<string, T> = { '/': page, '/planned': page }
+    for (const n of names) out[`${hubBase(n)}/`] = page
+    return out
+}
+
+/** a request the web hands to the daemon, as it goes there */
+export function proxied(path: string): boolean {
+    if (path === '/hub.json' || path.startsWith('/api/')) return true
+    return /^\/r\/[^/]+\/./.test(path)
+}
+
+/** the headers a browser sent, minus what names the browser's origin or this hop */
+const DROP = new Set(['host', 'origin', 'referer', 'sec-fetch-site', 'sec-fetch-mode', 'sec-fetch-dest', 'connection', 'keep-alive', 'content-length'])
+
+/** what the daemon being down reads like, as a page and as an api answer */
+export const daemonDownText = (daemon: string, why: string): string =>
+    `the shipkit daemon does not answer on ${daemon} (${why}). \`shipkit pm\` runs it; this page comes back by itself once it answers`
+
+export const pmDownText = (pm: string, why: string): string =>
+    `shipkit pm does not answer on ${pm} (${why}), so the resources and the daemon and web states are unknown. launchd runs it (\`shipkit pm install\`), or run \`shipkit pm\` from the house repo`
+
+/** the requests pm answers, the resources and the children */
+export const toPm = (path: string): boolean => path.startsWith('/api/pm/')
+
+const downPage = (text: string): string => `<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8"><title>shipkit: daemon down</title>
+<meta http-equiv="refresh" content="2"><style>body{font:14px/1.5 ui-sans-serif,system-ui;margin:0;padding:32px;background:#141619;color:#e6e6e6}
+@media (prefers-color-scheme: light){body{background:#fafafa;color:#1a1a1a}}b{color:#e5484d}</style></head>
+<body><p><b>daemon down</b></p><p>${text.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</p></body></html>`
+
+/** how long the web waits for the daemon's answer headers: the home api
+ *  answers from memory, a repo request can wait on that repo's load */
+export const MACHINE_ANSWER_MS = 5_000
+export const REPO_ANSWER_MS = 30_000
+/** how often the web asks the daemon's repo list once it has one, and while it has none */
+export const LIST_EVERY_MS = 30_000
+export const LIST_RETRY_MS = 1_000
+
+/** a run or a check run streams for minutes, and a silent one is never cut */
+export const streams = (path: string): boolean => /\/api\/(run|check\/run)$/.test(path)
+
+export type WebDeps<T> = {
+    port: number
+    /** the daemon's url, e.g. http://127.0.0.1:4798 */
+    daemon: string
+    /** pm's url, e.g. http://127.0.0.1:4797 */
+    pm: string
+    /** the one page bundle, served at every page route */
+    page: T
+    machineMs?: number
+    repoMs?: number
+    /** one pace for the repo list, in place of LIST_RETRY_MS and LIST_EVERY_MS */
+    listEveryMs?: number
+}
+
+export function serveWeb<T extends Bun.HTMLBundle | Response>(d: WebDeps<T>) {
+    let known = ''
+    let wasDown = false
+    let stopped = false
+    let listTimer: ReturnType<typeof setTimeout> | null = null
+    /** the repo names the daemon knows, or the reason it did not answer */
+    async function names(): Promise<string[] | Error> {
+        try {
+            const r = await fetch(`${d.daemon}/api/home/repos.json`, { signal: AbortSignal.timeout(3_000) })
+            if (!r.ok) return new Error(`${r.status} ${await r.text()}`)
+            return ((await r.json()) as { repos: string[] }).repos
+        } catch (e) {
+            return e as Error
+        }
+    }
+
+    async function proxy(req: Request, url: URL, srv: Bun.Server<unknown>): Promise<Response> {
+        if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
+        const headers = new Headers()
+        req.headers.forEach((v, k) => { if (!DROP.has(k)) headers.set(k, v) })
+        // a run or a live stream can stay silent for minutes
+        srv.timeout(req, 0)
+        const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : await req.arrayBuffer()
+        const path = url.pathname
+        const pm = toPm(path)
+        const target = pm ? d.pm : d.daemon
+        const wait = streams(path) ? null : path.startsWith('/r/') ? (d.repoMs ?? REPO_ANSWER_MS) : (d.machineMs ?? MACHINE_ANSWER_MS)
+        // the wait covers the answer headers only: a body already flowing is never cut
+        const ctl = new AbortController()
+        const timer = wait == null ? null : setTimeout(() => ctl.abort(new Error(`no answer in ${wait / 1000}s: it runs but hangs`)), wait)
+        try {
+            const r = await fetch(`${target}${path}${url.search}`, { method: req.method, headers, body, redirect: 'manual', decompress: false, signal: ctl.signal } as RequestInit)
+            if (timer != null) clearTimeout(timer)
+            if (wasDown && !pm) {
+                wasDown = false
+                follow()
+            }
+            const out = new Headers(r.headers)
+            out.delete('content-length')
+            out.delete('transfer-encoding')
+            out.delete('connection')
+            return new Response(r.body, { status: r.status, statusText: r.statusText, headers: out })
+        } catch (e) {
+            if (timer != null) clearTimeout(timer)
+            const why = ctl.signal.aborted ? (ctl.signal.reason as Error).message : (e as Error).message
+            if (pm) return new Response(pmDownText(d.pm, why), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', 'x-shipkit-pm': 'down' } })
+            wasDown = true
+            return new Response(daemonDownText(d.daemon, why), { status: 502, headers: { 'content-type': 'text/plain; charset=utf-8', 'x-shipkit-daemon': 'down' } })
+        }
+    }
+
+    const fetchFn = async (req: Request, srv: Bun.Server<unknown>): Promise<Response> => {
+        const url = new URL(req.url)
+        const path = url.pathname
+        if (proxied(path)) return proxy(req, url, srv)
+        const bare = /^\/r\/([^/]+)$/.exec(path)
+        if (bare != null) return Response.redirect(`${path}/${url.search}`, 308)
+        // a repo page the routes do not have yet: ask the daemon, set them, ask again
+        if (/^\/r\/[^/]+\/$/.test(path)) {
+            const n = await names()
+            if (n instanceof Error) return new Response(downPage(daemonDownText(d.daemon, n.message)), { status: 503, headers: { 'content-type': 'text/html; charset=utf-8' } })
+            const name = decodeURIComponent(path.slice(3, -1))
+            // known: its route is set now (here, or by a list that landed meanwhile)
+            if (n.includes(name)) {
+                sync(n)
+                return Response.redirect(`${path}${url.search}`, 307)
+            }
+            return new Response(`not a house repo: ${name}. The home lists its repos at /`, { status: 404 })
+        }
+        return new Response('not found: the home page is at /', { status: 404 })
+    }
+
+    const server = Bun.serve({ port: d.port, hostname: '127.0.0.1', routes: pageRoutes([], d.page), fetch: fetchFn })
+    /** the page routes follow the daemon's repo list; true when they changed */
+    function sync(list: string[]): boolean {
+        const sorted = [...list].sort()
+        if (sorted.join('\0') === known) return false
+        known = sorted.join('\0')
+        server.reload({ routes: pageRoutes(sorted, d.page), fetch: fetchFn })
+        return true
+    }
+    /** the routes follow the daemon's list: asked again soon while the
+     *  daemon does not answer, slowly once it does, and at once on its return */
+    function follow(): void {
+        if (listTimer != null) clearTimeout(listTimer)
+        listTimer = null
+        void names().then((n) => {
+            if (stopped) return
+            if (!(n instanceof Error)) sync(n)
+            listTimer = setTimeout(follow, d.listEveryMs ?? (n instanceof Error ? LIST_RETRY_MS : LIST_EVERY_MS))
+        })
+    }
+    follow()
+    return {
+        server,
+        stop: () => {
+            stopped = true
+            if (listTimer != null) clearTimeout(listTimer)
+            server.stop(true)
+        },
+    }
+}

package/src/home/supervise.ts

@@ -0,0 +1,346 @@
+// THE one way shipkit keeps a long running process alive: a global
+// resource, a repo's own dev server. Each process runs
+// DETACHED in its own process group, so the process that started it can die
+// or restart without taking it down, and its pid record in the machine db
+// (core/machine-db.ts) lets the next image adopt it instead of starting a
+// second copy.
+//
+// Truth is the pid and the probe, never this object's memory: tick() asks the
+// kernel whether the pid lives and the probe whether it answers.
+import { closeSync, existsSync, mkdirSync, openSync, readSync, rmSync, statSync, writeFileSync } from 'fs'
+import { dirname } from 'path'
+import { importMachineFile, machineDelete, machineGet, machineSet } from '../core/machine-db.ts'
+
+export type ProcStatus = 'down' | 'starting' | 'up' | 'crashed' | 'stopping'
+
+export type ProcSpec = {
+    id: string
+    cmd: string[]
+    cwd: string
+    env?: Record<string, string>
+    /** stdout and stderr land here, appended */
+    log: string
+    /** names its pid record, what the next image adopts: the machine db row
+     *  `pid:<pidKey>`. A path, because an older copy wrote a pid FILE there,
+     *  which is read once into the row and deleted */
+    pidKey: string
+    /** true once the process serves. No probe = up as soon as the pid lives */
+    probe?: () => Promise<boolean>
+    /** never left down after CRASH_LIMIT crashes: it keeps retrying at the
+     *  longest backoff, so a code fix brings it back with no hand */
+    neverGiveUp?: boolean
+}
+
+export type ProcView = {
+    id: string
+    status: ProcStatus
+    pid: number | null
+    /** epoch ms of the last status change */
+    since: number
+    /** crash restarts in the current window */
+    restarts: number
+    /** why it is not up, when that is known */
+    note: string | null
+    /** up, and started by something else: not ours to stop */
+    external: boolean
+}
+
+export type SuperviseDeps = {
+    spawn: (spec: ProcSpec) => number
+    alive: (pid: number) => boolean
+    /** signal the whole group the process leads */
+    kill: (pid: number, sig: 'SIGTERM' | 'SIGKILL') => void
+    now: () => number
+    /** epoch ms the process started, null when unknown. A pid that started
+     *  after its pid record was written was reused by another process */
+    startedAt?: (pid: number) => number | null
+}
+
+/** a process starts a moment before its pid record is written */
+const RECORD_SLACK_MS = 2_000
+
+/** a crash restarts after BACKOFF_MS[n], the last entry repeating */
+export const BACKOFF_MS = [1_000, 2_000, 5_000, 15_000, 60_000]
+/** this many crashes inside CRASH_WINDOW_MS and it stays down until asked */
+export const CRASH_LIMIT = 5
+export const CRASH_WINDOW_MS = 5 * 60_000
+/** a stop that SIGTERM did not end becomes a SIGKILL after this */
+export const KILL_AFTER_MS = 5_000
+
+/** the process is started by a shell that exits at once: it belongs to init
+ *  from its first moment, so a supervisor that restarts in place (execve)
+ *  never holds it as a zombie that reads alive forever. `set -m` gives it its
+ *  own process group, which a stop signals whole */
+const LAUNCH = 'set -m; "$@" >>"$0" 2>&1 </dev/null & echo $!'
+
+export const realDeps: SuperviseDeps = {
+    spawn: (spec) => {
+        mkdirSync(dirname(spec.log), { recursive: true })
+        closeSync(openSync(spec.log, 'a'))
+        const r = Bun.spawnSync(['/bin/sh', '-c', LAUNCH, spec.log, ...spec.cmd], { cwd: spec.cwd, env: { ...process.env, ...spec.env }, stdout: 'pipe', stderr: 'pipe' })
+        const pid = Number(r.stdout.toString().trim())
+        if (r.exitCode !== 0 || !Number.isInteger(pid) || pid <= 0) throw new Error(`the launch shell exited ${r.exitCode}: ${r.stderr.toString().trim()}`)
+        return pid
+    },
+    alive: (pid) => {
+        try {
+            process.kill(pid, 0)
+            return true
+        } catch (e) {
+            // EPERM: it lives, under another user
+            return (e as NodeJS.ErrnoException).code === 'EPERM'
+        }
+    },
+    kill: (pid, sig) => {
+        try {
+            process.kill(-pid, sig)
+        } catch {
+            try { process.kill(pid, sig) } catch { /* already gone */ }
+        }
+    },
+    now: Date.now,
+    startedAt: (pid) => {
+        const r = Bun.spawnSync(['ps', '-o', 'lstart=', '-p', String(pid)], { stdout: 'pipe', stderr: 'ignore' })
+        const t = Date.parse(r.stdout.toString().trim())
+        // lstart has whole seconds
+        return Number.isNaN(t) ? null : t + 999
+    },
+}
+
+export type PidRecord = { pid: number; cmd: string[]; at: number }
+
+const pidRow = (key: string): string => `pid:${key}`
+
+export function readPid(key: string): PidRecord | null {
+    importMachineFile<PidRecord>(pidRow(key), key)
+    const r = machineGet<PidRecord>(pidRow(key))
+    return r != null && Number.isInteger(r.pid) && r.pid > 0 ? r : null
+}
+
+function writePid(key: string, r: PidRecord): void {
+    machineSet(pidRow(key), r)
+}
+
+const dropPid = (key: string): void => {
+    machineDelete(pidRow(key))
+    try { rmSync(key, { force: true }) } catch { /* an older copy's file, gone either way */ }
+}
+
+export class Proc {
+    status: ProcStatus = 'down'
+    pid: number | null = null
+    since: number
+    note: string | null = null
+    /** what the owner asked for: a crash restarts only a process wanted up */
+    want: 'up' | 'down' = 'down'
+    private crashes: number[] = []
+    private retryAt: number | null = null
+    private killAt: number | null = null
+    private probing = false
+    /** a restart: start again once the stop landed */
+    private again = false
+    /** it answers its probe with no pid of ours behind it */
+    external = false
+    /** the pid came from the pid record an earlier image wrote, not from a start */
+    adopted = false
+
+    constructor(readonly spec: ProcSpec, private d: SuperviseDeps = realDeps) {
+        this.since = d.now()
+        const rec = readPid(spec.pidKey)
+        // an earlier image started it and it still runs: adopt, never double
+        if (rec != null && d.alive(rec.pid) && !((d.startedAt?.(rec.pid) ?? 0) > rec.at + RECORD_SLACK_MS)) {
+            this.pid = rec.pid
+            this.adopted = true
+            this.want = 'up'
+            this.set('starting')
+        } else if (rec != null) dropPid(spec.pidKey)
+    }
+
+    private set(s: ProcStatus, note: string | null = null): void {
+        if (s !== this.status) this.since = this.d.now()
+        this.status = s
+        this.note = note
+    }
+
+    /** start it unless it already runs; clears a crash give up */
+    start(): void {
+        this.want = 'up'
+        this.crashes = []
+        this.retryAt = null
+        if (this.pid != null && this.d.alive(this.pid)) return
+        // a second copy would lose the port to the first and read as a crash
+        if (this.external) return
+        this.launch()
+    }
+
+    /** start it, but look first: something else may already serve it (a hub
+     *  a VS Code task started, a dev server run by hand), and a second copy
+     *  would lose the port and linger. Every owner starts through this */
+    async ensure(): Promise<void> {
+        if (this.pid == null && !this.external && this.spec.probe != null && this.want === 'down') await this.tick()
+        this.start()
+    }
+
+    private launch(): void {
+        try {
+            const pid = this.d.spawn(this.spec)
+            this.pid = pid
+            this.adopted = false
+            writePid(this.spec.pidKey, { pid, cmd: this.spec.cmd, at: this.d.now() })
+            this.set('starting')
+        } catch (e) {
+            this.pid = null
+            this.set('crashed', `could not start ${this.spec.cmd.join(' ')}: ${(e as Error).message}`)
+        }
+    }
+
+    /** stop it, then start it again once it is gone */
+    restart(): void {
+        if (this.pid == null || !this.d.alive(this.pid)) {
+            this.start()
+            return
+        }
+        this.stop()
+        this.again = true
+    }
+
+    /** something else serves it (external): stop that owner, then start our
+     *  own copy. `targets` are what to signal (a process group, else the pid),
+     *  `owners` the pids that must be gone before the start. SIGTERM, then
+     *  SIGKILL once KILL_AFTER_MS passed with an owner still alive */
+    async takeOver(owners: number[], targets: number[], sleep: (ms: number) => Promise<void>): Promise<void> {
+        const left = (): boolean => owners.some((pid) => this.d.alive(pid))
+        for (const t of targets) this.d.kill(t, 'SIGTERM')
+        this.set('stopping', 'taking it over: stopping the copy started elsewhere')
+        let until = this.d.now() + KILL_AFTER_MS
+        while (left() && this.d.now() < until) await sleep(100)
+        if (left()) {
+            for (const t of targets) this.d.kill(t, 'SIGKILL')
+            until = this.d.now() + KILL_AFTER_MS
+            while (left() && this.d.now() < until) await sleep(100)
+        }
+        if (left()) {
+            this.set('up', `take over failed: pid ${owners.filter((pid) => this.d.alive(pid)).join(', ')} outlived SIGKILL`)
+            return
+        }
+        this.external = false
+        this.set('down')
+        this.start()
+    }
+
+    stop(): void {
+        this.want = 'down'
+        this.again = false
+        this.retryAt = null
+        if (this.pid == null || !this.d.alive(this.pid)) {
+            this.gone()
+            // started elsewhere: it keeps running, and says so
+            if (this.external) this.set('up', 'started outside the supervisor, so it is not stopped from here')
+            else this.set('down')
+            return
+        }
+        this.d.kill(this.pid, 'SIGTERM')
+        this.killAt = this.d.now() + KILL_AFTER_MS
+        this.set('stopping')
+    }
+
+    /** read through a call, so a check after an await is not narrowed away */
+    private stopping(): boolean {
+        return this.status === 'stopping'
+    }
+
+    private gone(): void {
+        this.pid = null
+        this.killAt = null
+        dropPid(this.spec.pidKey)
+    }
+
+    /** one look at the world: the pid, the probe, a due restart or kill */
+    async tick(): Promise<void> {
+        const now = this.d.now()
+        if (this.pid != null && !this.d.alive(this.pid)) {
+            this.gone()
+            if (this.again) {
+                this.again = false
+                this.want = 'up'
+                this.launch()
+            } else if (this.want === 'down') this.set('down')
+            else {
+                this.crashes = [...this.crashes.filter((t) => now - t < CRASH_WINDOW_MS), now]
+                if (this.crashes.length >= CRASH_LIMIT && this.spec.neverGiveUp !== true) {
+                    this.want = 'down'
+                    this.set('crashed', `exited ${this.crashes.length} times in ${Math.round(CRASH_WINDOW_MS / 60_000)} min, left down: see the log`)
+                } else {
+                    this.retryAt = now + BACKOFF_MS[Math.min(this.crashes.length - 1, BACKOFF_MS.length - 1)]!
+                    this.set('crashed', `exited, restart in ${Math.round((this.retryAt - now) / 1000)}s`)
+                }
+            }
+        }
+        if (this.status === 'stopping' && this.pid != null && this.killAt != null && now >= this.killAt) {
+            this.d.kill(this.pid, 'SIGKILL')
+            this.killAt = now + KILL_AFTER_MS
+        }
+        if (this.want === 'up' && this.pid == null && this.retryAt != null && now >= this.retryAt) {
+            this.retryAt = null
+            this.launch()
+        }
+        if (this.probing || this.status === 'stopping') return
+        this.probing = true
+        try {
+            if (this.pid != null && (this.status === 'starting' || this.status === 'up')) {
+                const ok = this.spec.probe == null ? true : await this.spec.probe().catch(() => false)
+                this.external = false
+                // a stop may have landed while the probe was out
+                if (this.pid != null && !this.stopping()) this.set(ok ? 'up' : 'starting', ok ? null : this.status === 'up' ? 'stopped answering its probe' : null)
+            } else if (this.pid == null && this.retryAt == null && this.spec.probe != null && (this.status === 'down' || this.status === 'up')) {
+                // no pid of ours: something else may serve it, a hub a VS Code
+                // task started or a tunnel opened by hand
+                const ok = await this.spec.probe().catch(() => false)
+                if (this.pid != null) return
+                this.external = ok
+                this.set(ok ? 'up' : 'down', ok ? 'started outside the supervisor' : null)
+            }
+        } finally {
+            this.probing = false
+        }
+    }
+
+    view(): ProcView {
+        return { id: this.spec.id, status: this.status, pid: this.pid, since: this.since, restarts: this.crashes.length, note: this.note, external: this.external }
+    }
+}
+
+/** the last `n` lines of a log, read from its tail only */
+export function tailLines(file: string, n: number, maxBytes = 64 * 1024): string[] {
+    if (!existsSync(file)) return []
+    try {
+        const size = statSync(file).size
+        const fd = openSync(file, 'r')
+        try {
+            const len = Math.min(size, maxBytes)
+            const buf = Buffer.alloc(len)
+            readSync(fd, buf, 0, len, size - len)
+            return buf.toString('utf8').split('\n').filter((l) => l !== '').slice(-n)
+        } finally {
+            closeSync(fd)
+        }
+    } catch {
+        return []
+    }
+}
+
+/** the most a process log grows before capLog cuts it */
+export const LOG_MAX_BYTES = 8 * 1024 * 1024
+
+/** a log past `max` bytes is cut to its last `keep` bytes, so a process that
+ *  runs for weeks never fills the disk. Appends in flight land after the cut */
+export function capLog(file: string, max = LOG_MAX_BYTES, keep = 1024 * 1024): boolean {
+    try {
+        if (statSync(file).size <= max) return false
+        const tail = tailLines(file, Number.MAX_SAFE_INTEGER, keep)
+        writeFileSync(file, `${tail.join('\n')}\n`)
+        return true
+    } catch {
+        return false
+    }
+}