rvlib-shipkit 2.1.1 → 2.3.0

package/src/review/trailer-model.ts

@@ -0,0 +1,183 @@
+// the trailer view's shapes (wiki build/trailer.md, Frame notes): what the hub answers about a repo's cuts, and a frame
+// note as the view shows it, read from its item of the one store. Pure: the routes and the page share them
+import { isFrame, isReply, partyOf, stateOf, type ReviewItem } from './model.ts'
+
+export type NoteState = 'open' | 'done' | 'wontfix'
+
+export interface NotePin {
+    /** 0 to 1 over the frame, from the left and from the top */
+    x: number
+    y: number
+}
+
+/** one note as the view shows it: an item of the one store whose subject is a frame */
+export interface TrailerNote {
+    /** its item's id */
+    id: string
+    /** its number on the trailer, in the order written: the label of its pin */
+    n: number
+    trailer: string
+    cut: string
+    /** seconds on the cut it was written on, the frame's middle */
+    time: number
+    frame: number
+    shot: string
+    /** seconds into the shot */
+    shotTime: number
+    section: string | null
+    text: string
+    pin?: NotePin
+    state: NoteState
+    /** done: the commit or the answer; wontfix: the reason */
+    reply?: string
+    written: string
+    closed?: string
+    /** its still, a file of its item's folder */
+    still: string
+}
+
+/** a frame item as a note: its words and pin are the owner's latest, its state the lifecycle's (fixed is done); null
+ *  when the item is no frame */
+export function noteOf(x: ReviewItem, n: number): TrailerNote | null {
+    const s = x.item.subject
+    if (!isFrame(s)) return null
+    const said = x.thread.filter((m) => partyOf(m.who) === 'owner' && m.op === undefined)
+    const text = said.filter(isReply).at(-1)?.text ?? ''
+    const pinned = said.filter((m) => m.rects !== undefined).at(-1)?.rects?.[0]
+    const st = stateOf(x, false)
+    const closing = st.state === 'closed' ? x.thread.filter((m) => m.op === 'fixed' || m.op === 'wontfix').at(-1) : undefined
+    const first = x.item.views[0]
+    return {
+        id: x.item.id,
+        n,
+        trailer: s.trailer,
+        cut: s.cut,
+        time: s.time,
+        frame: s.frame,
+        shot: s.shot,
+        shotTime: s.shotTime,
+        section: s.section,
+        text,
+        ...(pinned ? { pin: { x: pinned.x, y: pinned.y } } : {}),
+        state: closing?.op === 'wontfix' ? 'wontfix' : closing ? 'done' : 'open',
+        ...(closing?.note ? { reply: closing.note } : {}),
+        written: x.item.created,
+        ...(closing ? { closed: closing.at } : {}),
+        still: first && 'files' in first && 'image' in first.files ? first.files.image : 'image.png',
+    }
+}
+
+/** every frame note of one trailer, numbered in the order written */
+export function notesOf(items: readonly ReviewItem[], trailer: string): TrailerNote[] {
+    return items
+        .filter((x) => isFrame(x.item.subject) && x.item.subject.trailer === trailer)
+        .sort((a, b) => a.item.created.localeCompare(b.item.created))
+        .flatMap((x, i) => noteOf(x, i + 1) ?? [])
+}
+
+export interface CaptionSpan {
+    text: string
+    style: string
+    /** seconds on the cut */
+    start: number
+    end: number
+}
+
+export interface ShotSpan {
+    name: string
+    /** its line in the .trailer file */
+    line: number
+    start: number
+    /** where the next shot starts (the cut's end for the last): the span the timeline draws */
+    end: number
+    /** its whole length, the cut into the next included */
+    length: number
+    section: string | null
+    captions: CaptionSpan[]
+}
+
+export interface SectionSpan {
+    name: string
+    start: number
+    end: number
+}
+
+export interface Timeline {
+    total: number
+    fps: number
+    size: [number, number]
+    shots: ShotSpan[]
+    sections: SectionSpan[]
+}
+
+/** one cut of a trailer folder: a `.trailer` file and its render `out/<name>.mp4`, or a render with no file beside it */
+export interface CutInfo {
+    /** the `.trailer` file's stem, else the render's */
+    cut: string
+    /** the render's stem: the file's `trailer <name>` line */
+    name: string
+    /** repo relative: the render, its strip, its montage page */
+    files: { trailer: string | null; video: string; strip: string; montage: string | null }
+    /** the timeline the render on screen was made from, else the .trailer file's as it stands; null when neither parses */
+    timeline: Timeline | null
+    /** the timeline is the render's own (the file was saved before it) */
+    timelineFromRender: boolean
+    errors: string[]
+    /** the render on screen: its version (mtime in ms), length and rate; null when there is none */
+    video: { mtime: number; duration: number; fps: number } | null
+    /** a new render is being written: `video` is still the last finished one */
+    rendering: boolean
+    /** the .trailer file changed since that render */
+    edited: boolean
+    /** the render's contact strip (one frame a shot, `cols` a row), null when absent or not of this timeline */
+    strip: { cols: number; tileW: number; tileH: number; pad: number } | null
+    /** the .trailer file's mtime in ms, else the render's */
+    fileMtime: number
+    /** a kept version (`versions/<v>.trailer` and `versions/<v>/`): it never changes */
+    version: boolean
+}
+
+export interface TrailerInfo {
+    id: string
+    cuts: CutInfo[]
+    notes: TrailerNote[]
+}
+
+export interface TrailerDesk {
+    trailers: TrailerInfo[]
+}
+
+/** the shot on screen at `t`: the last one started */
+export function shotAt(tl: Pick<Timeline, 'shots'>, t: number): ShotSpan | null {
+    let out: ShotSpan | null = null
+    for (const s of tl.shots) {
+        if (s.start > t + 1e-6) break
+        out = s
+    }
+    return out ?? tl.shots[0] ?? null
+}
+
+/** where a note sits on a cut: its shot's start there plus its time into it, clamped to the shot; null when the shot is
+ *  not in it */
+export function noteTime(n: Pick<TrailerNote, 'shot' | 'shotTime'>, tl: Pick<Timeline, 'shots'>): number | null {
+    const s = tl.shots.find((x) => x.name === n.shot)
+    if (!s) return null
+    return s.start + Math.max(0, Math.min(s.length, n.shotTime))
+}
+
+/** the cuts newest first, by the later of the file's edit and its render; the kept versions after them, newest first too */
+export function cutsByRecent<C extends Pick<CutInfo, 'fileMtime' | 'video' | 'version'>>(cuts: readonly C[]): C[] {
+    const last = (c: C): number => Math.max(c.fileMtime, c.video?.mtime ?? 0)
+    return [...cuts].sort((a, b) => Number(a.version) - Number(b.version) || last(b) - last(a))
+}
+
+/** `m:ss.cc` */
+export function clock(t: number): string {
+    const s = Math.max(0, t)
+    const m = Math.floor(s / 60)
+    const r = s - m * 60
+    return `${m}:${r < 10 ? '0' : ''}${r.toFixed(2)}`
+}
+
+export const TRAILER_ID_RE = /^[a-z0-9][a-z0-9-]*$/
+export const CUT_RE = /^[a-z0-9][a-z0-9-]*$/

