rvlib-shipkit 0.38.0 → 1.0.0

package/src/core/instance.ts

@@ -0,0 +1,195 @@
+// THE PROCESS IMAGE: who wrote a slot, a lease or an attach answer is a pid
+// PLUS a nonce drawn once per program start. `bun --watch` restarts a program
+// in the same pid (execve), so a pid alone outlives the run that took the
+// record. One registry file per pid, `<pid>.json` under
+// ~/.cache/shipkit/instances/, says which image owns that pid now and which
+// check children it has in flight.
+//
+// The one constraint a reader breaks first: only a pid that is gone or runs
+// ANOTHER image is a dead holder. A silent beat never is: the beat is a main
+// thread timer, and a live holder busy in one long synchronous step stops
+// beating while it still holds the phase. A record with NO nonce, or a pid
+// with no registry file, falls back to the pid rule: an older shipkit writes
+// no nonce, and a missing file must never read as a dead holder, or two
+// processes run one phase at once.
+import { randomBytes } from 'crypto'
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { pidAlive } from '../ledger/live-runs.ts'
+import { descendantPids, psSnapshot } from './process-tree.ts'
+
+export const INSTANCES_DIR_ENV = 'SHIPKIT_INSTANCES_DIR'
+/** how often a running image stamps its registry file, so the housekeeping
+ *  below never drops the file of an image that still runs */
+export const INSTANCE_BEAT_MS = 5_000
+/** a registry file nothing stamped for this long is dropped, whatever its pid */
+const KEEP_MS = 60 * 60 * 1000
+/** a long lived image (the hub) sweeps this often, not only at start */
+const SWEEP_EVERY_MS = 60 * 60 * 1000
+/** a `<pid>.json.tmp-*` this old is a write that died before its rename */
+const TMP_KEEP_MS = 60_000
+
+export type InstanceId = { pid: number; nonce: string }
+type Registry = InstanceId & { beat: number; started: number; children: number[] }
+
+// on globalThis: two copies of the lib in one process are one image, and two
+// nonces for one pid would each call the other's records dead. The nonce key
+// holds a bare string because an older copy reads it as one.
+const g = globalThis as unknown as Record<symbol, unknown>
+const NONCE = (g[Symbol.for('shipkit.instance.nonce')] ??= randomBytes(6).toString('hex')) as string
+
+// one image writes one registry file, so every copy shares the children it
+// lists and the timer that beats it: a copy of its own writes only its own
+// children over the other's
+type ImageState = {
+    started: number
+    children: Set<number>
+    beating: { dir: string; timer: ReturnType<typeof setInterval> } | null
+    swept: number
+    exitHook: boolean
+}
+const state = (g[Symbol.for('shipkit.instance.state')] ??= {
+    started: Date.now(),
+    children: new Set<number>(),
+    beating: null,
+    swept: 0,
+    exitHook: false,
+} satisfies ImageState) as ImageState
+
+export const thisInstance = (): InstanceId => ({ pid: process.pid, nonce: NONCE })
+
+export const instancesDir = (): string => {
+    const env = process.env[INSTANCES_DIR_ENV]
+    return env != null && env !== '' ? env : join(homedir(), '.cache', 'shipkit', 'instances')
+}
+
+const readRegistry = (dir: string, pid: number): Registry | null => {
+    try {
+        const r = JSON.parse(readFileSync(join(dir, `${pid}.json`), 'utf8')) as Partial<Registry>
+        if (typeof r.nonce !== 'string' || typeof r.beat !== 'number') return null
+        return { pid, nonce: r.nonce, beat: r.beat, started: Number(r.started ?? r.beat), children: Array.isArray(r.children) ? r.children.filter((c) => Number.isInteger(c)) : [] }
+    } catch { return null }
+}
+
+/** why a holder is not a running image, or null while it is one */
+export function instanceGone(h: { pid: number; nonce?: string }): string | null {
+    if (!pidAlive(h.pid)) return `pid ${h.pid} is not running`
+    if (h.nonce == null) return null
+    if (h.pid === process.pid) return h.nonce === NONCE ? null : `pid ${h.pid} restarted in place (this process is a later image of it)`
+    const r = readRegistry(instancesDir(), h.pid)
+    return r == null || r.nonce === h.nonce ? null : `pid ${h.pid} restarted in place (another image of it runs now)`
+}
+
+// ---------------------------------------------------------------------------
+// this image's registry file: written on first use, stamped while it runs,
+// removed at exit, and listing the check children in flight so a later image
+// of the pid can reap them
+
+const write = (dir: string): void => {
+    try {
+        mkdirSync(dir, { recursive: true })
+        const path = join(dir, `${process.pid}.json`)
+        const tmp = `${path}.tmp-${NONCE}`
+        writeFileSync(tmp, JSON.stringify({ pid: process.pid, nonce: NONCE, beat: Date.now(), started: state.started, children: [...state.children] } satisfies Registry))
+        renameSync(tmp, path)
+    } catch { /* a registry nobody can write costs liveness precision, never a run */ }
+}
+
+const sweepRegistry = (dir: string, now: number): void => {
+    state.swept = now
+    try {
+        for (const f of readdirSync(dir)) {
+            const p = join(dir, f)
+            if (/^\d+\.json\.tmp-/.test(f)) {
+                try { if (now - statSync(p).mtimeMs > TMP_KEEP_MS) rmSync(p, { force: true }) } catch { /* raced: gone either way */ }
+                continue
+            }
+            const m = /^(\d+)\.json$/.exec(f)
+            if (m == null) continue
+            const r = readRegistry(dir, Number(m[1]))
+            // a pid that is gone says nothing a liveness read needs
+            if (r == null || !pidAlive(r.pid) || now - r.beat > KEEP_MS) rmSync(p, { force: true })
+        }
+    } catch { /* housekeeping never fails a run */ }
+}
+
+/** the file goes with the image, and only while it is still this image's:
+ *  a later image of the pid owns what it wrote */
+const dropOwnRecord = (): void => {
+    if (state.beating == null) return
+    if (readRegistry(state.beating.dir, process.pid)?.nonce === NONCE) rmSync(join(state.beating.dir, `${process.pid}.json`), { force: true })
+}
+
+/** publish this image as the owner of its pid, and keep stamping it. Every
+ *  record writer calls it first, so a record's nonce is always one the
+ *  registry has seen. Idempotent; the dir is read on each call so a test that
+ *  points the env elsewhere gets its own file */
+export function announceInstance(): InstanceId {
+    const dir = instancesDir()
+    if (state.beating?.dir !== dir) {
+        if (state.beating != null) clearInterval(state.beating.timer)
+        sweepRegistry(dir, Date.now())
+        write(dir)
+        const timer = setInterval(() => {
+            write(dir)
+            if (Date.now() - state.swept > SWEEP_EVERY_MS) sweepRegistry(dir, Date.now())
+        }, INSTANCE_BEAT_MS)
+        timer.unref()
+        state.beating = { dir, timer }
+    }
+    if (!state.exitHook) {
+        state.exitHook = true
+        process.on('exit', dropOwnRecord)
+    }
+    return thisInstance()
+}
+
+/** a child a check spawned, listed while it runs */
+export function trackChild(pid: number): void {
+    state.children.add(pid)
+    announceInstance()
+    if (state.beating != null) write(state.beating.dir)
+}
+
+export function untrackChild(pid: number): void {
+    if (!state.children.delete(pid)) return
+    if (state.beating != null) write(state.beating.dir)
+}
+
+/** what a new image of a restarted pid finds of the previous one, and reaps */
+export type Reclaimed = { previous: string | null; killed: number[] }
+
+/** called by a long lived process (the hub) at start, BEFORE it runs
+ *  anything: the previous image of this pid is gone, so every check child it
+ *  listed that is still OUR child is killed with its whole tree. A child
+ *  this image spawns for itself (the comfy panel) is never listed, so it is
+ *  left to be adopted. Then this image takes the pid over. */
+export function reclaimPreviousImage(o: { snapshot?: string } = {}): Reclaimed {
+    const dir = instancesDir()
+    const prev = readRegistry(dir, process.pid)
+    const out: Reclaimed = { previous: null, killed: [] }
+    if (prev != null && prev.nonce !== NONCE) {
+        out.previous = prev.nonce
+        const snapshot = o.snapshot ?? psSnapshot()
+        const ours = new Set(directChildren(snapshot))
+        for (const kid of prev.children) {
+            // a listed pid that is no longer our child was reused by someone else
+            if (!ours.has(kid)) continue
+            for (const pid of [...descendantPids(kid, snapshot), kid]) {
+                try { process.kill(pid, 'SIGKILL'); out.killed.push(pid) } catch { /* already gone */ }
+            }
+        }
+    }
+    announceInstance()
+    return out
+}
+
+const directChildren = (snapshot: string): number[] => {
+    const out: number[] = []
+    for (const line of snapshot.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line)
+        if (m != null && Number(m[2]) === process.pid) out.push(Number(m[1]))
+    }
+    return out
+}

