rvlib-shipkit 1.2.0 → 1.4.0

package/src/home/machine-stores.ts

@@ -91,8 +91,9 @@ export const BOOT_SWEEP_DELAY_MS = 10_000
 export type Sweeper = { stop: () => void; once: () => Promise<void> }
 
 /** the daemon's one retention sweep: every repo it loads, then the machine,
- *  on boot and every hour. A store whose sweep throws is one printed line */
-export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (l: string) => void; everyMs?: number; bootDelayMs?: number; now?: () => number }): Sweeper {
+ *  then `also` (the machine's batched writes), on boot and every hour. A
+ *  store whose sweep throws is one printed line */
+export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (l: string) => void; everyMs?: number; bootDelayMs?: number; now?: () => number; also?: (now: number) => void }): Sweeper {
     let running = false
     const once = async (): Promise<void> => {
         if (running) return
@@ -103,6 +104,7 @@ export function startSweeps(o: { roots: () => string[]; dir: string; printErr: (
                 for (const r of await sweepStores(repoStores(root), now)) if (r.error != null) o.printErr(`WARN retention sweep of ${r.id} in ${root} failed: ${r.error}`)
             }
             for (const r of await sweepStores(machineStores(o.dir), now)) if (r.error != null) o.printErr(`WARN retention sweep of ${r.id} failed: ${r.error}`)
+            o.also?.(now)
         } finally {
             running = false
         }

package/src/home/open-app.ts

@@ -1,16 +1,29 @@
-// opens one shipkit app window on a url, in its own short process, so pm
-// never loads what building the app needs:
+// opens one shipkit app window, in its own short process, so pm never loads
+// what building an app needs:
 //
-//   bun open-app.ts <url>
+//   bun open-app.ts <url>                 one more shipkit window on a url
+//   bun open-app.ts --process <json>      a global process's own app (WrapperOf)
 import { LIB_VERSION } from '../core/lib-version.ts'
-import { openWindow } from './home-start.ts'
+import type { WrapperOf } from './gui-app.ts'
+import { openProcessApp, openWindow } from './home-start.ts'
 
 if (import.meta.main) {
-    const url = process.argv[2]
-    if (url == null) {
-        console.error('usage: bun open-app.ts <url>')
-        process.exit(2)
+    const [first, second] = process.argv.slice(2)
+    const warn = (l: string): void => console.error(l)
+    try {
+        if (first === '--process' && second != null) {
+            const d = JSON.parse(second) as WrapperOf
+            const cmd = openProcessApp(d, { version: LIB_VERSION, warn })
+            console.log(`shipkit: opened ${d.id} as its own app: ${cmd.join(' ')}`)
+        } else if (first != null && first !== '--process') {
+            const cmd = openWindow(first, { version: LIB_VERSION, warn })
+            console.log(`shipkit: opened ${first} as an app window: ${cmd.join(' ')}`)
+        } else {
+            console.error('usage: bun open-app.ts <url> | --process <json>')
+            process.exit(2)
+        }
+    } catch (e) {
+        console.error(`shipkit: could not open the app: ${(e as Error).message}`)
+        process.exit(1)
     }
-    const cmd = openWindow(url, { version: LIB_VERSION, warn: (l) => console.error(l) })
-    console.log(`shipkit: opened ${url} as an app window: ${cmd.join(' ')}`)
 }

package/src/home/pm-config.ts

@@ -2,18 +2,14 @@
 // and the global processes every house repo declares in its `.shipkit.ts`
 // files), read in a short child process so pm itself never imports a repo
 // file. That graph would make pm large and reload it on every edit there.
+// The answer names the paths it read (`inputs`) and their stamp, so pm runs
+// the child again only once a stat of one of them moved.
 //
-//   bun pm-config.ts <root>   prints { index, processes, errors } as json on stdout
+//   bun pm-config.ts <root>   prints a PmConfig as json on stdout
 import { homedir } from 'os'
-import type { GlobalProcessDecl } from './global-units.ts'
+import { houseInputs, stampOf, type PmConfig } from './pm-inputs.ts'
 
-export type PmConfig = {
-    /** the house wiki index the repo includes, null when it includes none */
-    index: string | null
-    processes: GlobalProcessDecl[]
-    /** the unit files that would not load */
-    errors: string[]
-}
+export type { PmConfig }
 
 if (import.meta.main) {
     const root = process.argv[2]
@@ -22,14 +18,22 @@ if (import.meta.main) {
         process.exit(2)
     }
     const { houseRepos } = await import('../serve/project-gutter.ts')
+    const { repoUnitFiles } = await import('../core/discover-checks.ts')
     const house = houseRepos(root, homedir())
-    const out: PmConfig = { index: house.index, processes: [], errors: [] }
+    const repos = house.index == null ? [] : house.repos
+    const files = new Map<string, string[]>()
+    const inputs = houseInputs(house.home, house.index, repos.map((r) => r.path), (r, dirs) => {
+        const f = repoUnitFiles(r, dirs)
+        files.set(r, f)
+        return f
+    })
+    const out: PmConfig = { index: house.index, processes: [], errors: [], inputs, stamp: stampOf(inputs) }
     if (house.index != null) {
         // a unit file imports the lib by name: this copy, like the daemon's
         const { useOneLib } = await import('../core/one-lib.ts')
         const { scanGlobalUnits } = await import('./global-units.ts')
         useOneLib()
-        const u = await scanGlobalUnits(house.repos.map((r) => ({ name: r.name, path: r.path })))
+        const u = await scanGlobalUnits(repos.map((r) => ({ name: r.name, path: r.path })), { files: (r) => files.get(r) ?? [] })
         out.processes = u.processes
         out.errors = u.errors
     }

package/src/home/pm-inputs.ts

@@ -0,0 +1,76 @@
+// what pm stamps to know whether the house side moved, without running the
+// child that reads it (pm-config.ts): the answer's shape, the paths it
+// depends on, and their stamp. Imports nothing a repo file does, so pm's own
+// graph stays small.
+import { readdirSync, statSync } from 'fs'
+import { dirname, join } from 'path'
+import { UNIT_SUFFIX } from '../core/check-file-names.ts'
+import type { GlobalProcessDecl } from './global-units.ts'
+
+export type PmConfig = {
+    /** the house wiki index the repo includes, null when it includes none */
+    index: string | null
+    processes: GlobalProcessDecl[]
+    /** the unit files that would not load */
+    errors: string[]
+    /** every path whose stat can change this answer (houseInputs) */
+    inputs: string[]
+    /** stampOf(inputs), taken before the unit files were imported */
+    stamp: string
+}
+
+/** the files a repo carries its includes in. Here, not in project-gutter.ts
+ *  which reads them, so pm stamps them without loading that graph */
+export const CLAUDE_FILES = ['CLAUDE.md', 'CLAUDE.local.md']
+
+/** what the answer depends on, as paths to stat: the dir holding the repos
+ *  (a repo added or removed), every sibling's CLAUDE files (a repo starting
+ *  to include the house), the index, each house repo's config (archived),
+ *  and every dir and unit file the unit walk read. A helper a unit file
+ *  imports is not in it: an edit there shows once the unit file moves */
+export function houseInputs(home: string, index: string | null, repos: string[], unitFiles: (root: string, dirs: string[]) => string[]): string[] {
+    const parent = dirname(home)
+    const out = [parent]
+    let names: string[] = []
+    try { names = readdirSync(parent) } catch { /* the stat of parent says when it appears */ }
+    for (const n of names.sort()) if (!n.startsWith('.')) for (const f of CLAUDE_FILES) out.push(join(parent, n, f))
+    if (index != null) out.push(index)
+    for (const r of repos) {
+        out.push(join(r, 'repo.config.ts'))
+        const dirs: string[] = []
+        const files = unitFiles(r, dirs)
+        out.push(...dirs, ...files)
+    }
+    return out
+}
+
+/** a dir's entries that can change the answer: its subdirs and its unit
+ *  files. A temp file coming and going moves the dir's mtime, not this */
+const listings = new Map<string, { mtime: number; names: string }>()
+function dirNames(dir: string, mtime: number): string {
+    const hit = listings.get(dir)
+    if (hit?.mtime === mtime) return hit.names
+    let names = ''
+    try {
+        names = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => !e.name.startsWith('.') && (e.isDirectory() || e.name.endsWith(UNIT_SUFFIX)))
+            .map((e) => e.name)
+            .sort()
+            .join('/')
+    } catch { /* gone between the stat and the read: the next stat says so */ }
+    listings.set(dir, { mtime, names })
+    return names
+}
+
+/** every path as one string: a file by its mtime, a dir by the entries
+ *  that matter (read again only when its mtime moved), -1 when missing */
+export function stampOf(paths: string[]): string {
+    return paths.map((p) => {
+        try {
+            const st = statSync(p)
+            return st.isDirectory() ? dirNames(p, st.mtimeMs) : st.mtimeMs
+        } catch {
+            return -1
+        }
+    }).join(',')
+}

package/src/home/pm.ts

@@ -7,9 +7,12 @@
 // the one constraint a reader breaks first: pm never takes a child down with
 // it. A reload of pm, or pm killed, leaves both running, and the next pm
 // adopts them from their pid records. Only a stop asked of pm stops them.
+import { existsSync } from 'fs'
+import { join } from 'path'
 import { LIB_VERSION } from '../core/lib-version.ts'
+import { iconImageType } from '../shipkit-files.ts'
 import { sameOrigin } from '../serve/same-origin.ts'
-import { childLog, childPid } from './home-paths.ts'
+import { childLog, childPid, daemonPort, homePort, pmLog, pmPort } from './home-paths.ts'
 import type { Resources, ResourceView } from './resources.ts'
 import { capLog, Proc, realDeps, tailLines, type ProcView, type SuperviseDeps } from './supervise.ts'
 
@@ -21,10 +24,22 @@ export const PM_TICK_MS = 2_000
 
 export type ChildView = ProcView & { tail: string[] }
 
+/** where pm, the daemon and the web listen */
+export type CorePorts = { pm: number; daemon: number; web: number }
+
+/** how many log lines each of shipkit's own processes hands the page */
+const CORE_TAIL = 20
+
 export type PmAnswer = {
     pm: 'shipkit-pm'
     pid: number
+    /** epoch ms this pm started; absent from a pm older than the field */
+    since?: number
     version: string
+    /** where pm and its children listen; absent from a pm older than the field */
+    ports?: CorePorts
+    /** the last lines of pm's own log; absent from a pm older than the field */
+    tail?: string[]
     children: ChildView[]
     resources: ResourceView[]
     /** the `.shipkit.ts` files that would not load, as pm last read them */
@@ -35,6 +50,8 @@ export type PmDeps = {
     dir: string
     /** the house repo: where the children run */
     root: string
+    /** the port pm serves on (default: SHIPKIT_PM_PORT, else 4797) */
+    port?: number
     /** the command that runs one role, e.g. [bun, cli.ts, 'daemon'] */
     cmd: (role: Role) => string[]
     /** true once the role serves */
@@ -50,6 +67,7 @@ const WEB_ANSWER_MS = 200
 
 export class Pm {
     readonly children: Map<Role, Proc>
+    private readonly startedAt = Date.now()
 
     constructor(private d: PmDeps) {
         this.children = new Map(ROLES.map((role) => [role, new Proc({
@@ -90,14 +108,30 @@ export class Pm {
     }
 
     answer(): PmAnswer {
-        const children = [...this.children.values()].map((p) => ({ ...p.view(), tail: p.status === 'up' ? [] : tailLines(p.spec.log, 20) }))
-        return { pm: 'shipkit-pm', pid: process.pid, version: LIB_VERSION, children, resources: this.d.resources.views(), unitErrors: this.d.resources.errors }
+        // up: since its pid started, so a pm reload never resets its uptime
+        const children = [...this.children.values()].map((p) => {
+            const v = p.view()
+            return { ...v, since: (v.status === 'up' ? p.startedAt() : null) ?? v.since, tail: tailLines(p.spec.log, CORE_TAIL) }
+        })
+        const ports = { pm: this.d.port ?? pmPort(), daemon: daemonPort(), web: homePort() }
+        return { pm: 'shipkit-pm', pid: process.pid, since: this.startedAt, version: LIB_VERSION, ports, tail: tailLines(pmLog(this.d.dir), CORE_TAIL), children, resources: this.d.resources.views(), unitErrors: this.d.resources.errors }
+    }
+
+    /** the image a global process declares as its icon, and no other file */
+    private icon(id: string): Response {
+        const d = this.d.resources.get(id)?.decl
+        const type = d?.icon == null ? null : iconImageType(d.icon)
+        if (d?.icon == null || type == null) return new Response(`no image icon for '${id}'`, { status: 404 })
+        const file = join(d.root, d.icon)
+        if (!existsSync(file)) return new Response(`${d.repo}/${d.icon} does not exist: the icon of '${id}'`, { status: 404 })
+        return new Response(Bun.file(file), { headers: { 'content-type': type, 'cache-control': 'no-cache' } })
     }
 
     async handle(req: Request): Promise<Response> {
         const path = new URL(req.url).pathname
         if (!sameOrigin(req)) return new Response('refused: a request that changes something must come from the home page', { status: 403 })
         if (path === '/api/pm/status.json') return Response.json(this.answer())
+        if (path.startsWith('/api/pm/icon/') && req.method === 'GET') return this.icon(decodeURIComponent(path.slice('/api/pm/icon/'.length)))
         if (req.method !== 'POST') return new Response('not found', { status: 404 })
         const b = (await req.json().catch(() => ({}))) as Record<string, unknown>
         if (path === '/api/pm/child') {
@@ -120,10 +154,9 @@ export class Pm {
             if (act === 'start') report(r.set('up'))
             else if (act === 'stop') report(r.set('down'))
             else if (act === 'restart') report(r.restart())
-            else if (act === 'open' || act === 'app') {
+            else if (act === 'open' || act === 'chrome' || act === 'app') {
                 if (r.decl.url == null) return new Response(`${r.decl.id} declares no url to open`, { status: 400 })
-                if (act === 'app' && !r.decl.app) return new Response(`${r.decl.id} does not declare app: true, so it has no app window`, { status: 400 })
-                report(r.open(act === 'app' ? 'app' : 'browser'))
+                report(r.open(act === 'open' ? 'browser' : act))
             } else if (act === 'takeover') {
                 const v = r.takeOverView
                 if (v == null) return new Response(`${r.decl.id} does not run outside the supervisor: nothing to take over`, { status: 409 })
@@ -133,7 +166,7 @@ export class Pm {
                 if (!r.decl.actions.some((a) => a.id === b.action)) return new Response(`${r.decl.id} declares no action '${String(b.action)}'`, { status: 404 })
                 if (r.running != null) return new Response(`${r.decl.id} is already running its action '${r.running}'`, { status: 409 })
                 report(r.action(String(b.action)))
-            } else return new Response('act must be start, stop, restart, open, app, takeover or action', { status: 400 })
+            } else return new Response('act must be start, stop, restart, open, chrome, app, takeover or action', { status: 400 })
             return Response.json(r.view())
         }
         return new Response('not found', { status: 404 })

package/src/home/process-rows.ts

@@ -0,0 +1,222 @@
+// the processes as rows: shipkit's own first (pm, the daemon, the web: the
+// core group), then one group per declaring repo, one row per process, in the
+// order the page and `shipkit global-processes` both show.
+// The page's table and the command's text and json are all drawn from these
+// rows, so the two can never disagree. A row carries no clock: ages are words
+// computed at render time from `since`.
+import type { GlobalProcessDecl } from './global-units.ts'
+import type { CorePorts, PmAnswer } from './pm.ts'
+import type { ProcessIcon, ResourceView } from './resources.ts'
+import type { ProcStatus } from './supervise.ts'
+
+/** a status as pm reports it, unknown while pm does not answer, silent
+ *  while pm runs it but the page gets no answer from it */
+export type RowStatus = ProcStatus | 'unknown' | 'silent'
+
+/** the dot a row wears: green up, red crashed, grey stopped or unknown, orange on its way */
+export type RowDot = 'up' | 'crashed' | 'down' | 'starting' | 'unknown'
+
+export type ProcessRow = {
+    id: string
+    label: string
+    repo: string
+    file: string
+    status: RowStatus
+    dot: RowDot
+    url: string | null
+    /** the url without its scheme, what the table shows dimmed */
+    host: string | null
+    pid: number | null
+    /** epoch ms its state counts from (up: its pid's start when it has one), null when pm never said */
+    since: number | null
+    note: string | null
+    description: string | null
+    where: string | null
+    /** the last line of its log, null when it has none */
+    lastLog: string | null
+    tail: string[]
+    canStop: boolean
+    /** the page offers restart: a global process pm runs and can stop, while
+     *  up; the daemon and the web always, through pm; never pm itself */
+    canRestart: boolean
+    /** one of shipkit's own: always on, no stop, no open */
+    core: boolean
+    /** the shipkit version it runs, when known (core rows only) */
+    version: string | null
+    takeOver: ResourceView['takeOver']
+    actions: { id: string; label: string }[]
+    running: string | null
+    icon: ProcessIcon | null
+    /** its own app is being built or opened */
+    appBusy: boolean
+}
+
+/** a repo's processes, or shipkit's own (`core`, always the first group) */
+export type ProcessGroup = { repo: string; core?: true; rows: ProcessRow[] }
+
+/** the core group's name */
+export const CORE_GROUP = 'shipkit'
+
+export const dotOf = (s: RowStatus): RowDot =>
+    s === 'up' ? 'up' : s === 'crashed' || s === 'silent' ? 'crashed' : s === 'starting' || s === 'stopping' ? 'starting' : s === 'down' ? 'down' : 'unknown'
+
+const hostOf = (url: string | null): string | null => (url == null ? null : url.replace(/^https?:\/\//, '').replace(/\/$/, ''))
+
+/** a process as pm serves it. A pm older than pid and since reads them as null */
+export function rowOf(r: ResourceView): ProcessRow {
+    return {
+        id: r.id,
+        label: r.label,
+        repo: r.repo,
+        file: r.file,
+        status: r.status,
+        dot: dotOf(r.status),
+        url: r.url,
+        host: hostOf(r.url),
+        pid: r.pid ?? null,
+        since: r.since ?? null,
+        note: r.note,
+        description: r.description,
+        where: r.where,
+        lastLog: r.tail.at(-1) ?? null,
+        tail: r.tail,
+        canStop: r.canStop,
+        canRestart: r.status === 'up' && r.canStop,
+        core: false,
+        version: null,
+        takeOver: r.takeOver,
+        actions: r.actions,
+        running: r.running,
+        icon: r.icon,
+        appBusy: r.appBusy === true,
+    }
+}
+
+/** a declared process while pm does not answer: everything but its state */
+export function declaredRow(d: GlobalProcessDecl): ProcessRow {
+    return {
+        id: d.id,
+        label: d.label,
+        repo: d.repo,
+        file: d.file,
+        status: 'unknown',
+        dot: 'unknown',
+        url: d.url,
+        host: hostOf(d.url),
+        pid: null,
+        since: null,
+        note: null,
+        description: d.description,
+        where: d.where,
+        lastLog: null,
+        tail: [],
+        canStop: false,
+        canRestart: false,
+        core: false,
+        version: null,
+        takeOver: null,
+        actions: d.actions.map((a) => ({ id: a.id, label: a.label })),
+        running: null,
+        appBusy: false,
+        // an image is pm's to serve, and pm does not answer
+        icon: d.icon == null || /\.[a-z0-9]+$/i.test(d.icon) ? null : { text: d.icon },
+    }
+}
+
+/** one group per repo, in `order` (the project list), the repos it does not
+ *  list after it by name; a group keeps pm's order */
+export function groupRows(rows: ProcessRow[], order: string[]): ProcessGroup[] {
+    const by = new Map<string, ProcessRow[]>()
+    for (const r of rows) by.set(r.repo, [...(by.get(r.repo) ?? []), r])
+    const rank = (repo: string): number => {
+        const i = order.indexOf(repo)
+        return i < 0 ? order.length : i
+    }
+    return [...by.keys()]
+        .sort((a, b) => rank(a) - rank(b) || a.localeCompare(b))
+        .map((repo) => ({ repo, rows: by.get(repo)! }))
+}
+
+export const CORE_ABOUT = {
+    pm: 'the process manager, the LaunchAgent com.shipkit.pm: launchd starts it at login and again when it dies, so the page has no restart for it (from a terminal: launchctl kickstart -k gui/$(id -u)/com.shipkit.pm)',
+    daemon: 'loads every house repo hub in one process and serves their api, restarted through pm',
+    web: 'serves this page and passes every api request to the daemon, restarted through pm',
+} as const
+
+export type CoreOpts = {
+    /** the daemon's own version, asked of the daemon; null when it does not answer */
+    daemonVersion?: string | null
+    /** where each listens, when pm does not say (an older pm, or pm down) */
+    ports?: CorePorts | null
+    /** one of shipkit's own not answering the page, and why: its row says
+     *  no answer whatever pm last reported. pm silent, every other row is
+     *  the last answer's with its state unknown, so the table keeps its lines */
+    silent?: Partial<Record<'pm' | 'daemon' | 'web', string>>
+}
+
+function coreRow(id: 'pm' | 'daemon' | 'web', o: { status: RowStatus; pid: number | null; since: number | null; note: string | null; tail: string[]; version: string | null; port: number | null; restart: boolean }): ProcessRow {
+    const url = o.port == null ? null : `http://127.0.0.1:${o.port}`
+    return {
+        id, label: id, repo: CORE_GROUP, file: '', status: o.status, dot: dotOf(o.status), url, host: hostOf(url), pid: o.pid, since: o.since, note: o.note,
+        description: CORE_ABOUT[id], where: null, lastLog: o.tail.at(-1) ?? null, tail: o.tail,
+        canStop: false, canRestart: o.restart, core: true, version: o.version, takeOver: null, actions: [], running: null, icon: null, appBusy: false,
+    }
+}
+
+/** shipkit's own processes, one row each: pm as it answers (down when it does
+ *  not), then the daemon and the web as pm reports them (unknown without pm) */
+export function coreGroup(pm: PmAnswer | null, o: CoreOpts = {}): ProcessGroup {
+    const ports = pm?.ports ?? o.ports ?? null
+    const rows: ProcessRow[] = [pm == null
+        ? coreRow('pm', { status: 'down', pid: null, since: null, note: 'pm does not answer', tail: [], version: null, port: ports?.pm ?? null, restart: false })
+        : coreRow('pm', { status: 'up', pid: pm.pid, since: pm.since ?? null, note: null, tail: pm.tail ?? [], version: pm.version, port: ports?.pm ?? null, restart: false })]
+    for (const id of ['daemon', 'web'] as const) {
+        const c = pm?.children.find((x) => x.id === id)
+        const port = ports?.[id] ?? null
+        const version = id === 'daemon' ? (o.daemonVersion ?? null) : null
+        if (c == null) rows.push(coreRow(id, { status: 'unknown', pid: null, since: null, note: null, tail: [], version, port, restart: false }))
+        else {
+            const note = [c.note, c.restarts > 0 ? `${c.restarts} restart(s)` : null].filter((x) => x != null).join(', ')
+            rows.push(coreRow(id, { status: c.status, pid: c.pid, since: c.since, note: note === '' ? null : note, tail: c.tail, version, port, restart: true }))
+        }
+    }
+    const s = o.silent ?? {}
+    return { repo: CORE_GROUP, core: true, rows: rows.map((r) => {
+        const why = s[r.id as 'pm' | 'daemon' | 'web']
+        return why != null && why !== '' ? { ...r, status: 'silent', dot: 'crashed', note: why } : s.pm ? stale(r) : r
+    }) }
+}
+
+/** what the page's table holds, from pm's answer: the core group, then the
+ *  global processes by repo */
+export const processGroups = (pm: PmAnswer | null, order: string[], o: CoreOpts = {}): ProcessGroup[] =>
+    [coreGroup(pm, o), ...groupRows((pm?.resources ?? []).map((r) => (o.silent?.pm ? stale(rowOf(r)) : rowOf(r))), order)]
+
+/** a row from an answer pm can no longer confirm: its state unknown, nothing to click */
+const stale = (r: ProcessRow): ProcessRow => ({ ...r, status: 'unknown', dot: 'unknown', canStop: false, canRestart: false, takeOver: null, running: null, appBusy: false })
+
+/** the declared icon, else the repo's own, else none */
+export const processIcon = (r: { icon: ProcessIcon | null }, repoIcon: string | null): ProcessIcon | null =>
+    r.icon ?? (repoIcon == null ? null : { src: repoIcon })
+
+/** a span in its largest whole unit: 45s, 3m, 2h, 4d */
+export function spanWords(ms: number): string {
+    const s = Math.max(0, Math.floor(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** the state in words: `up 2h`, `crashed 3m ago`, `stopped`, `starting` */
+export function stateWords(r: Pick<ProcessRow, 'status' | 'since'>, now: number): string {
+    const age = r.since == null ? null : spanWords(now - r.since)
+    switch (r.status) {
+        case 'up': return age == null ? 'up' : `up ${age}`
+        case 'crashed': return age == null ? 'crashed' : `crashed ${age} ago`
+        case 'down': return 'stopped'
+        case 'unknown': return 'unknown (pm down)'
+        case 'silent': return 'no answer'
+        default: return r.status
+    }
+}