package/src/review/trailer-routes.ts

@@ -0,0 +1,136 @@
+// the hub's trailer routes (wiki build/trailer.md, Frame notes): a repo's cuts with their timelines and notes, a kept
+// render with byte ranges, and the owner's frame notes, each an item of the one review store. Paths are relative to the
+// repo hub's base. null: not a path of these
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, relative } from 'node:path'
+import { bad, NO_STORE, ranged } from './http.ts'
+import { ID_RE, isFrame } from './model.ts'
+import { act, appendMessage, deleteRaised, raiseItem, readAllCached, readItem } from './store.ts'
+import { cutOf, frameNote, montagePage, trailerDir, trailerIds, trailerInfo, videoOf, viewStrip, viewVideo } from './trailer-desk.ts'
+import { CUT_RE, noteOf, TRAILER_ID_RE, type NotePin, type NoteState, type TrailerDesk } from './trailer-model.ts'
+
+const clamp = (v: number): number => Number(Math.min(1, Math.max(0, v)).toFixed(4))
+
+const pinOf = (v: unknown): NotePin | undefined => {
+    const p = v as { x?: unknown; y?: unknown } | null | undefined
+    return p && typeof p.x === 'number' && typeof p.y === 'number' ? { x: p.x, y: p.y } : undefined
+}
+
+const STATES: readonly NoteState[] = ['open', 'done', 'wontfix']
+
+/** a note's title in the list: its first words */
+const titleOf = (text: string): string => {
+    const t = text.trim().split('\n')[0] ?? ''
+    return t.length > 80 ? `${t.slice(0, 79).trimEnd()}…` : t
+}
+
+/** the commit the tree stands at, for the record of a note; none when git does not answer */
+function headCommit(root: string): string | undefined {
+    const r = Bun.spawnSync(['git', 'rev-parse', '--short=10', 'HEAD'], { cwd: root, stdout: 'pipe', stderr: 'ignore' })
+    const sha = r.stdout.toString().trim()
+    return r.exitCode === 0 && /^[0-9a-f]{7,40}$/.test(sha) ? sha : undefined
+}
+
+/** a note as the view shows it, after a change: numbered among its trailer's notes */
+function noteAfter(dir: string, nid: string): Response {
+    const x = readItem(dir, nid)
+    if (!x || !isFrame(x.item.subject)) return bad(`no note ${nid}`, 404)
+    const trailer = x.item.subject.trailer
+    const n = readAllCached(dir).items.filter((y) => isFrame(y.item.subject) && y.item.subject.trailer === trailer && y.item.created <= x.item.created).length
+    const note = noteOf(x, Math.max(1, n))
+    return note ? Response.json(note, { headers: NO_STORE }) : bad(`no note ${nid}`, 404)
+}
+
+export async function trailerRoutes(req: Request, path: string, root: string, dir: string): Promise<Response | null> {
+    const API = '/api/trailer'
+    if (path !== API && !path.startsWith(`${API}/`)) return null
+    try {
+        if (path === API && req.method === 'GET') {
+            const desk: TrailerDesk = { trailers: trailerIds(root).flatMap((id) => trailerInfo(root, id) ?? []) }
+            return Response.json(desk, { headers: NO_STORE })
+        }
+        const media = /^\/api\/trailer\/(video|strip)\/([^/]+)\/([^/]+)\/(\d+)\.(mp4|png)$/.exec(path)
+        if (media && req.method === 'GET') {
+            const [, kind, id = '', cut = '', version = ''] = media
+            if (!TRAILER_ID_RE.test(id) || !CUT_RE.test(cut)) return bad(`${path}?`, 404)
+            return ranged(req, kind === 'video' ? viewVideo(root, id, cut, Number(version)) : viewStrip(root, id, cut, Number(version)))
+        }
+        const mont = /^\/api\/trailer\/montage\/([^/]+)\/([^/]+)$/.exec(path)
+        if (mont && req.method === 'GET') {
+            const page = montagePage(root, mont[1] ?? '', mont[2] ?? '')
+            return page === null ? bad('no montage page: sk trailer writes it with the render', 404) : new Response(page, { headers: { 'Content-Type': 'text/markdown; charset=utf-8', ...NO_STORE } })
+        }
+        if (path === `${API}/reveal` && req.method === 'POST') {
+            // the render on screen shown in the Finder, so a cut already on this disk is never downloaded
+            const b = (await req.json()) as Record<string, unknown>
+            const dir = trailerDir(root, String(b.trailer ?? ''))
+            const c = dir ? cutOf(dir, String(b.cut ?? '')) : null
+            if (!dir || !c) return bad(`no cut ${String(b.trailer)}/${String(b.cut)}`, 404)
+            const video = videoOf(dir, c)
+            if (!existsSync(video)) return bad(`${c.cut} is not rendered yet`, 404)
+            if (process.platform !== 'darwin') return bad('the Finder is macOS only', 501)
+            const r = Bun.spawnSync(['open', '-R', video], { stdout: 'ignore', stderr: 'pipe' })
+            if (r.exitCode !== 0) return bad(`open -R: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`, 500)
+            return Response.json({ ok: true, file: relative(root, video) }, { headers: NO_STORE })
+        }
+        if (path === `${API}/notes` && req.method === 'POST') {
+            const b = (await req.json()) as Record<string, unknown>
+            const id = String(b.trailer ?? '')
+            if (!trailerDir(root, id)) return bad(`no trailer ${id}`)
+            const text = String(b.text ?? '')
+            if (text.trim() === '') return bad('a note says something')
+            const pin = pinOf(b.pin)
+            const tmp = mkdtempSync(join(tmpdir(), 'trailer-note-'))
+            try {
+                const still = join(tmp, 'still.png')
+                const subject = await frameNote(root, id, { cut: String(b.cut ?? ''), version: Number(b.version), time: Number(b.time) || 0 }, still)
+                const commit = headCommit(root)
+                const x = await raiseItem(dir, {
+                    subject,
+                    origin: { by: 'owner', from: 'trailer' },
+                    topic: 'film',
+                    title: titleOf(text),
+                    text,
+                    ...(pin ? { rects: [{ x: clamp(pin.x), y: clamp(pin.y), w: 0, h: 0, comment: '' }] } : {}),
+                    image: still,
+                    ...(commit ? { commit } : {}),
+                })
+                return noteAfter(dir, x.item.id)
+            } finally {
+                rmSync(tmp, { recursive: true, force: true })
+            }
+        }
+        const one = /^\/api\/trailer\/notes\/([^/]+)\/([^/]+)$/.exec(path)
+        if (one) {
+            const [, id = '', nid = ''] = one
+            const x = trailerDir(root, id) && ID_RE.test(nid) ? readItem(dir, nid) : null
+            if (!x || !isFrame(x.item.subject) || x.item.subject.trailer !== id) return bad(`no note ${id}/${nid}`, 404)
+            if (req.method === 'DELETE') {
+                deleteRaised(dir, nid)
+                return Response.json({ ok: true }, { headers: NO_STORE })
+            }
+            if (req.method !== 'POST') return null
+            const b = (await req.json()) as Record<string, unknown>
+            if (typeof b.state === 'string' && !STATES.includes(b.state as NoteState)) return bad(`state ${b.state}?`)
+            const text = typeof b.text === 'string' ? b.text.trim() : undefined
+            if (text === '') return bad('a note says something')
+            const pin = b.pin === null ? null : pinOf(b.pin)
+            if (text !== undefined || pin !== undefined)
+                appendMessage(dir, nid, {
+                    who: 'owner',
+                    ...(text !== undefined ? { text } : {}),
+                    ...(pin !== undefined ? { rects: pin ? [{ x: clamp(pin.x), y: clamp(pin.y), w: 0, h: 0, comment: '' }] : [] } : {}),
+                })
+            const reply = typeof b.reply === 'string' ? b.reply : undefined
+            if (b.state === 'open') act(dir, nid, 'reopen', 'owner')
+            else if (b.state === 'done') act(dir, nid, 'fixed', 'owner', reply?.trim() ? { note: reply } : {})
+            else if (b.state === 'wontfix') act(dir, nid, 'wontfix', 'owner', { note: reply?.trim() || 'not done' })
+            return noteAfter(dir, nid)
+        }
+        return bad(`${req.method} ${path}?`, 404)
+    } catch (e) {
+        console.error(`FAIL: ${req.method} ${path}: ${(e as Error).message}`)
+        return bad(e)
+    }
+}

