rvlib-shipkit 1.1.0 → 1.2.0

package/src/core/job-follow.ts

@@ -0,0 +1,102 @@
+// following a detached gate job from its folder (jobs.ts): its wire lines as
+// out.log grows, its verdicts as checks.ndjson grows, then its exit code. The
+// daemon follows every job it starts, and every job still running when a new
+// image of it boots; a terminal whose stream the daemon cut follows the rest
+// of its job here, from the line it had reached.
+//
+// the one constraint a reader breaks first: the verdict is exit.json, never
+// the pid. A pid can outlive its job as a zombie nobody reaps, and a job can
+// write exit.json a moment before its pid goes, so the folder is drained once
+// more after either.
+import { closeSync, openSync, readSync } from 'fs'
+import type { CheckEvent } from './check-runner.ts'
+import { jobAlive, jobChecks, jobOut, readExit, readJob } from './jobs.ts'
+
+export type FollowTap = { line: (l: string) => void; check?: (e: CheckEvent) => void }
+
+/** one file read from a byte offset, one complete line at a time */
+class Tail {
+    private at = 0
+    private partial = ''
+    constructor(private path: string) {}
+
+    lines(): string[] {
+        let fd: number
+        try { fd = openSync(this.path, 'r') } catch { return [] }
+        const chunks: string[] = []
+        try {
+            const buf = Buffer.alloc(64 * 1024)
+            for (;;) {
+                const n = readSync(fd, buf, 0, buf.length, this.at)
+                if (n <= 0) break
+                this.at += n
+                chunks.push(buf.subarray(0, n).toString('utf8'))
+            }
+        } finally { closeSync(fd) }
+        if (chunks.length === 0) return []
+        const all = (this.partial + chunks.join('')).split('\n')
+        this.partial = all.pop() ?? ''
+        return all
+    }
+
+    /** what is left once the writer is gone: a last line with no newline */
+    rest(): string[] {
+        const out = this.lines()
+        if (this.partial !== '') out.push(this.partial)
+        this.partial = ''
+        return out
+    }
+}
+
+export type FollowOpts = {
+    /** out.log lines already delivered elsewhere, skipped here */
+    skipLines?: number
+    pollMs?: number
+    /** how often the pid is asked whether it still runs (it costs a ps) */
+    aliveEveryMs?: number
+    alive?: (pid: number) => boolean
+    sleep?: (ms: number) => Promise<void>
+    /** stop following early (the tab went away); resolves null */
+    abort?: () => boolean
+}
+
+/** the job's exit code once it has one, 1 for a job that died without one,
+ *  null when abort said stop */
+export async function followJob(root: string, id: string, tap: FollowTap, o: FollowOpts = {}): Promise<number | null> {
+    const out = new Tail(jobOut(root, id))
+    const checks = new Tail(jobChecks(root, id))
+    const sleep = o.sleep ?? Bun.sleep
+    const isAlive = o.alive ?? jobAlive
+    let skip = o.skipLines ?? 0
+    const drain = (end: boolean): void => {
+        for (const l of end ? out.rest() : out.lines()) {
+            if (skip > 0) { skip--; continue }
+            tap.line(l)
+        }
+        for (const l of end ? checks.rest() : checks.lines()) {
+            if (l === '' || tap.check == null) continue
+            try { tap.check(JSON.parse(l) as CheckEvent) } catch { /* a torn line: the ledger has the verdict */ }
+        }
+    }
+    let lastAlive = 0
+    for (;;) {
+        drain(false)
+        const exit = readExit(root, id)
+        if (exit != null) { drain(true); return exit.code }
+        if (o.abort?.() === true) return null
+        const now = Date.now()
+        if (now - lastAlive >= (o.aliveEveryMs ?? 1_000)) {
+            lastAlive = now
+            const job = readJob(root, id)
+            if (job == null || !isAlive(job.pid)) {
+                // it may have written its verdict between the two reads
+                const late = readExit(root, id)
+                drain(true)
+                if (late != null) return late.code
+                tap.line(`FAIL: gate job ${id} died without a verdict (pid ${job?.pid ?? '?'} is gone)`)
+                return 1
+            }
+        }
+        await sleep(o.pollMs ?? 100)
+    }
+}