package/src/core/jobs.ts

@@ -0,0 +1,118 @@
+// DETACHED GATES: `shipkit ci --detach` starts an ordinary gate in the
+// background and hands back a run id, `shipkit status [id]` reads it back.
+//
+// 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).
+import { spawn } from 'child_process'
+import { 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'
+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 }
+
+const JOBS = `${LAYOUT.tmp}/shipkit-jobs`
+/** how long a finished run stays readable */
+const KEEP_MS = 7 * 24 * 60 * 60 * 1000
+
+const ciLine = (args: string[]): string => ['shipkit ci', ...args].join(' ')
+
+export const jobDir =(root: string, id: string): string => join(root, JOBS, id)
+
+const readJson = <T>(p: string): T | null => {
+    try { return JSON.parse(readFileSync(p, 'utf8')) as T } catch { return null }
+}
+
+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[] } {
+    sweepJobs(root)
+    const id = `ci-${Date.now().toString(36)}-${process.pid.toString(36)}`
+    const dir = jobDir(root, id)
+    mkdirSync(dir, { recursive: true })
+    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 })
+    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))
+    return {
+        id,
+        pid,
+        lines: [
+            `ok: gate started in the background as ${id} (pid ${pid}): ${ciLine(o.args)}`,
+            `      fix: shipkit status ${id} prints it, and exits ${STILL_RUNNING} until it has a verdict`,
+        ],
+    }
+}
+
+/** 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)
+    if (!existsSync(dir)) return
+    atomicWrite(join(dir, 'exit.json'), JSON.stringify({ code, finishedAt: Date.now() } satisfies Exit))
+}
+
+function latestJob(root: string): string | null {
+    let best: Job | null = null
+    try {
+        for (const name of readdirSync(join(root, JOBS))) {
+            const j = readJson<Job>(join(root, JOBS, name, 'job.json'))
+            if (j != null && (best == null || j.startedAt > best.startedAt)) best = j
+        }
+    } catch { return null }
+    return best?.id ?? null
+}
+
+/** the run's wire lines so far, then one line on where it stands. The code is
+ *  the gate's own exit code once it has one, STILL_RUNNING before, 1 for a
+ *  run that died without a verdict, 2 for an id nobody started here. */
+export function jobStatus(root: string, id?: string): { code: number; lines: string[] } {
+    const want = id ?? latestJob(root)
+    if (want == null) return { code: 2, lines: ['FAIL: no detached run in this checkout yet', '      fix: shipkit ci --detach starts one'] }
+    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)})`]
+    let out = ''
+    try { out = readFileSync(join(dir, 'out.log'), 'utf8') } catch { /* nothing printed yet */ }
+    lines.push(...out.split('\n').filter((l) => l !== ''))
+    const exit = (): Exit | null => readJson<Exit>(join(dir, 'exit.json'))
+    let e = exit()
+    if (e == null && alive(job.pid)) {
+        lines.push(`skip: run ${job.id} still running (${((Date.now() - job.startedAt) / 1000).toFixed(1)}s so far), status exits ${STILL_RUNNING} until it has a verdict`)
+        return { code: STILL_RUNNING, lines }
+    }
+    // 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)}`] }
+    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 {
+    const base = join(root, JOBS)
+    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 */ }
+}

