rvlib-shipkit 0.38.0 → 1.0.0

package/src/core/run-fixers.ts

@@ -13,11 +13,15 @@ import { join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import type { RepoConfig } from '../repo-config.ts'
-import { runFix } from '../rules/run-fix.ts'
+import { runFix } from './run-fix.ts'
 import { routesToShipkit } from './canonical-scripts.ts'
+import { discoverLegacyChecks } from './discover-legacy-checks.ts'
+import { repoCheckFiles } from './discover-checks.ts'
 import { mutateLease, withMutateLease } from './locked-write.ts'
-import { repairContractDirs } from './repair-contract-dirs.ts'
+import { migrateLayout } from './migrate-layout.ts'
+import { renderPolicy } from '../checks/SK004-gitignore-policy.check.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
+import { gitBin } from './git-bin.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
 
@@ -103,7 +107,7 @@ export function resolveFixers(root: string, config?: RepoConfig): FixerResolutio
  *  actually stops another agent's work being reported here is the lease plus
  *  the byte comparison, not a path list. */
 function treeState(root: string): Map<string, string> | null {
-    const p = Bun.spawnSync(['git', 'status', '--porcelain'], { cwd: root })
+    const p = Bun.spawnSync([gitBin(), 'status', '--porcelain'], { cwd: root })
     if (p.exitCode !== 0) return null
     const m = new Map<string, string>()
     for (const l of p.stdout.toString().split('\n')) {
@@ -119,6 +123,15 @@ function treeState(root: string): Map<string, string> | null {
     return m
 }
 
+/** the bytes of repo.config.ts and the set of check and check files, as one
+ *  hash. Read without git, so a repo with no history is covered too */
+function shapeStamp(root: string): string {
+    let config = ''
+    try { config = readFileSync(join(root, 'repo.config.ts'), 'utf8') } catch {}
+    const files = [...repoCheckFiles(root), ...discoverLegacyChecks(root).map((d) => d.path)].sort()
+    return String(Bun.hash(`${config}\0${files.join('\0')}`))
+}
+
 export type FixPassOpts = {
     /** also apply the structural SK rule fixers (default false) */
     rules?: boolean
@@ -135,6 +148,9 @@ export type FixPassResult = {
     touched: string[]
     /** verify mode only: a fixer had to rewrite something, so the commit is not clean */
     failed: boolean
+    /** repo.config.ts or a check file moved under the pass, so a config or an
+     *  inventory read before it describes a repo that is gone */
+    reshaped: boolean
 }
 
 export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpts): Promise<FixPassResult> {
@@ -157,46 +173,52 @@ export async function runFixPass(root: string, config: RepoConfig, o: FixPassOpt
     if (verify) {
         o.print(`FAIL: fixers never ran — ${lease.warn}`)
         o.print('      fix: nothing was verified. re-run once that process finishes, or pass --no-fix to state that on purpose')
-        return { ran: false, touched: [], failed: true }
+        return { ran: false, touched: [], failed: true, reshaped: false }
     }
     o.print(`WARN fix pass skipped — ${lease.warn}`)
     o.print('      fix: nothing was repaired this run; the gate below reports the tree as it stands')
-    return { ran: false, touched: [], failed: false }
+    return { ran: false, touched: [], failed: false, reshaped: false }
 }
 
 async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, verify: boolean): Promise<FixPassResult> {
+    // the old root layout moves under .shipkit/ before anything else reads a
+    // path: a move is not a decision, so it lands as one machine commit and
+    // only what a machine cannot decide reaches a human. Runs before the tree
+    // snapshot, and before hooks arm, because the hooks folder may be what moves
+    if (!verify) {
+        const m = migrateLayout(root, { config, renderGitignore: (t, legacy) => renderPolicy(t, config, legacy) })
+        if (m.moved.length > 0 || m.removed.length > 0) {
+            const what = m.moved.filter((x) => x.kind !== 'cache').map((x) => `${x.from}/`).join(' ')
+            if (m.uncommitted === true) {
+                o.print(`WARN moved ${what} under .shipkit/, and the commit did not land`)
+                const p = m.pending ?? []
+                o.print(`      fix: commit exactly these paths, never a bare commit: git commit -m 'chore: move the shipkit folders under .shipkit/' -- ${p.slice(0, 12).join(' ')}${p.length > 12 ? ` (+${p.length - 12} more, listed by git status)` : ''}`)
+            } else if (what !== '') o.print(`ok: moved ${what} under .shipkit/${m.commit != null ? `, committed as ${m.commit}` : ''}`)
+        }
+        if (m.deferred != null) {
+            o.print(`WARN the move under .shipkit/ is deferred: ${m.deferred}`)
+            o.print('      fix: commit or discard that edit, then re-run shipkit ci')
+        }
+        for (const r of m.refusals) {
+            o.print(`WARN ${r.from}/ cannot move to ${r.to}/: ${r.reason}`)
+            o.print(`      fix: move the files into ${r.to}/ yourself, then delete ${r.from}/`)
+        }
+    }
     // commit gates arm themselves on the interactive gate: a repo.config with
     // dark hooks is the half-wired state that let a whole drill session
-    // commit ungated (2026-08-04). Runs BEFORE the tree snapshot: arming is
-    // its own reported concern, never counted as a fixer rewrite.
+    // commit ungated (2026-08-04). Arming is its own reported concern, never
+    // counted as a fixer rewrite.
     if (o.armHooks === true && !verify) {
         const armed = armHooks(root, config)
-        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the hooks/ dir`)
+        if (armed.state === 'armed') o.print(`ok: hooks armed (${armed.detail}), commit the .shipkit/hooks/ dir`)
         else if (armed.state === 'foreign' || armed.state === 'not-root') o.print(`skip: hooks (${armed.detail})`)
         else if (armed.state === 'failed') o.print(`WARN hooks could not arm: ${armed.detail}`)
     }
-    // a contract folder typed without its dot is a typo a machine can fix with
-    // certainty, so it is repaired and committed rather than reported. Only the
-    // ambiguous case reaches a human. Runs before the tree snapshot: the rename
-    // lands in its own commit and is never counted as a fixer rewrite
-    if (!verify) {
-        const repaired = repairContractDirs(root)
-        for (const r of repaired.refusals) {
-            o.print(`WARN ${r.from}/ and ${r.to}/ both exist — ${r.reason}`)
-            o.print(`      fix: move the files into ${r.to}/ yourself, then delete ${r.from}/`)
-        }
-        // silence is for a repair that COMPLETED. one that renamed and could
-        // not land the commit leaves dirt nobody can trace to a run they did
-        // not make, which is the failure the silence was meant to prevent
-        for (const r of repaired.uncommitted) {
-            o.print(`WARN renamed ${r.from}/ to ${r.to}/, and the commit did not land`)
-            o.print(`      fix: commit the removal of ${r.from}/ yourself — the files are in ${r.to}/`)
-        }
-    }
     const { slots, unfilled, disabled } = resolveFixers(root, config)
     for (const u of unfilled) o.print(`skip: ${u.id} (${u.reason})`)
     for (const d of disabled) o.print(`skip: ${d.id} (${d.reason})`)
     const before = treeState(root)
+    const shapeBefore = shapeStamp(root)
 
     for (const s of slots) {
         const r = await spawnWithTimeout(s.cmd, { cwd: root, timeoutMs: FIXER_TIMEOUT_MS })
@@ -209,6 +231,7 @@ async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, ver
     if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print })
 
     const after = treeState(root)
+    const reshaped = shapeStamp(root) !== shapeBefore
     const touched: string[] = []
     if (before != null && after != null) {
         for (const [path, hash] of after) if (before.get(path) !== hash) touched.push(path)
@@ -227,17 +250,17 @@ async function fixPassBody(root: string, config: RepoConfig, o: FixPassOpts, ver
     const list = `${touched.slice(0, 8).join(' ')}${touched.length > 8 ? ` … +${touched.length - 8}` : ''}`
     if (before == null) {
         o.print(`ok: fix pass ran, ${slots.length} fixer(s) (not a git repo — rewritten files cannot be listed)`)
-        return { ran: true, touched, failed: false }
+        return { ran: true, touched, failed: false, reshaped }
     }
     if (touched.length === 0) {
         o.print(`ok: ${verify ? 'fixers verified' : 'fix pass'} clean (${slots.length} fixer(s), nothing to rewrite)`)
-        return { ran: true, touched, failed: false }
+        return { ran: true, touched, failed: false, reshaped }
     }
     if (verify) {
         o.print(`FAIL: ${touched.length} file(s) are not fixer-clean: ${list}`)
         o.print(`      fix: run \`shipkit ci\` locally (the fix pass rewrites them) and commit the result`)
-        return { ran: true, touched, failed: true }
+        return { ran: true, touched, failed: true, reshaped }
     }
     o.print(`ok: fix pass rewrote ${touched.length} file(s): ${list}`)
-    return { ran: true, touched, failed: false }
+    return { ran: true, touched, failed: false, reshaped }
 }

package/src/core/self-update.ts

@@ -2,6 +2,9 @@
 // checks the registry (24h cache on disk), updates rvlib-shipkit when it is
 // behind, and RE-EXECS the same invocation so the run continues on the new
 // version. a stale toolkit must never wait for a human to police versions.
+// the update runs through the manager the repo's own lock files name: on an
+// npm consumer, bun would move package.json and leave package-lock.json on
+// the old version, which is a pair `npm ci` refuses at deploy time.
 //
 // never fires: running from source (not under node_modules), CI env, frozen,
 // re-exec guard set, dirty package.json/lockfile (a tool must not mix its
@@ -11,6 +14,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
+import { detectPackageManager } from './package-manager.ts'
+import { gitBin } from './git-bin.ts'
 
 const PKG = 'rvlib-shipkit'
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000
@@ -77,7 +82,7 @@ async function latestCached(): Promise<string | null> {
 }
 
 const manifestDirty = (root: string): boolean => {
-    const p = Bun.spawnSync(['git', 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb', 'package-lock.json'], { cwd: root })
+    const p = Bun.spawnSync([gitBin(), 'status', '--porcelain', '--', 'package.json', 'bun.lock', 'bun.lockb', 'package-lock.json'], { cwd: root })
     if (p.exitCode !== 0) return true // no git = no safe write
     return p.stdout.toString().trim() !== ''
 }
@@ -99,8 +104,9 @@ export async function maybeSelfUpdateAndRestart(root: string): Promise<void> {
     const plan = planSelfUpdate({ ...base, latest: await latestCached(), manifestDirty: manifestDirty(root) })
     if (plan.action === 'warn') { console.error(`WARN self-update: ${plan.reason}`); return }
     if (plan.action !== 'update') return
-    console.error(`ok: rvlib-shipkit ${plan.installed} → ${plan.latest}, self-updating (bun update --latest ${PKG})`)
-    const up = Bun.spawnSync(['bun', 'update', '--latest', PKG], { cwd: root, stdout: 'inherit', stderr: 'inherit' })
+    const cmd = detectPackageManager(root).update([PKG])
+    console.error(`ok: rvlib-shipkit ${plan.installed} → ${plan.latest}, self-updating (${cmd.join(' ')})`)
+    const up = Bun.spawnSync(cmd, { cwd: root, stdout: 'inherit', stderr: 'inherit' })
     if (up.exitCode !== 0) { console.error(`WARN self-update failed (exit ${up.exitCode}), continuing on ${plan.installed}`) ; return }
     console.error(`ok: restarting on ${plan.latest} — commit package.json + lockfile with your work`)
     const child = Bun.spawnSync([process.execPath, ...process.argv.slice(1)], {

package/src/core/slots.ts

@@ -0,0 +1,83 @@
+// THE MACHINE POOL: every shipkit process on this machine (every repo, every
+// agent, the hub) measures at most parallelCap() checks at once. One lock file
+// per slot, `slot-<n>.lock` under ~/.cache/shipkit/slots/, taken through the
+// mutate lease's non blocking form (locked-write.ts tryLease): a slot whose
+// holder died is free at once, and a live holder heartbeats it.
+//
+// The one constraint a reader breaks first: a process started BY a check
+// (SHIPKIT_SLOT_HELD=1 in its environment) takes no slot. It already runs on
+// its parent's, and a parent waiting on a child that waits for a slot the
+// parent holds is a deadlock the moment every slot is such a parent.
+import { mkdirSync, readdirSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+import { leaseHolder, tryLease } from './locked-write.ts'
+import { PARALLEL_ENV, parallelCap, parallelCapInfo } from './parallel.ts'
+
+/** where the slots live, for a test that must not touch the machine's pool */
+export const SLOTS_DIR_ENV = 'SHIPKIT_SLOTS_DIR'
+/** set for every process a check spawns: it runs on its parent's slot */
+export const SLOT_HELD_ENV = 'SHIPKIT_SLOT_HELD'
+
+export type SlotPool = { dir: string; size: number }
+
+export type SlotHolder = { slot: number; pid: number; repo: string; check: string; since: number }
+
+const SLOT_POLL_MS = 25
+
+export const poolDir = (): string => {
+    const env = process.env[SLOTS_DIR_ENV]
+    return env != null && env !== '' ? env : join(homedir(), '.cache', 'shipkit', 'slots')
+}
+
+/** this process's pool, or null when it runs inside a check that holds one */
+export function machinePool(): SlotPool | null {
+    return process.env[SLOT_HELD_ENV] === '1' ? null : { dir: poolDir(), size: parallelCap() }
+}
+
+/** who holds which slot right now, dead holders left out. Every slot file in
+ *  the dir is read, so a slot taken under a larger size still shows. */
+export function poolOccupancy(pool: SlotPool = { dir: poolDir(), size: parallelCap() }): { size: number; dir: string; held: SlotHolder[] } {
+    const held: SlotHolder[] = []
+    let names: string[] = []
+    try { names = readdirSync(pool.dir) } catch { /* no pool yet: nobody holds anything */ }
+    for (const name of names) {
+        const m = /^slot-(\d+)\.lock$/.exec(name)
+        if (m == null) continue
+        const h = leaseHolder(join(pool.dir, `slot-${m[1]}`))
+        if (h != null) held.push({ slot: Number(m[1]), pid: h.pid, repo: h.meta.repo ?? '?', check: h.meta.check ?? h.label, since: h.at })
+    }
+    return { size: pool.size, dir: pool.dir, held: held.sort((a, b) => a.slot - b.slot) }
+}
+
+/** what `shipkit ci` prints about the pool, one line (two with a bad env) */
+export function poolLines(): string[] {
+    const info = parallelCapInfo()
+    const pool = machinePool()
+    const why = info.source === 'env' ? `${PARALLEL_ENV} sets it` : `this machine's cores, 2 to 8; ${PARALLEL_ENV} sets it`
+    return [
+        ...(info.problem == null ? [] : [`WARN ${info.problem}`]),
+        pool == null
+            ? `ok: parallel: inside a check that holds a machine slot, so this run takes none (up to ${info.cap} at once in this process)`
+            : `ok: parallel: one machine pool of ${info.cap} slot(s) shared by every shipkit process, ${poolOccupancy(pool).held.length} held now (${why})`,
+    ]
+}
+
+/** wait for a free slot and hold it until release(). null = abort said stop. */
+export async function takeSlot(
+    pool: SlotPool,
+    who: { repo: string; check: string },
+    o: { abort?: () => boolean; pollMs?: number; onWait?: (held: SlotHolder[]) => void } = {},
+): Promise<{ slot: number; release: () => void } | null> {
+    mkdirSync(pool.dir, { recursive: true })
+    let heard = false
+    for (;;) {
+        for (let slot = 0; slot < pool.size; slot++) {
+            const lease = tryLease(join(pool.dir, `slot-${slot}`), who.check, { repo: who.repo, check: who.check })
+            if (lease != null) return { slot, release: lease.release }
+        }
+        if (o.abort?.() === true) return null
+        if (!heard) { heard = true; o.onWait?.(poolOccupancy(pool).held) }
+        await Bun.sleep(o.pollMs ?? SLOT_POLL_MS)
+    }
+}

package/src/core/spawn-timeout.ts

@@ -3,8 +3,16 @@
 // Resolves the binary first (Bun.spawn throws on a missing one), streams
 // stdout+stderr, SIGTERM at timeoutMs, SIGKILL after a grace period so a
 // SIGTERM-ignoring child can never hang the caller.
+//
+// The kill walks the whole process TREE, because the cmd is usually a wrapper
+// (`bun scripts/test.ts` spawning `bun test`) and Bun.spawn offers no process
+// group to signal: signalling the wrapper alone leaves the process doing the
+// work orphaned and spinning, with nothing left holding a handle on it.
 
 import { existsSync } from 'fs'
+import { gitBin } from './git-bin.ts'
+import { trackChild, untrackChild } from './instance.ts'
+import { descendantPids } from './process-tree.ts'
 
 export type SpawnOutcome = {
     code: number
@@ -26,12 +34,28 @@ export type SpawnTimeoutOpts = {
     onSpawn?: (proc: ReturnType<typeof Bun.spawn>) => void
 }
 
+/** signal the descendants, then the child itself through its own handle (the
+ *  handle knows the child exited, a bare pid does not). A pid that already
+ *  went is the normal case here, never an error. Returns what it signalled, so
+ *  a later pass can reach a survivor that reparenting has hidden. A remembered
+ *  pid could be recycled inside that pass's grace window, which is the price
+ *  of a runtime with no process group to signal. */
+export function killTree(proc: { pid: number; kill: (s?: NodeJS.Signals) => void }, signal: NodeJS.Signals, known?: number[]): number[] {
+    const pids = [...new Set([...(known ?? []), ...descendantPids(proc.pid)])]
+    for (const pid of pids) {
+        try { process.kill(pid, signal) } catch {}
+    }
+    try { proc.kill(signal) } catch {}
+    return pids
+}
+
 export async function spawnWithTimeout(cmd: string[], opts: SpawnTimeoutOpts): Promise<SpawnOutcome> {
     const head = cmd[0]
     if (head == null) return { code: -1, out: 'empty command', timedOut: false, spawnFailed: true }
     // path-style heads verified too — Bun.spawn on a missing path throws,
     // which must surface as a result, never a crash
-    const bin = head.includes('/') ? head : Bun.which(head)
+    const name = head === 'git' ? gitBin() : head
+    const bin = name.includes('/') ? name : Bun.which(name)
     if (bin == null || !existsSync(bin)) return { code: -1, out: `${head}: not found`, timedOut: false, spawnFailed: true }
     let proc: ReturnType<typeof Bun.spawn>
     try {
@@ -44,10 +68,16 @@ export async function spawnWithTimeout(cmd: string[], opts: SpawnTimeoutOpts): P
     } catch (e) {
         return { code: -1, out: `spawn error: ${String(e).slice(0, 200)}`, timedOut: false, spawnFailed: true }
     }
+    // listed while it runs, so a later image of this pid can reap it
+    trackChild(proc.pid)
     opts.onSpawn?.(proc)
     let timedOut = false
-    const timer = setTimeout(() => { timedOut = true; try { proc.kill() } catch {} }, opts.timeoutMs)
-    const killer = setTimeout(() => { try { proc.kill('SIGKILL') } catch {} }, opts.timeoutMs + (opts.killGraceMs ?? 2000))
+    // what the tree looked like at SIGTERM time: a survivor is reparented the
+    // moment its parent dies, so the SIGKILL pass can no longer walk down to
+    // it from the child
+    let tree: number[] = []
+    const timer = setTimeout(() => { timedOut = true; tree = killTree(proc, 'SIGTERM') }, opts.timeoutMs)
+    const killer = setTimeout(() => { killTree(proc, 'SIGKILL', tree) }, opts.timeoutMs + (opts.killGraceMs ?? 2000))
     let out = ''
     const eat = async (stream: ReadableStream<Uint8Array>): Promise<void> => {
         const dec = new TextDecoder()
@@ -59,6 +89,7 @@ export async function spawnWithTimeout(cmd: string[], opts: SpawnTimeoutOpts): P
     }
     await Promise.all([eat(proc.stdout as ReadableStream<Uint8Array>), eat(proc.stderr as ReadableStream<Uint8Array>)])
     const code = await proc.exited
+    untrackChild(proc.pid)
     clearTimeout(timer)
     clearTimeout(killer)
     return { code, out, timedOut, spawnFailed: false }