package/src/core/job-run.ts

@@ -0,0 +1,27 @@
+// the inside of a gate job the daemon started (jobs.ts startJob): the run's
+// options come from the job folder rather than from flags, every verdict is
+// appended to checks.ndjson for whoever follows it, and a background run takes
+// the machine's one background turn here, so the turn outlives a daemon
+// reload the same as the run does.
+import { basename } from 'path'
+import { useOneLib } from './one-lib.ts'
+import { appendJobCheck, type JobKind, type JobOpts } from './jobs.ts'
+import { autoGatePool, takeSlot } from './slots.ts'
+import type { CheckEvent } from './check-runner.ts'
+
+export async function runJob(root: string, id: string, kind: JobKind, job: JobOpts, print: (l: string) => void): Promise<number> {
+    // before the repo config loads: it imports this copy of the lib, never its own install
+    if (job.oneLib === true) useOneLib()
+    const turn = job.turn === true ? await takeSlot(autoGatePool(), { repo: basename(root), check: 'auto gate' }, { pollMs: 250 }) : null
+    try {
+        const onCheck = (e: CheckEvent): void => appendJobCheck(root, id, e)
+        if (kind === 'ci') {
+            const { runCi } = await import('./run-ci.ts')
+            return await runCi(root, { ...job.opts, print, onCheck })
+        }
+        const { runCheck } = await import('./run-check.ts')
+        return await runCheck(root, { ...job.opts, print, onCheck })
+    } finally {
+        turn?.release()
+    }
+}

package/src/core/jobs.ts

@@ -1,13 +1,17 @@
 // DETACHED GATES: `shipkit ci --detach` starts an ordinary gate in the
-// background and hands back a run id, `shipkit status [id]` reads it back.
+// background and hands back a run id, `shipkit status [id]` reads it back. The
+// daemon runs every gate of its repos the same way (job-follow.ts), so a
+// daemon reload never kills one.
 //
 // The background process OWNS NOTHING. It is the same gate a terminal runs,
 // its answers land in the same ledger and its cost in the same run record;
 // this module only remembers where its output went and how it ended, in
 // `.shipkit/tmp/shipkit-jobs/<id>/`: `job.json` (who, what, when), `out.log` (its
-// wire lines as it prints them) and `exit.json` (the verdict, once).
+// wire lines as it prints them), `checks.ndjson` (one verdict per line, for a
+// job the daemon started), `opts.json` (the run's options, same) and
+// `exit.json` (the verdict, once).
 import { spawn } from 'child_process'
-import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync } from 'fs'
 import { join } from 'path'
 import { LAYOUT } from './layout.ts'
 import { atomicWrite } from './locked-write.ts'
@@ -16,16 +20,22 @@ import { fmtStamp } from './wire.ts'
 /** status exit code while the run has no verdict yet */
 export const STILL_RUNNING = 3
 
-type Job = { id: string; pid: number; args: string[]; startedAt: number }
-type Exit = { code: number; finishedAt: number }
+export type JobKind = 'ci' | 'check'
+export type Job = { id: string; pid: number; args: string[]; startedAt: number; kind?: JobKind }
+export type Exit = { code: number; finishedAt: number }
 
-const JOBS = `${LAYOUT.tmp}/shipkit-jobs`
+export const JOBS = `${LAYOUT.tmp}/shipkit-jobs`
 /** how long a finished run stays readable */
-const KEEP_MS = 7 * 24 * 60 * 60 * 1000
+export const JOBS_KEEP_MS = 7 * 24 * 60 * 60 * 1000
+/** the most finished runs kept, newest first */
+export const JOBS_MAX = 100
 