package/src/core/layout.ts

@@ -0,0 +1,52 @@
+// Where shipkit keeps things inside a repo: ONE folder, `.shipkit/`.
+//
+// Every path a reader or writer needs comes from this table, so a move is one
+// edit here plus the migration that carries existing repos along
+// (core/migrate-layout.ts). A repo root holds the project, never the toolkit.
+//
+// Git policy lives in the SK004 block: `.shipkit/*` is ignored, and only the
+// TRACKED children below are re-included. A folder nobody listed is local by
+// default, which is the contract's default too.
+
+export const SHIPKIT_DIR = '.shipkit'
+
+const sk = (sub: string): string => `${SHIPKIT_DIR}/${sub}`
+
+export const LAYOUT = {
+    // tracked: authored state
+    asks: sk('asks'),
+    hooks: sk('hooks'),
+    identity: sk('identity'),
+    assets: sk('assets'),
+    comfy: sk('comfy'),
+    // local: drafts, private notes, venue listings until they go live
+    private: sk('private'),
+    reflections: sk('reflections'),
+    social: sk('social'),
+    journal: sk('journal'),
+    domain: sk('domain'),
+    itch: sk('itch'),
+    steam: sk('steam'),
+    discord: sk('discord'),
+    // a review with no output file named by its caller (YYYYMMDD-HHMMSS-<name>.md)
+    reviews: sk('reviews'),
+    // scratch: plans, logs, leases, detached runs, screenshots
+    tmp: sk('tmp'),
+    // generated on every run
+    status: sk('STATUS.md'),
+    statusFull: sk('STATUS.full.md'),
+    cache: sk('cache'),
+} as const
+
+/** the children the SK004 block re-includes: everything else under `.shipkit/` stays local */
+export const TRACKED_DIRS = [LAYOUT.asks, LAYOUT.hooks, LAYOUT.identity, LAYOUT.assets, LAYOUT.comfy] as const
+
+/** the machine-global private folder, under $HOME: one keyword list and one
+ *  allowlist per machine, never copied into a repo */
+export const MACHINE_PRIVATE = LAYOUT.private
+
+/** where a gate run writes its per task logs unless repo.config says `logDir` */
+export const CI_LOG_DIR = `${LAYOUT.tmp}/shipkit-ci`
+
+/** the leak guard's per-repo keyword list */
+export const KEYWORD_FILE = `${LAYOUT.private}/banned-keywords.txt`