package/src/review/unit.ts

@@ -0,0 +1,165 @@
+// a repo's parts of the one store (wiki build/shipkit/review.md, A project's parts): its subject kinds, topics, sources,
+// auto rules and the dispatcher switch, declared once in a `review({...})` unit of any `<name>.shipkit.ts`. Every unit
+// file imports this module, so it stays light: the store reads the pure part through specOf(dir), project.ts finds,
+// imports and serves the rest
+import { AGENT_RE, type ReviewItem, type ReviewMark, type Spec, type SpecKind, type SpecTopic, type Subject } from './model.ts'
+import type { AddInput, ViewInput } from './store.ts'
+
+/** one line of a kind's data view: a fact the hub and `show` print */
+export interface Fact {
+    label: string
+    value: string
+}
+
+/** a link the hub opens */
+export interface Link {
+    label: string
+    url: string
+}
+
+/** a text the hub shows, or a change of one shown as a diff */
+export type ViewText = { text: string } | { before: string; after: string }
+
+/** one subject kind: its words, its key, near rule and problems (the model's), and its data view, all server side */
+export interface KindDef<S extends Subject = Subject> extends SpecKind {
+    key?(s: S): string | null
+    near?(a: S, b: S): boolean
+    problems?(s: S): string[]
+    facts?(x: ReviewItem): Fact[]
+    links?(x: ReviewItem): Link[]
+    /** a url the hub opens in a frame: the subject live */
+    live?(x: ReviewItem): string | null
+    text?(x: ReviewItem): ViewText | null
+    /** the `sk review add` flags this kind reads, each with its help line: `--where <zone>:<x>,<y>` */
+    flags?: Record<string, string>
+    /** the subject (and its topic) a card of this kind gets from those flags, every flag as the list of its values;
+     *  throws with the reason a flag is wrong */
+    parse?(flags: Record<string, string[]>): { subject: S; topic?: string }
+}
+
+/** what a rule or a source raises: an item to a lane, open from the start; `key` names what it is about */
+export interface Raise {
+    title: string
+    what: string
+    lane: string
+    subject: Subject
+    key?: string
+}
+
+export interface AutoCtx {
+    items: readonly ReviewItem[]
+    now: Date
+}
+
+/** a rule on a clock: its answer is raised as an item, one open item a rule and key */
+export interface AutoRule {
+    id: string
+    every: `${number}m`
+    when(ctx: AutoCtx): Raise | readonly Raise[] | null
+}
+
+/** what the repo adds to a view: its rings, the review light */
+export interface ViewExtra {
+    marks?: ReviewMark[]
+    light?: 'review'
+}
+
+/** what a verb of the repo gets: its store and root, and its two outputs */
+export interface VerbCtx {
+    dir: string
+    root: string
+    say(line: string): void
+    err(line: string): void
+}
+
+/** the live shots a draft card follows: its frames now, and the shot stopped when the card is ready */
+export interface LiveShots {
+    frames(name: string): { image: string; history: { file: string; label: string }[] }
+    stop?(name: string, why: string): void
+}
+
+/** where items come from beyond this machine: `pull` writes each new one through raiseItem and returns their ids */
+export interface ReviewSource {
+    id: string
+    pull(o: { dir: string; items: readonly ReviewItem[]; say: (line: string) => void }): Promise<string[]>
+    /** a test report deleted at its source; the store's folder goes after it */
+    remove?(x: ReviewItem): Promise<void>
+    /** what `show` prints of an item this source raised, beyond its words */
+    facts?(x: ReviewItem): Fact[]
+}
+
+export interface ReviewDef {
+    kinds?: Record<string, KindDef>
+    topics?: Record<string, SpecTopic>
+    dispatcher?: boolean
+    sources?: readonly ReviewSource[]
+    auto?: readonly AutoRule[]
+    /** a repo relative font file the animation's labels are drawn in */
+    anim?: { font?: string }
+    /** the `sk review add` and `add-view` flags of any kind (a ring over the subject), each with its help line */
+    flags?: Record<string, string>
+    /** what the repo checks and fills on a card before it is written (marks read from its own shots, the review light,
+     *  a lane from a commit, a refused contact sheet); throws to refuse it */
+    add?(input: AddInput, flags: Record<string, string[]>): AddInput | Promise<AddInput>
+    /** the same on a view added to an open card */
+    addView?(view: ViewInput, flags: Record<string, string[]>): ViewExtra | Promise<ViewExtra>
+    /** a draft card's live shots: `sk review add --wip --live <name>`, `ready` stops the shot */
+    live?: LiveShots
+    /** the repo's own verbs under `sk review <verb>`: a report replayed in the game, the town composer */
+    verbs?: Record<string, { description: string; usage?: string; run(args: string[], ctx: VerbCtx): number | Promise<number> }>
+}
+
+export type ReviewUnit = ReviewDef & { kind: 'review' }
+
+const WORD = /^[a-z][a-z0-9-]*$/
+
+/** why a review unit cannot be read, or null */
+export function reviewProblem(d: ReviewDef): string | null {
+    for (const [k, v] of Object.entries(d.kinds ?? {})) {
+        if (!WORD.test(k)) return `review: kind '${k}' is a lowercase word`
+        if (typeof v.label !== 'string' || v.label.trim() === '') return `review: kind '${k}' has its label`
+        for (const f of ['key', 'near', 'problems', 'facts', 'links', 'live', 'text'] as const)
+            if (v[f] !== undefined && typeof v[f] !== 'function') return `review: kind '${k}'.${f} is a function`
+    }
+    for (const [k, v] of Object.entries(d.topics ?? {})) {
+        if (!WORD.test(k)) return `review: topic '${k}' is a lowercase word`
+        if (typeof v.label !== 'string' || v.label.trim() === '') return `review: topic '${k}' has its label`
+    }
+    const ids = new Set<string>()
+    for (const r of d.auto ?? []) {
+        if (!AGENT_RE.test(r.id ?? '')) return `review: auto rule '${String(r.id)}' is a word (${AGENT_RE.source})`
+        if (ids.has(r.id)) return `review: two auto rules named '${r.id}'`
+        ids.add(r.id)
+        if (!/^\d+(\.\d+)?m$/.test(r.every ?? '')) return `review: auto rule '${r.id}' runs every '<minutes>m', like '10m'`
+        if (typeof r.when !== 'function') return `review: auto rule '${r.id}'.when is a function`
+    }
+    const core = new Set(['ls', 'add', 'add-view', 'show', 'inbox', 'seen', 'reply', 'withdraw', 'reopen', 'fixed', 'wontfix', 'claim', 'release', 'blocked', 'done', 'dispatcher', 'dispatch', 'ask', 'drop', 'reassign', 'next', 'topics', 'board', 'ready', 'delete', 'marks', 'anim', 'auto', 'watch'])
+    for (const [v, def] of Object.entries(d.verbs ?? {})) {
+        if (!WORD.test(v)) return `review: verb '${v}' is a lowercase word`
+        if (core.has(v)) return `review: verb '${v}' is one of sk review's own`
+        if (typeof def.run !== 'function') return `review: verb '${v}'.run is a function`
+    }
+    for (const [k, v] of Object.entries(d.kinds ?? {})) if (v.flags && typeof v.parse !== 'function') return `review: kind '${k}' reads flags, so it has a parse`
+    if (d.live && typeof d.live.frames !== 'function') return 'review: live.frames is a function'
+    for (const s of d.sources ?? []) {
+        if (!AGENT_RE.test(s.id ?? '')) return `review: source '${String(s.id)}' is a word`
+        if (typeof s.pull !== 'function') return `review: source '${s.id}'.pull is a function`
+    }
+    return null
+}
+
+export function review(d: ReviewDef): ReviewUnit {
+    const why = reviewProblem(d)
+    if (why !== null) throw new Error(why)
+    return { ...d, kind: 'review' }
+}
+
+/** the model's part of a unit: its kinds, topics and dispatcher switch */
+export const specOfUnit = (u: ReviewDef | null): Spec => ({ kinds: u?.kinds ?? {}, topics: u?.topics ?? {}, dispatcher: u?.dispatcher === true })
+
+/** the words of a spec the browser reads: no function crosses */
+export const specData = (spec: Spec): Spec => ({
+    kinds: Object.fromEntries(Object.entries(spec.kinds).map(([k, v]) => [k, { label: v.label, ...(v.icon ? { icon: v.icon } : {}) }])),
+    topics: spec.topics,
+    dispatcher: spec.dispatcher,
+})