-const ciLine = (args: string[]): string => ['shipkit ci', ...args].join(' ')
+const ciLine = (args: string[], kind: JobKind = 'ci'): string => [`shipkit ${kind}`, ...args].join(' ')
 
-export const jobDir =(root: string, id: string): string => join(root, JOBS, id)
+export const jobDir = (root: string, id: string): string => join(root, JOBS, id)
+export const jobOut = (root: string, id: string): string => join(jobDir(root, id), 'out.log')
+export const jobChecks = (root: string, id: string): string => join(jobDir(root, id), 'checks.ndjson')
+const jobOpts = (root: string, id: string): string => join(jobDir(root, id), 'opts.json')
 
 const readJson = <T>(p: string): T | null => {
     try { return JSON.parse(readFileSync(p, 'utf8')) as T } catch { return null }
@@ -35,19 +45,41 @@ const alive = (pid: number): boolean => {
     try { process.kill(pid, 0); return true } catch (e) { return (e as { code?: string }).code === 'EPERM' }
 }
 
-/** start `shipkit ci <args> --job <id>` detached from this process and its
- *  terminal, and return at once */
-export function startDetached(root: string, o: { cli: string; args: string[] }): { id: string; pid: number; lines: string[] } {
+/** alive and not a zombie: a job the daemon started and never reaps (its
+ *  previous image did) stays in the process table after it exits */
+export function jobAlive(pid: number): boolean {
+    if (pid <= 0 || !alive(pid)) return false
+    const st = Bun.spawnSync(['ps', '-o', 'stat=', '-p', String(pid)]).stdout.toString().trim()
+    return st !== '' && !st.startsWith('Z')
+}
+
+let seq = 0
+
+/** what a job the daemon starts carries beside its flags: the run's options
+ *  as the runner takes them, one lib copy for the repo config, and the
+ *  machine's one background turn for a run nobody waits on */
+export type JobOpts = { opts: Record<string, unknown>; oneLib?: boolean; turn?: boolean }
+
+/** start `shipkit <kind> <args> --job <id>` detached from this process and
+ *  its terminal, and return at once */
+export function startJob(root: string, o: { cli: string; kind: JobKind; args: string[]; job?: JobOpts }): { id: string; pid: number } {
     sweepJobs(root)
-    const id = `ci-${Date.now().toString(36)}-${process.pid.toString(36)}`
+    const id = `${o.kind}-${Date.now().toString(36)}-${process.pid.toString(36)}${(seq++).toString(36)}`
     const dir = jobDir(root, id)
     mkdirSync(dir, { recursive: true })
+    if (o.job != null) atomicWrite(jobOpts(root, id), JSON.stringify(o.job))
     const out = openSync(join(dir, 'out.log'), 'a')
-    const child = spawn(process.execPath, [o.cli, 'ci', ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: process.env })
+    const child = spawn(process.execPath, [o.cli, o.kind, ...o.args, '--job', id], { cwd: root, detached: true, stdio: ['ignore', out, out], env: process.env })
     closeSync(out)
     child.unref()
     const pid = child.pid ?? 0
-    atomicWrite(join(dir, 'job.json'), JSON.stringify({ id, pid, args: o.args, startedAt: Date.now() } satisfies Job))
+    atomicWrite(join(dir, 'job.json'), JSON.stringify({ id, pid, args: o.args, startedAt: Date.now(), kind: o.kind } satisfies Job))
+    return { id, pid }
+}
+
+/** `shipkit ci --detach`: a job, and the two lines that say how to read it back */
+export function startDetached(root: string, o: { cli: string; args: string[] }): { id: string; pid: number; lines: string[] } {
+    const { id, pid } = startJob(root, { cli: o.cli, kind: 'ci', args: o.args })
     return {
         id,
         pid,
@@ -58,6 +90,30 @@ export function startDetached(root: string, o: { cli: string; args: string[] }):
     }
 }
 
+/** the options a daemon job was started with, null for a `--detach` one */
+export const readJobOpts = (root: string, id: string): JobOpts | null => readJson<JobOpts>(jobOpts(root, id))
+
+/** one verdict of the job, for whoever follows it */
+export function appendJobCheck(root: string, id: string, e: unknown): void {
+    try { appendFileSync(jobChecks(root, id), `${JSON.stringify(e)}\n`) } catch { /* the folder was swept: the verdict is in the ledger anyway */ }
+}
+
+export const readJob = (root: string, id: string): Job | null => readJson<Job>(join(jobDir(root, id), 'job.json'))
+export const readExit = (root: string, id: string): Exit | null => readJson<Exit>(join(jobDir(root, id), 'exit.json'))
+
+/** the jobs of this checkout still running: started, no verdict, pid alive */
+export function liveJobs(root: string): Job[] {
+    const out: Job[] = []
+    try {
+        for (const name of readdirSync(join(root, JOBS))) {
+            const j = readJob(root, name)
+            if (j == null || existsSync(join(root, JOBS, name, 'exit.json')) || !jobAlive(j.pid)) continue
+            out.push(j)
+        }
+    } catch { /* no jobs yet */ }
+    return out.sort((a, b) => a.startedAt - b.startedAt)
+}
+
 /** the detached gate records how it ended. Called by the gate itself. */
 export function recordExit(root: string, id: string, code: number): void {
     const dir = jobDir(root, id)
@@ -85,7 +141,7 @@ export function jobStatus(root: string, id?: string): { code: number; lines: str
     const dir = jobDir(root, want)
     const job = readJson<Job>(join(dir, 'job.json'))
     if (job == null) return { code: 2, lines: [`FAIL: no detached run '${want}' in this checkout`, `      fix: shipkit status (no id) shows the latest one`] }
-    const lines = [`ok: run ${job.id}: ${ciLine(job.args)} (pid ${job.pid}, started ${fmtStamp(job.startedAt)})`]
+    const lines = [`ok: run ${job.id}: ${ciLine(job.args, job.kind)} (pid ${job.pid}, started ${fmtStamp(job.startedAt)})`]
     let out = ''
     try { out = readFileSync(join(dir, 'out.log'), 'utf8') } catch { /* nothing printed yet */ }
     lines.push(...out.split('\n').filter((l) => l !== ''))
@@ -97,22 +153,26 @@ export function jobStatus(root: string, id?: string): { code: number; lines: str
     }
     // it may have written its verdict between the two reads
     e ??= exit()
-    if (e == null) return { code: 1, lines: [...lines, `FAIL: run ${job.id} died without a verdict (pid ${job.pid} is gone)`, `      fix: ${ciLine(job.args)}`] }
+    if (e == null) return { code: 1, lines: [...lines, `FAIL: run ${job.id} died without a verdict (pid ${job.pid} is gone)`, `      fix: ${ciLine(job.args, job.kind)}`] }
     const took = `${((e.finishedAt - job.startedAt) / 1000).toFixed(1)}s`
     lines.push(e.code === 0 ? `ok: run ${job.id} finished green in ${took}` : `FAIL: run ${job.id} finished red (exit ${e.code}) in ${took}`)
     return { code: e.code, lines }
 }
 
-/** finished runs older than a week go; a running one never does */
-function sweepJobs(root: string): void {
+/** finished runs older than a week go, then the oldest past the count cap;
+ *  a running one never does */
+export function sweepJobs(root: string, now = Date.now(), o: { keepMs?: number; max?: number } = {}): void {
     const base = join(root, JOBS)
+    let dirs: { dir: string; mtime: number }[]
     try {
-        for (const name of readdirSync(base)) {
-            const dir = join(base, name)
-            const j = readJson<Job>(join(dir, 'job.json'))
-            try { if (statSync(dir).mtimeMs > Date.now() - KEEP_MS) continue } catch { continue }
-            if (j != null && alive(j.pid)) continue
-            rmSync(dir, { recursive: true, force: true })
-        }
-    } catch { /* no jobs yet: nothing to sweep */ }
+        dirs = readdirSync(base).flatMap((name) => {
+            try { return [{ dir: join(base, name), mtime: statSync(join(base, name)).mtimeMs }] } catch { return [] }
+        })
+    } catch { return /* no jobs yet: nothing to sweep */ }
+    dirs.sort((a, b) => b.mtime - a.mtime).forEach((d, i) => {
+        if (d.mtime > now - (o.keepMs ?? JOBS_KEEP_MS) && i < (o.max ?? JOBS_MAX)) return
+        const j = readJson<Job>(join(d.dir, 'job.json'))
+        if (j != null && alive(j.pid)) return
+        try { rmSync(d.dir, { recursive: true, force: true }) } catch { /* raced: gone either way */ }
+    })
 }

package/src/core/legacy-shapes.ts

@@ -17,6 +17,7 @@
 // It reads ONLY through the check context it is handed, so SK016 is cached
 // on the listing of check files and their sources.
 import { basename, join, relative, resolve } from 'path'
+import { statementEnd } from './statement-end.ts'
 import { fallbackNames, isCheckFilePath, readLegacyCheck, type LegacyCheck } from './check-file-names.ts'
 import type { ScanCtx } from './check-ctx.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -177,20 +178,6 @@ export const checkFileName = (id: string): string => `${id.replace(/[^A-Za-z0-9.
 
 // ── editing repo.config.ts ───────────────────────────────────────────────
 
-/** a statement that starts on `i`, ending where its brackets balance and the
- *  line is not obviously continued. Deliberately simple: anything it cannot
- *  read lands as a hand pass rather than as a half rewritten config. */
-function statementEnd(lines: string[], i: number): number {
-    let depth = 0
-    for (let j = i; j < lines.length; j++) {
-        for (const ch of lines[j]!) {
-            if (ch === '(' || ch === '[' || ch === '{') depth++
-            else if (ch === ')' || ch === ']' || ch === '}') depth--
-        }
-        if (depth <= 0) return j
-    }
-    return lines.length - 1
-}
 
 /** the config text without one top level key, its trailing comma and the
  *  comment block written above it. Null when the key is not there, or when it

package/src/core/machine-db.ts

@@ -0,0 +1,83 @@
+// THE MACHINE DB: what shipkit remembers about this machine, whatever repo
+// asks, in one sqlite file: pm's children and resources (their pid records),
+// the repos flagged active, the rail order, the self update answer, the
+// instance registry. One `state` table of named json values.
+//
+// The one constraint a reader breaks first: a failure reads as "nothing
+// remembered", and every caller treats that as the safe side (no adoption,
+// no replay, the pid rule). Slot LOCKS are not here: they are leases a dead
+// pid must release at once, which a file does and a row does not.
+import { Database } from 'bun:sqlite'
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { ensureWal } from '../ledger/db.ts'
+
+export const MACHINE_DB_ENV = 'SHIPKIT_MACHINE_DB'
+
+/** `~/.config/shipkit/shipkit.sqlite`; beside a moved home dir when one is
+ *  set, so a smoke or a suite with its own home never touches the real one */
+export function machineDbPath(): string {
+    const env = process.env[MACHINE_DB_ENV]
+    if (env != null && env !== '') return env
+    const home = process.env.SHIPKIT_HOME_DIR
+    if (home != null && home !== '') return join(home, 'machine.sqlite')
+    return join(homedir(), '.config', 'shipkit', 'shipkit.sqlite')
+}
+
+/** a machine write waits this long on another process's */
+const BUSY_MS = 2_000
+
+const SCHEMA = 'create table if not exists state (name text primary key, value text not null, at integer not null)'
+
+function withMachine<R>(body: (db: Database) => R, path = machineDbPath()): R | null {
+    let db: Database | null = null
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        db = new Database(path, { create: true, readwrite: true })
+        db.exec(`pragma busy_timeout = ${BUSY_MS}`)
+        ensureWal(db, BUSY_MS)
+        db.exec(SCHEMA)
+        return body(db)
+    } catch {
+        return null
+    } finally {
+        try { db?.close() } catch { /* never opened */ }
+    }
+}
+
+export function machineGet<T>(name: string): T | null {
+    const row = withMachine((db) => db.query('select value from state where name = ?').get(name) as { value: string } | null)
+    if (row == null) return null
+    try { return JSON.parse(row.value) as T } catch { return null }
+}
+
+export function machineSet(name: string, value: unknown): boolean {
+    return withMachine((db) => {
+        db.query('insert or replace into state (name, value, at) values (?, ?, ?)').run(name, JSON.stringify(value), Date.now())
+        return true
+    }) ?? false
+}
+
+export function machineDelete(name: string): void {
+    withMachine((db) => db.query('delete from state where name = ?').run(name))
+}
+
+/** every value whose name starts with `prefix` */
+export function machineList<T>(prefix: string): { name: string; value: T; at: number }[] {
+    const rows = withMachine((db) => db.query('select name, value, at from state where substr(name, 1, ?) = ?').all(prefix.length, prefix) as { name: string; value: string; at: number }[]) ?? []
+    return rows.flatMap((r) => {
+        try { return [{ name: r.name, value: JSON.parse(r.value) as T, at: r.at }] } catch { return [] }
+    })
+}
+
+/** the migration of one json file: its value becomes the row, then the file
+ *  goes. Only when the row does not exist yet, so a file an older copy wrote
+ *  after the move never overwrites a newer row */
+export function importMachineFile<T>(name: string, file: string, parse: (text: string) => T = (t) => JSON.parse(t) as T): void {
+    if (!existsSync(file)) return
+    try {
+        if (machineGet(name) == null) machineSet(name, parse(readFileSync(file, 'utf8')))
+        rmSync(file, { force: true })
+    } catch { /* an unreadable file is left for a person to look at */ }
+}

package/src/core/one-lib.ts

@@ -0,0 +1,85 @@
+// one copy of the toolkit per process: a process that loads several repos
+// (the home) makes every `rvlib-shipkit` import, from any repo config or check
+// file, land on its OWN copy. A repo's install is never loaded, so there is one
+// module instance per lib file: one mobx, one class identity, one version.
+//
+// the one constraint a reader breaks first: register it BEFORE the first repo
+// config is imported. A module already loaded keeps the copy it resolved.
+import { readFileSync, realpathSync } from 'fs'
+import { extname, join } from 'path'
+import { LIB_ROOT } from './lib-root.ts'
+
+const NAME = 'rvlib-shipkit'
+
+type Exports = Record<string, string>
+
+const readExports = (root: string): Exports => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { exports?: Exports }
+        return pkg.exports ?? { '.': './src/shipkit.ts' }
+    } catch {
+        return { '.': './src/shipkit.ts' }
+    }
+}
+
+/** the file a specifier names inside `root`, through its package exports
+ *  (`.`, `./contracts`, `./src/*`), or null when it is not this package */
+export function libTarget(spec: string, root: string = LIB_ROOT, exports: Exports = readExports(root)): string | null {
+    if (spec !== NAME && !spec.startsWith(`${NAME}/`)) return null
+    const sub = `.${spec.slice(NAME.length)}`
+    const exact = exports[sub]
+    if (exact != null) return join(root, exact)
+    for (const [k, v] of Object.entries(exports)) {
+        if (!k.endsWith('/*') || !sub.startsWith(k.slice(0, -1))) continue
+        return join(root, v.slice(0, -1) + sub.slice(k.length - 1))
+    }
+    return join(root, sub)
+}
+
+/** a file of ANOTHER copy of the package (a repo's node_modules, bun's
+ *  install cache), as the path inside that copy, else null */
+export function foreignLibPath(path: string, root: string = LIB_ROOT): string | null {
+    const m = /\/(?:node_modules\/rvlib-shipkit|install\/cache\/rvlib-shipkit@[^/]*)\/(.+)$/.exec(path)
+    if (m == null) return null
+    const own = real(root)
+    if (path.startsWith(`${root}/`) || real(path).startsWith(`${own}/`)) return null
+    return m[1]!
+}
+
+const real = (p: string): string => {
+    try {
+        return realpathSync(p)
+    } catch {
+        return p
+    }
+}
+
+const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = { '.ts': 'ts', '.tsx': 'tsx', '.js': 'js', '.mjs': 'js', '.jsx': 'jsx' }
+
+let installed = false
+
+/** route every import of the package to this process's copy. Idempotent */
+export function useOneLib(root: string = LIB_ROOT): void {
+    if (installed) return
+    installed = true
+    const exports = readExports(root)
+    Bun.plugin({
+        name: 'shipkit-one-lib',
+        setup(build) {
+            // a subpath is resolved here, before any other copy is looked at
+            build.onResolve({ filter: /^rvlib-shipkit\// }, (a) => {
+                const path = libTarget(a.path, root, exports)
+                return path == null ? undefined : { path }
+            })
+            // the bare name never reaches onResolve at runtime, so the file
+            // another copy resolved to is loaded as a re-export of ours
+            build.onLoad({ filter: /\/(node_modules\/rvlib-shipkit|install\/cache\/rvlib-shipkit@[^/]*)\// }, (a) => {
+                const loader = LOADERS[extname(a.path)] ?? 'ts'
+                const sub = foreignLibPath(a.path, root)
+                if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader }
+                const target = JSON.stringify(join(root, sub))
+                return { contents: `export * from ${target}\nimport * as own from ${target}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+            })
+        },
+    })
+}

package/src/core/port-holders.ts

@@ -0,0 +1,43 @@
+// who holds a local tcp port, and the process group a pid runs in: what a
+// takeover of a server started elsewhere needs to stop it. Unreadable (no
+// lsof, no ps) means an empty answer, never a throw.
+import { existsSync } from 'fs'
+
+/** the pids LISTENING on a tcp port, on darwin and linux. `-sTCP:LISTEN`
+ *  carries the whole answer: `-i tcp:<port>` alone also matches every client
+ *  connected to it, this process included, and those must never be killed.
+ *  lsof sits in /usr/sbin on darwin, which a gui-launched shell can miss */
+export function portHolders(port: number): number[] {
+    const lsof = Bun.which('lsof') ?? ['/usr/sbin/lsof', '/usr/bin/lsof'].find((p) => existsSync(p))
+    if (lsof == null) return []
+    const r = Bun.spawnSync([lsof, '-ti', `tcp:${port}`, '-sTCP:LISTEN'], { stdout: 'pipe', stderr: 'ignore' })
+    const pids = r.stdout
+        .toString()
+        .split('\n')
+        .map((l) => Number(l.trim()))
+        .filter((n) => Number.isInteger(n) && n > 0)
+    return [...new Set(pids)]
+}
+
+/** the process group of a pid, null when ps cannot say */
+export function groupOf(pid: number): number | null {
+    const ps = Bun.which('ps') ?? (existsSync('/bin/ps') ? '/bin/ps' : null)
+    if (ps == null) return null
+    const r = Bun.spawnSync([ps, '-o', 'pgid=', '-p', String(pid)], { stdout: 'pipe', stderr: 'ignore' })
+    const g = Number(r.stdout.toString().trim())
+    return Number.isInteger(g) && g > 0 ? g : null
+}
+
+/** the port a local url serves on, null for a remote host or no url */
+export function localPort(url: string | null): number | null {
+    if (url == null) return null
+    let u: URL
+    try {
+        u = new URL(url)
+    } catch {
+        return null
+    }
+    if (!['127.0.0.1', 'localhost', '[::1]', '0.0.0.0'].includes(u.hostname)) return null
+    const p = u.port !== '' ? Number(u.port) : u.protocol === 'https:' ? 443 : u.protocol === 'http:' ? 80 : NaN
+    return Number.isInteger(p) && p > 0 ? p : null
+}