rvlib-shipkit 1.1.1 → 1.3.0

package/src/core/identity-color.ts

@@ -0,0 +1,203 @@
+// a repo's identity colours: `identity: { colorLight, colorDark }` in its
+// repo.config.ts, one hex each. colorLight reads on a light background,
+// colorDark on a dark one. This module is pure (the page imports it): hue
+// maths, the fallback from the repo name, and the byte preserving edit of the
+// config text. Reading an icon is core/identity.ts.
+
+export type Identity = { colorLight: string; colorDark: string }
+
+export const HEX_RE = /^#[0-9a-fA-F]{6}$/
+
+/** why this value is not an identity, or null */
+export function identityProblem(v: unknown): string | null {
+    if (v == null) return 'no identity colours'
+    if (typeof v !== 'object') return 'identity is not an object'
+    const o = v as Record<string, unknown>
+    for (const k of ['colorLight', 'colorDark'] as const)
+        if (typeof o[k] !== 'string' || !HEX_RE.test(o[k] as string)) return `identity.${k} is ${o[k] == null ? 'missing' : `'${String(o[k])}'`}, not a #rrggbb hex`
+    return null
+}
+
+const clamp = (v: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, v))
+
+/** hsl (h in degrees, s and l in 0..1) as #rrggbb */
+export function hslHex(h: number, s: number, l: number): string {
+    const a = s * Math.min(l, 1 - l)
+    const f = (n: number): string => {
+        const k = (n + h / 30) % 12
+        const c = l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))
+        return Math.round(c * 255).toString(16).padStart(2, '0')
+    }
+    return `#${f(0)}${f(8)}${f(4)}`
+}
+
+/** #rrggbb as hsl, h in degrees */
+export function hexHsl(hex: string): { h: number; s: number; l: number } {
+    const n = Number.parseInt(hex.slice(1), 16)
+    return rgbHsl((n >> 16) & 255, (n >> 8) & 255, n & 255)
+}
+
+export function rgbHsl(r8: number, g8: number, b8: number): { h: number; s: number; l: number } {
+    const r = r8 / 255
+    const g = g8 / 255
+    const b = b8 / 255
+    const max = Math.max(r, g, b)
+    const min = Math.min(r, g, b)
+    const l = (max + min) / 2
+    const d = max - min
+    if (d === 0) return { h: 0, s: 0, l }
+    const s = d / (1 - Math.abs(2 * l - 1))
+    let h = max === r ? ((g - b) / d) % 6 : max === g ? (b - r) / d + 2 : (r - g) / d + 4
+    h *= 60
+    if (h < 0) h += 360
+    return { h, s, l }
+}
+
+/** the pair for one hue: saturated enough to read as a colour, dark enough
+ *  for white paper, light enough for a dark page */
+export function identityOfHue(h: number, s = 0.7): Identity {
+    const sat = clamp(s, 0.5, 0.85)
+    return { colorLight: hslHex(h, sat, 0.38), colorDark: hslHex(h, sat, 0.68) }
+}
+
+/** a hue hashed from the name, stable from one run to the next */
+export function nameHue(name: string): number {
+    let h = 0
+    for (const c of name) h = (h * 31 + c.charCodeAt(0)) >>> 0
+    return h % 360
+}
+
+export const identityOfName = (name: string): Identity => identityOfHue(nameHue(name))
+
+/** the dominant saturated hue of rgba pixels, weighted by saturation, or
+ *  null when the image is grey, transparent or empty */
+export function dominantHue(rgba: Uint8Array | Buffer, channels = 4): { h: number; s: number } | null {
+    const BINS = 36
+    const weight = new Float64Array(BINS)
+    const sumS = new Float64Array(BINS)
+    const vecX = new Float64Array(BINS)
+    const vecY = new Float64Array(BINS)
+    for (let i = 0; i + channels - 1 < rgba.length; i += channels) {
+        if (channels === 4 && rgba[i + 3]! < 128) continue
+        const { h, s, l } = rgbHsl(rgba[i]!, rgba[i + 1]!, rgba[i + 2]!)
+        if (s < 0.3 || l < 0.12 || l > 0.9) continue
+        const b = Math.floor(h / (360 / BINS)) % BINS
+        const w = s * (1 - Math.abs(2 * l - 1))
+        weight[b]! += w
+        sumS[b]! += s * w
+        vecX[b]! += Math.cos((h * Math.PI) / 180) * w
+        vecY[b]! += Math.sin((h * Math.PI) / 180) * w
+    }
+    let best = -1
+    let bestW = 0
+    // a bin and its two neighbours, so a hue on a bin edge is not split
+    for (let b = 0; b < BINS; b++) {
+        const w = weight[b]! + weight[(b + 1) % BINS]! + weight[(b + BINS - 1) % BINS]!
+        if (w > bestW) { bestW = w; best = b }
+    }
+    if (best < 0 || bestW === 0) return null
+    let x = 0, y = 0, s = 0, w = 0
+    for (const b of [(best + BINS - 1) % BINS, best, (best + 1) % BINS]) {
+        x += vecX[b]!
+        y += vecY[b]!
+        s += sumS[b]!
+        w += weight[b]!
+    }
+    let h = (Math.atan2(y, x) * 180) / Math.PI
+    if (h < 0) h += 360
+    return { h, s: s / w }
+}
+
+// ── the config text ─────────────────────────────────────────────────────
+
+// the key where a config writes it: at a line start, or inline after `{` or
+// `,` (a one line config), bare or quoted
+const KEY_RE = /(?:^|[{,])\s*(['"]?)identity\1\s*:\s*/gm
+
+/** per char of the text: the object depth inside `defineRepo({` after that
+ *  char (1 on the top level keys), or -1 inside a string or a comment */
+export function configDepths(text: string): Int32Array {
+    const depth = new Int32Array(text.length).fill(0)
+    const open = /defineRepo\(\s*\{/.exec(text)
+    if (open == null) return depth
+    let d = 0
+    let quote: string | null = null
+    let comment: 'line' | 'block' | null = null
+    for (let i = open.index + open[0].length - 1; i < text.length; i++) {
+        const ch = text[i]!
+        if (comment === 'line') { if (ch === '\n') comment = null; else { depth[i] = -1; continue } }
+        else if (comment === 'block') { depth[i] = -1; if (ch === '/' && text[i - 1] === '*') comment = null; continue }
+        else if (quote != null) { depth[i] = -1; if (ch === '\\') { depth[++i] = -1 } else if (ch === quote) quote = null; continue }
+        else if (ch === '/' && text[i + 1] === '/') { comment = 'line'; depth[i] = -1; continue }
+        else if (ch === '/' && text[i + 1] === '*') { comment = 'block'; depth[i] = -1; continue }
+        else if (ch === "'" || ch === '"' || ch === '`') { quote = ch; depth[i] = -1; continue }
+        if (ch === '{' || ch === '[' || ch === '(') d++
+        else if (ch === '}' || ch === ']' || ch === ')') d--
+        depth[i] = d
+    }
+    return depth
+}
+
+/** every top level `identity` key of `defineRepo({…})`, as the offsets of
+ *  its `{…}` value (end exclusive), null when the value is not an object
+ *  literal. A key nested deeper, in a string or in a comment is not it */
+function identityKeys(text: string): { value: { start: number; end: number } | null }[] {
+    const depth = configDepths(text)
+    const out: { value: { start: number; end: number } | null }[] = []
+    for (const m of text.matchAll(KEY_RE)) {
+        const sep = /^[{,]/.test(m[0]) ? m.index : m.index - 1
+        if (sep < 0 || depth[sep] !== 1) continue
+        const at = m.index + m[0].length
+        if (text[at] !== '{') { out.push({ value: null }); continue }
+        let end = -1
+        for (let j = at; j < text.length; j++) if (depth[j] === 1 && text[j] === '}') { end = j + 1; break }
+        out.push({ value: end === -1 ? null : { start: at, end } })
+    }
+    return out
+}
+
+/** whether the text declares an `identity` key at all, readable or not */
+export const declaresIdentity = (text: string): boolean => identityKeys(text).length > 0
+
+/** the identity the config text declares, read without loading it: the page
+ *  rows and the daemon read many configs per poll */
+export function identityOfText(text: string): Identity | null {
+    const keys = identityKeys(text)
+    const v = keys.length === 1 ? keys[0]!.value : null
+    if (v == null) return null
+    const body = text.slice(v.start, v.end)
+    const light = /(['"]?)colorLight\1\s*:\s*['"`](#[0-9a-fA-F]{6})['"`]/.exec(body)?.[2]
+    const dark = /(['"]?)colorDark\1\s*:\s*['"`](#[0-9a-fA-F]{6})['"`]/.exec(body)?.[2]
+    return light == null || dark == null ? null : { colorLight: light.toLowerCase(), colorDark: dark.toLowerCase() }
+}
+
+/** the config text with `identity` set to these colours. Only that key
+ *  moves: an existing object value is replaced in place, a missing key lands
+ *  as the first key of `defineRepo({`, and every other byte stays. Throws
+ *  when the text holds the key twice, holds it with a value that is not an
+ *  object literal, or has no `defineRepo({` to write into */
+export function setIdentityText(text: string, id: Identity): string {
+    const bad = identityProblem(id)
+    if (bad != null) throw new Error(bad)
+    const q = /\bname\s*:\s*"/.test(text) && !/\bname\s*:\s*'/.test(text) ? '"' : "'"
+    const value = `{ colorLight: ${q}${id.colorLight.toLowerCase()}${q}, colorDark: ${q}${id.colorDark.toLowerCase()}${q} }`
+    const keys = identityKeys(text)
+    if (keys.length > 1) throw new Error('repo.config.ts declares `identity` more than once, set it by hand')
+    if (keys.length === 1) {
+        const v = keys[0]!.value
+        if (v == null) throw new Error('repo.config.ts declares `identity` as something other than `{ … }`, set it by hand')
+        return `${text.slice(0, v.start)}${value}${text.slice(v.end)}`
+    }
+    const lines = text.split('\n')
+    const open = lines.findIndex((l) => /defineRepo\(\s*\{/.test(l))
+    if (open === -1) throw new Error('repo.config.ts has no `defineRepo({` to write `identity` into, set it by hand')
+    const line = lines[open]!
+    if (/defineRepo\(\s*\{\s*$/.test(line)) {
+        const next = lines.slice(open + 1).find((l) => l.trim() !== '' && !/^\s*}/.test(l))
+        const pad = next != null ? /^(\s*)/.exec(next)![1]! : `${/^(\s*)/.exec(line)![1]!}    `
+        return [...lines.slice(0, open + 1), `${pad}identity: ${value},`, ...lines.slice(open + 1)].join('\n')
+    }
+    // a config on one line: the key goes right after the brace
+    lines[open] = line.replace(/defineRepo\(\s*\{\s*/, (m) => `${m}identity: ${value}, `)
+    return lines.join('\n')
+}

package/src/core/identity.ts

@@ -0,0 +1,91 @@
+// a repo's identity colours, from disk: the dominant saturated colour of its
+// rail icon (serve/project-gutter.ts ICON_FILES), else a hue hashed from its
+// name, written into repo.config.ts with only the `identity` key moving. SK024
+// warns when the key is missing, its fix and the daemon's load both call
+// ensureIdentity, and the page's two swatches reach writeIdentity.
+import { existsSync, readFileSync } from 'fs'
+import { basename, join } from 'path'
+import sharp from 'sharp'
+import { atomicWrite } from './locked-write.ts'
+import { dominantHue, identityOfHue, identityOfName, identityOfText, identityProblem, setIdentityText, type Identity } from './identity-color.ts'
+import { ICON_FILES } from '../serve/project-gutter.ts'
+
+export const CONFIG_FILE = 'repo.config.ts'
+
+/** where a repo's own copy declares the config keys it knows */
+export const INSTALLED_CONFIG_SRC = 'node_modules/rvlib-shipkit/src/repo-config.ts'
+
+/** why the key cannot be written in this repo yet, or null. `source` is the
+ *  text of its own copy's repo-config.ts, null when it has none. A copy that
+ *  does not know the key would refuse it (its config load in ci, its
+ *  typecheck), so nothing writes it there. Read by capability, not version:
+ *  a linked copy is the source itself, whatever its package.json says */
+export const identityRefusal = (source: string | null): string | null =>
+    source != null && !source.includes("'identity'")
+        ? `its own rvlib-shipkit predates the identity key, so writing it would break that copy: update rvlib-shipkit first`
+        : null
+
+const installedSource = (root: string): string | null => {
+    try {
+        return readFileSync(join(root, INSTALLED_CONFIG_SRC), 'utf8')
+    } catch {
+        return null
+    }
+}
+
+/** the name the config declares, else the folder name */
+export const configName = (text: string, root: string): string => /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(text)?.[1] ?? basename(root)
+
+/** the colours an image's pixels suggest, or null when it is grey, unreadable
+ *  or a format sharp does not read (an .ico) */
+export async function identityOfImage(bytes: Uint8Array): Promise<Identity | null> {
+    try {
+        const { data } = await sharp(bytes).resize(64, 64, { fit: 'inside' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
+        const d = dominantHue(data, 4)
+        return d == null ? null : identityOfHue(d.h, d.s)
+    } catch {
+        return null
+    }
+}
+
+/** the repo's icon file, first hit wins, repo-relative */
+export const iconFileOf = (root: string): string | null => ICON_FILES.find((f) => existsSync(join(root, f))) ?? null
+
+/** what the colours should be: from the icon when it has a colour, else from the name */
+export async function deriveIdentity(root: string, name: string, read: (rel: string) => Uint8Array | null = (rel) => readFileSync(join(root, rel))): Promise<{ id: Identity; from: string }> {
+    const icon = iconFileOf(root)
+    if (icon != null) {
+        const bytes = read(icon)
+        const id = bytes == null ? null : await identityOfImage(bytes)
+        if (id != null) return { id, from: icon }
+    }
+    return { id: identityOfName(name), from: `the name '${name}'` }
+}
+
+/** the config with valid colours: derived and written when the key is
+ *  missing or malformed, the text left byte for byte otherwise */
+export async function ensureIdentity(root: string): Promise<{ changed: boolean; id: Identity | null; from: string | null; refused?: string }> {
+    const path = join(root, CONFIG_FILE)
+    if (!existsSync(path)) return { changed: false, id: null, from: null }
+    const text = readFileSync(path, 'utf8')
+    const have = identityOfText(text)
+    if (have != null && identityProblem(have) == null) return { changed: false, id: have, from: null }
+    const refused = identityRefusal(installedSource(root))
+    if (refused != null) return { changed: false, id: identityOfName(configName(text, root)), from: null, refused }
+    const { id, from } = await deriveIdentity(root, configName(text, root))
+    atomicWrite(path, setIdentityText(text, id))
+    return { changed: true, id, from }
+}
+
+/** set the colours by hand; a value left out keeps what the config has */
+export function writeIdentity(root: string, next: Partial<Identity>): Identity {
+    const refused = identityRefusal(installedSource(root))
+    if (refused != null) throw new Error(refused)
+    const path = join(root, CONFIG_FILE)
+    const text = readFileSync(path, 'utf8')
+    const have = identityOfText(text) ?? identityOfName(configName(text, root))
+    const id = { colorLight: next.colorLight ?? have.colorLight, colorDark: next.colorDark ?? have.colorDark }
+    const out = setIdentityText(text, id)
+    if (out !== text) atomicWrite(path, out)
+    return { colorLight: id.colorLight.toLowerCase(), colorDark: id.colorDark.toLowerCase() }
+}

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