package/src/review/watchers.ts

@@ -0,0 +1,54 @@
+// who listens: each `sk review watch` registers one file per process beside the store (`.shipkit/review-watchers/`),
+// out of its watch, so a registration never wakes the watchers. A file alone is never trusted: its pid is probed
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { WatchFilter, Watcher } from './model.ts'
+
+const watchersDir = (dir: string): string => join(dir, '..', 'review-watchers')
+
+/** the process is there: a signal 0 reaches it, or it exists under another user */
+export function pidAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (e) {
+        return (e as NodeJS.ErrnoException).code === 'EPERM'
+    }
+}
+
+/** this process watches what `filter` keeps until it exits: its file goes on exit and on a signal */
+export function registerWatch(dir: string, filter: WatchFilter, now = new Date()): void {
+    const folder = watchersDir(dir)
+    mkdirSync(folder, { recursive: true })
+    const file = join(folder, `${process.pid}.json`)
+    const w: Watcher = { pid: process.pid, session: filter.session, lane: filter.lane, started: now.toISOString() }
+    writeFileSync(`${file}.tmp`, `${JSON.stringify(w)}\n`)
+    renameSync(`${file}.tmp`, file)
+    const gone = (): void => rmSync(file, { force: true })
+    process.on('exit', gone)
+    for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP'] as const)
+        process.on(sig, () => {
+            gone()
+            process.exit(0)
+        })
+}
+
+/** every live watcher, by pid; a file whose process is gone is deleted */
+export function liveWatchers(dir: string, alive: (pid: number) => boolean = pidAlive): Watcher[] {
+    const folder = watchersDir(dir)
+    if (!existsSync(folder)) return []
+    const out: Watcher[] = []
+    for (const name of readdirSync(folder)) {
+        if (!name.endsWith('.json')) continue
+        const file = join(folder, name)
+        let w: Watcher | null = null
+        try {
+            w = JSON.parse(readFileSync(file, 'utf8')) as Watcher
+        } catch {
+            w = null
+        }
+        if (w && Number.isInteger(w.pid) && alive(w.pid)) out.push({ pid: w.pid, session: w.session ?? null, lane: w.lane ?? null, started: w.started })
+        else rmSync(file, { force: true })
+    }
+    return out.sort((a, b) => a.pid - b.pid)
+}