package/src/core/legacy-shapes.ts

@@ -0,0 +1,207 @@
+// THE MIGRATION, as code: what a repo still declares in a shape the check
+// file replaced, and the mechanical rewrite of each one. Check SK016 reports
+// this list and applies these rewrites.
+//
+// Every shape here is READ through 0.40 and refused at the first release
+// after `shipkit fleet` shows no repo below it, so a repo keeps working while
+// it carries them and learns what to write instead on every run.
+//
+// What is mechanical, and what is not, is the whole design of this module. A
+// `checkDefaults` value, a `ruleExempt` entry and a task that is DATA are
+// rewritten without guessing. A legacy check script, a `rules: []` entry and
+// a task whose body is `logic` are not: a script prints and exits in a
+// process of its own, which a check file never does (SK020), and a function
+// closes over the lexical scope of the file it was written in. Those are
+// LISTED by name with what they become, never half rewritten.
+//
+// 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 { fallbackNames, isCheckFilePath, readLegacyCheck, type LegacyCheck } from './check-file-names.ts'
+import type { ScanCtx } from './check-ctx.ts'
+import type { RepoConfig } from '../repo-config.ts'
+import { descriptionProblem, type TaskDef } from '../check.ts'
+
+/** the narrow module every rewritten file imports `check` from, and the ONE
+ *  spelling: the barrel costs 400ms of module load and discovery imports
+ *  every one of these. A repo that INSTALLS the toolkit resolves it through
+ *  node_modules, and a repo that hosts the source resolves the same bare
+ *  specifier through its tsconfig `paths`, which is also what keeps one copy
+ *  of every shared peer reachable. A nested package carrying its own tsconfig
+ *  repeats that one mapping. */
+export const CHECK_MODULE = 'rvlib-shipkit/src/check.ts'
+
+/** the opening and closing lines of a rewritten check file. A repo that
+ *  reaches the toolkit only through the global launcher resolves nothing, so
+ *  it gets the plain object: discovery re-validates it through `check()`
+ *  either way, and an import it cannot resolve takes every check down. */
+export function checkWrapper(root: string): { head: string[]; open: string; close: string } {
+    try {
+        Bun.resolveSync(CHECK_MODULE, root)
+        return { head: [`import { check } from '${CHECK_MODULE}'`, ''], open: 'export default check({', close: '})' }
+    } catch {
+        return { head: [], open: 'export default {', close: '}' }
+    }
+}
+
+export type LegacyCheckFile = {
+    /** repo-relative path of the legacy check script */
+    rel: string
+    /** what the static reader read out of it, verbatim */
+    read: LegacyCheck
+}
+
+export type LegacyTask = {
+    id: string
+    /** a task that is pure DATA (`cmd` and its decorations) is rewritten into
+     *  a file. One whose body is `logic` is a function, so it is hand work */
+    data: boolean
+    optIn: boolean
+}
+
+export type LegacyShapes = {
+    checkFiles: LegacyCheckFile[]
+    /** ids declared through `repo.config.ts rules: []` */
+    rules: string[]
+    tasks: LegacyTask[]
+    /** the repo sets `checkDefaults`, which lets a file forget `blocking` */
+    checkDefaults: boolean
+    /** ids exempted through `ruleExempt`, the spelling `when` replaced */
+    ruleExempt: string[]
+    /** check files still opening with the TODO description the migration
+     *  wrote. Not a legacy shape, so not in `count`: the file loads and
+     *  runs, and only its author can write the sentence */
+    placeholders: string[]
+    /** every shape, counted once */
+    count: number
+}
+
+/** every check file the repo carries, as discovery would find it, with its
+ *  source. Listed through `c.list`, so it is what git sees: a gitignored
+ *  check file is no declaration of this repo */
+export function repoCheckSources(d: Pick<ScanCtx, 'root' | 'list' | 'read'>): { rel: string; abs: string; src: string | null }[] {
+    return d.list(`**/*.check.ts`)
+        .filter(isCheckFilePath)
+        .map((rel) => ({ rel, abs: join(d.root, rel), src: d.read(rel) }))
+}
+
+export function legacyShapes(d: Pick<ScanCtx, 'root' | 'list' | 'read'>, c: RepoConfig): LegacyShapes {
+    const files = repoCheckSources(d)
+    const names = fallbackNames(d.root, files.map((f) => f.abs))
+    const checkFiles: LegacyCheckFile[] = []
+    for (const f of files) {
+        const read = f.src == null ? null : readLegacyCheck(f.abs, names.get(f.abs)!, f.src)
+        if (read != null) checkFiles.push({ rel: f.rel, read })
+    }
+    const rules = (c.rules ?? []).map((r) => r.id)
+    const tasks = (c.tasks ?? []).map((t): LegacyTask => ({ id: t.id, data: t.logic == null && t.cmd != null, optIn: t.optIn === true }))
+    const ruleExempt = Object.keys(c.ruleExempt ?? {})
+    const checkDefaults = c.checkDefaults != null
+    const placeholders = files.filter((f) => f.src?.includes(PLACEHOLDER_MARK) === true).map((f) => f.rel)
+    return {
+        placeholders,
+        checkFiles,
+        rules,
+        tasks,
+        checkDefaults,
+        ruleExempt,
+        count: checkFiles.length + rules.length + tasks.length + (checkDefaults ? 1 : 0) + ruleExempt.length,
+    }
+}
+
+// ── what a check script becomes ──────────────────────────────────────────
+
+/** a TS string literal, escapes and all */
+const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
+
+/** what a check file says when no line was given for it. It passes the shape,
+ *  so the repo keeps running, and it carries the marker SK016 reports, so a
+ *  human writes the line. */
+export const descriptionPlaceholder = (): string => `${PLACEHOLDER_MARK}, in one line`
+
+/** the words every placeholder carries, and what SK016 looks for */
+export const PLACEHOLDER_MARK = 'TODO: state what must be true'
+
+/** the hand port of one check script, named for its author. A script prints
+ *  and exits in a process of its own, and a check file never does (SK020):
+ *  its prints become calls on `c` inside `run`, which only a reader of that
+ *  body can write. The declarations it carries are spelled out so the port
+ *  drops none of them. */
+export function scriptPort(read: LegacyCheck, fallbackBlocking: boolean | undefined): string {
+    const blocking = read.blocking ?? fallbackBlocking
+    const fields = [
+        blocking == null ? 'blocking: <true | false, it declares none>' : `blocking: ${blocking}`,
+        ...(read.inputs != null ? [`inputs: [${read.inputs.map(q).join(', ')}]`] : []),
+        ...(read.ttl != null ? [`ttl: ${q(read.ttl)}`] : []),
+        ...(read.never != null ? [`never: ${q(read.never)}`] : []),
+        ...(read.gate ? [] : [`when: 'health'`]),
+    ]
+    return `a check script, run as its own process: port it by hand into \`export default check({ description, ${fields.join(', ')}, run: (c) => … })\`, each print a call on c (c.ok, c.warn, c.fail)`
+}
+
+/** the check file a task's argv runs through bun, `bun <file>` or `bun run
+ *  <file>`, relative, `./` prefixed or absolute, resolved against the task's
+ *  cwd. `rest` is what the argv passes after the file: a task that passes its
+ *  own arguments asks a different question, so it is never folded. */
+export function checkFileRunBy(t: Pick<TaskDef, 'cmd' | 'cwd'>, root: string): { rel: string; rest: string[] } | null {
+    const cmd = t.cmd
+    if (cmd == null || cmd.length < 2 || basename(cmd[0]!) !== 'bun') return null
+    const at = cmd[1] === 'run' ? 2 : 1
+    const arg = cmd[at]
+    if (arg == null || !arg.endsWith('.check.ts')) return null
+    const rel = relative(root, resolve(root, t.cwd ?? '.', arg)).replace(/\\/g, '/')
+    if (rel.startsWith('..')) return null
+    return { rel, rest: cmd.slice(at + 1) }
+}
+
+/** a task that is DATA, as its own check file. `build: true` is what a task
+ *  always was: the gate runs it and the health pass leaves it out. */
+export function taskCheckSource(t: TaskDef, root: string): string {
+    const own = t.description != null && descriptionProblem(t.description) == null ? t.description.trim() : null
+    const fields = [`id: ${q(t.id)},`, `description: ${q(own ?? descriptionPlaceholder())},`, 'blocking: true,', 'build: true,', `cmd: [${t.cmd!.map(q).join(', ')}],`]
+    if (t.deps != null && t.deps.length > 0) fields.push(`deps: [${t.deps.map(q).join(', ')}],`)
+    if (t.inputs != null) fields.push(`inputs: [${t.inputs.map(q).join(', ')}],`)
+    if (t.ttl != null) fields.push(`ttl: ${q(t.ttl)},`)
+    if (t.never != null) fields.push(`never: ${q(t.never)},`)
+    if (t.group != null) fields.push(`group: ${q(t.group)},`)
+    if (t.timeoutMs != null) fields.push(`timeoutMs: ${t.timeoutMs},`)
+    if (t.env != null) fields.push(`env: { ${Object.entries(t.env).map(([k, v]) => `${q(k)}: ${q(v)}`).join(', ')} },`)
+    if (t.cwd != null) fields.push(`cwd: ${q(t.cwd)},`)
+    if (t.optIn === true) fields.push(`when: 'health',`)
+    const w = checkWrapper(root)
+    return [...w.head, w.open, ...fields.map((f) => `    ${f}`), w.close, ''].join('\n')
+}
+
+/** a file name for a check whose id carries characters a path should not */
+export const checkFileName = (id: string): string => `${id.replace(/[^A-Za-z0-9._-]+/g, '-')}.check.ts`
+
+// ── 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
+ *  appears more than once: a machine that picks one of two is guessing. */
+export function dropConfigKey(text: string, key: string): string | null {
+    const lines = text.split('\n')
+    const at = lines.map((l, i) => (new RegExp(`^\\s*${key}\\s*:`).test(l) ? i : -1)).filter((i) => i !== -1)
+    if (at.length !== 1) return null
+    const start = at[0]!
+    const end = statementEnd(lines, start)
+    let from = start
+    while (from > 0 && lines[from - 1]!.trim().startsWith('//')) from--
+    return [...lines.slice(0, from), ...lines.slice(end + 1)].join('\n')
+}

package/src/core/lib-root.ts

@@ -0,0 +1,5 @@
+// the toolkit's own package dir. Its source is keyed by the toolchain id, so a
+// scan of what a repo's code reaches treats it like an install
+import { join } from 'path'
+
+export const LIB_ROOT = join(import.meta.dir, '../..')