rvlib-shipkit 0.38.1 → 1.0.0

package/src/core/locked-write.ts

@@ -5,6 +5,8 @@
 // never corrupts, never blocks.
 import { linkSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from 'fs'
 import { basename, dirname, join } from 'path'
+import { LAYOUT } from './layout.ts'
+import { announceInstance, instanceGone, thisInstance } from './instance.ts'
 
 // a writer that died without unlocking must not wedge the file forever
 const LOCK_STALE_MS = 120_000
@@ -60,9 +62,11 @@ export function atomicWrite(path: string, content: string): void {
 // grabbing.
 //
 // Bounded in every direction, because a gate that hangs is worse than a gate
-// that overlaps. A holder is stale when its pid is not running OR when the
-// lock has not been touched for LOCK_STALE_MS, so a pid reused by a long
-// lived process cannot wedge a repo forever. A holder that is genuinely still
+// that overlaps. A holder is stale when its IMAGE is not running (its pid is
+// gone, or the pid runs another image after a restart in place:
+// core/instance.ts) OR when the lock has not been touched for LOCK_STALE_MS,
+// so a pid reused by a long lived process cannot wedge a repo forever. A
+// holder that is genuinely still
 // working HEARTBEATS the lock while it holds it, so the age rule only ever
 // fires on a run that is gone or wedged. A waiter gives up after maxWaitMs and
 // says so by name, path and escape hatch. Every line it prints carries a
@@ -78,37 +82,42 @@ const LEASE_HEARTBEAT_MS = 20_000
  *  SIGTERMed mid wait with no cause on screen */
 const LEASE_MAX_WAIT_MS = 60_000
 
-type Holder = { pid: number; at: number; label: string }
+type Holder = { pid: number; nonce?: string; at: number; label: string; meta?: Record<string, string> }
 
 let leaseSeq = 0
 
 const readHolder = (lockPath: string): Holder | null => {
     try {
         const h = JSON.parse(readFileSync(lockPath, 'utf8')) as Partial<Holder>
-        return typeof h.pid === 'number' ? { pid: h.pid, at: typeof h.at === 'number' ? h.at : 0, label: String(h.label ?? '?') } : null
+        if (typeof h.pid !== 'number') return null
+        return {
+            pid: h.pid,
+            ...(typeof h.nonce === 'string' ? { nonce: h.nonce } : {}),
+            at: typeof h.at === 'number' ? h.at : 0,
+            label: String(h.label ?? '?'),
+            ...(h.meta != null && typeof h.meta === 'object' ? { meta: h.meta } : {}),
+        }
     } catch { return null }
 }
 
-/** is that pid still running? signal 0 asks without delivering anything.
- *  EPERM means alive and owned by another user, which still counts as alive. */
-const alive = (pid: number): boolean => {
-    if (!Number.isInteger(pid) || pid <= 0) return false
-    try { process.kill(pid, 0); return true } catch (e) { return (e as { code?: string }).code === 'EPERM' }
-}
-
-/** publish a COMPLETE lock under a name that did not exist a moment ago */
-const grabLease = (lockPath: string, label: string): boolean => {
+/** publish a COMPLETE lock under a name that did not exist a moment ago.
+ *  'held' = the name exists, which is the only answer worth waiting on. Any
+ *  other failure (the dir gone or not writable) comes back as its message:
+ *  nobody holds that lock, and retrying cannot make it appear. */
+const grabLease = (lockPath: string, label: string, meta?: Record<string, string>): 'taken' | 'held' | { error: string } => {
     const tmp = `${lockPath}.tmp-${process.pid}-${leaseSeq++}`
+    const me = announceInstance()
     try {
-        writeFileSync(tmp, JSON.stringify({ pid: process.pid, at: Date.now(), label } satisfies Holder))
+        writeFileSync(tmp, JSON.stringify({ pid: me.pid, nonce: me.nonce, at: Date.now(), label, meta } satisfies Holder))
         linkSync(tmp, lockPath)
-        return true
-    } catch { return false }
-    finally { rmSync(tmp, { force: true }) }
+        return 'taken'
+    } catch (e) {
+        return (e as NodeJS.ErrnoException).code === 'EEXIST' ? 'held' : { error: (e as Error).message }
+    } finally { rmSync(tmp, { force: true }) }
 }
 
 const sameHolder = (a: Holder | null, b: Holder | null): boolean =>
-    a == null ? b == null : b != null && a.pid === b.pid && a.at === b.at
+    a == null ? b == null : b != null && a.pid === b.pid && a.nonce === b.nonce && a.at === b.at
 
 /** move the lock aside, and ONLY the lock we judged dead. Exactly one racer
  *  can win the rename; the rest see ENOENT and go back to grabbing.
@@ -137,16 +146,78 @@ const stealLease = (lockPath: string, expect: Holder | null): boolean => {
  *  lease two others believe they hold */
 const releaseLease = (lockPath: string): void => {
     const h = readHolder(lockPath)
-    if (h == null || h.pid === process.pid) rmSync(lockPath, { force: true })
+    const me = thisInstance()
+    if (h == null || (h.pid === me.pid && (h.nonce == null || h.nonce === me.nonce))) rmSync(lockPath, { force: true })
 }
 
-export type LeaseOutcome<T> = { ok: true; value: T; waitedMs: number } | { ok: false; warn: string }
+/** why the holder no longer holds, or null while it does: its image is gone
+ *  (core/instance.ts), or it is wedged (nothing has touched it for the stale
+ *  window, and a live holder heartbeats), or a body no reader can make sense
+ *  of is old enough not to be a write in flight */
+const deadBecause = (holder: Holder | null, ageMs: number): string | null => {
+    if (holder == null) return ageMs > 2_000 ? `an unreadable lock, untouched ${Math.round(ageMs / 1000)}s` : null
+    const gone = instanceGone(holder)
+    if (gone != null) return gone
+    return ageMs > LOCK_STALE_MS ? `pid ${holder.pid}, untouched ${Math.round(ageMs / 1000)}s` : null
+}
+
+/** a phase that legitimately outlives the stale window must keep proving it
+ *  is working, or the age rule steals from it. unref'd, so a held lease never
+ *  keeps a process alive on its own */
+const holdLease = (lockPath: string): { release: () => void } => {
+    const beat = setInterval(() => { try { utimesSync(lockPath, new Date(), new Date()) } catch { /* stolen or gone: release sorts it out */ } }, LEASE_HEARTBEAT_MS)
+    beat.unref()
+    return { release: () => { clearInterval(beat); releaseLease(lockPath) } }
+}
+
+/** ONE non blocking attempt at `<path>.lock`: taken (a holder that is gone or
+ *  wedged is stolen first), or null while a live holder has it. Held the same
+ *  way withMutateLease holds it, heartbeat included. `meta` rides in the lock
+ *  so a reader can say who holds it. */
+export function tryLease(path: string, label: string, meta?: Record<string, string>): { release: () => void } | null {
+    const lockPath = `${path}.lock`
+    for (let round = 0; round < 3; round++) {
+        const grab = grabLease(lockPath, label, meta)
+        if (grab === 'taken') return holdLease(lockPath)
+        if (grab !== 'held') return null
+        const holder = readHolder(lockPath)
+        let ageMs = 0
+        try { ageMs = Date.now() - statSync(lockPath).mtimeMs } catch { continue }
+        if (deadBecause(holder, ageMs) == null) return null
+        stealLease(lockPath, holder)
+    }
+    return null
+}
+
+/** who holds `<path>.lock` right now, or null when nobody live does */
+export function leaseHolder(path: string): { pid: number; at: number; label: string; meta: Record<string, string> } | null {
+    const lockPath = `${path}.lock`
+    const h = readHolder(lockPath)
+    let ageMs = 0
+    try { ageMs = Date.now() - statSync(lockPath).mtimeMs } catch { return null }
+    return h == null || deadBecause(h, ageMs) != null ? null : { pid: h.pid, at: h.at, label: h.label, meta: h.meta ?? {} }
+}
+
+export type LeaseOutcome<T> = { ok: true; value: T; waitedMs: number } | { ok: false; warn: string; aborted?: true }
 
 /** hold `<path>.lock` for the duration of fn. Blocking, stolen from a holder
  *  that is gone or wedged, refused (never hung) past maxWaitMs. */
 export async function withMutateLease<T>(
     path: string,
-    o: { label: string; print?: (line: string) => void; maxWaitMs?: number; escape?: string; announceMs?: number },
+    o: {
+        label: string
+        print?: (line: string) => void
+        maxWaitMs?: number
+        escape?: string
+        announceMs?: number
+        pollMs?: number
+        /** called once, the first time a LIVE holder makes this caller wait */
+        onWait?: (holder: { pid: number; label: string }) => void
+        /** called on every steal this caller wins, with the dead holder */
+        onSteal?: (holder: { pid: number; nonce?: string }) => void
+        /** polled while waiting: true stops the wait, and fn never runs */
+        abort?: () => boolean
+    },
     fn: () => T | Promise<T>,
 ): Promise<LeaseOutcome<T>> {
     const lockPath = `${path}.lock`
@@ -156,23 +227,28 @@ export async function withMutateLease<T>(
     // the first announcement is due at LEASE_ANNOUNCE_MS, every later one a
     // re-announce interval after it
     let announced = -LEASE_REANNOUNCE_MS
+    let heard = false
     mkdirSync(dirname(lockPath), { recursive: true })
 
     for (;;) {
-        if (grabLease(lockPath, o.label)) break
+        const grab = grabLease(lockPath, o.label)
+        if (grab === 'taken') break
+        if (grab !== 'held') return { ok: false, warn: `${o.label} lease: cannot create ${lockPath}: ${grab.error}` }
         const holder = readHolder(lockPath)
         let ageMs = 0
         // the lock vanished between grab and stat: the holder just finished,
         // so go straight back and take it
         try { ageMs = Date.now() - statSync(lockPath).mtimeMs } catch { continue }
-        // gone (no such process), or wedged (nothing has touched it for the
-        // stale window, and a live holder heartbeats), or a body no reader can
-        // make sense of that is old enough not to be a write in flight
-        const dead = holder == null ? ageMs > 2_000 : !alive(holder.pid) || ageMs > LOCK_STALE_MS
-        if (dead) {
-            if (stealLease(lockPath, holder)) print(`ok: stole the ${o.label} lease from a holder that is gone (pid ${holder?.pid ?? '?'}, untouched ${Math.round(ageMs / 1000)}s) — a run died mid phase`)
+        const dead = deadBecause(holder, ageMs)
+        if (dead != null) {
+            if (stealLease(lockPath, holder)) {
+                print(`ok: stole the ${o.label} lease from a holder that is gone (${dead}): a run died mid phase`)
+                if (holder != null) o.onSteal?.(holder)
+            }
             continue
         }
+        if (o.abort?.() === true) return { ok: false, warn: `${o.label} lease: stopped waiting`, aborted: true }
+        if (!heard && holder != null) { heard = true; o.onWait?.(holder) }
         const waited = Date.now() - start
         if (waited > maxWait)
             return {
@@ -183,26 +259,21 @@ export async function withMutateLease<T>(
             announced = waited
             print(`ok: waiting ${Math.round(waited / 1000)}s for the ${o.label} lease — ${holder == null ? 'an unreadable lock holds it' : `pid ${holder.pid} holds it (${holder.label})`}, lock ${lockPath}`)
         }
-        await Bun.sleep(LEASE_POLL_MS)
+        await Bun.sleep(o.pollMs ?? LEASE_POLL_MS)
     }
 
-    // a phase that legitimately outlives the stale window must keep proving it
-    // is working, or the age rule steals from it. unref'd, so a held lease
-    // never keeps a process alive on its own
-    const beat = setInterval(() => { try { utimesSync(lockPath, new Date(), new Date()) } catch { /* stolen or gone: the finally sorts it out */ } }, LEASE_HEARTBEAT_MS)
-    beat.unref()
+    const held = holdLease(lockPath)
     try {
         return { ok: true, value: await fn(), waitedMs: Date.now() - start }
     } finally {
-        clearInterval(beat)
-        releaseLease(lockPath)
+        held.release()
     }
 }
 
-/** where a repo's mutate leases live. Under the gitignored tmp/ dir so a lease
+/** where a repo's mutate leases live. Under the gitignored scratch dir so a lease
  *  file can never enter a commit, and per WORKTREE, because the phases it
  *  guards rewrite worktree-local files. The NAME is the concern: two phases
  *  that cannot corrupt each other take different leases, so `asks` never
  *  blocks a `fix`. `git config` is the one shared-across-worktrees write and
  *  carries its own retry (hooks/run-hooks.ts). */
-export const mutateLease = (root: string, name: string): string => join(root, 'tmp', `shipkit-${name}`)
+export const mutateLease = (root: string, name: string): string => join(root, LAYOUT.tmp, `shipkit-${name}`)

package/src/core/machine-commit.ts

@@ -18,10 +18,12 @@
 // not worth a red gate. `SHIPKIT_NO_AUTOCOMMIT=1` turns it off.
 import { existsSync } from 'fs'
 import { join, resolve } from 'path'
+import { gitRoot } from './git-root.ts'
 import { nestedConfigRoot } from './nesting.ts'
+import { gitBin } from './git-bin.ts'
 
 const git = (cwd: string, args: string[]): { ok: boolean; out: string } => {
-    const r = Bun.spawnSync(['git', ...args], { cwd })
+    const r = Bun.spawnSync([gitBin(), ...args], { cwd })
     return { ok: r.exitCode === 0, out: `${r.stdout.toString()}${r.stderr.toString()}`.trim() }
 }
 
@@ -38,9 +40,8 @@ export function machineCommit(o: MachineCommit): boolean {
     if (process.env['SHIPKIT_NO_AUTOCOMMIT'] === '1') return false
     if (o.paths.length === 0) return false
     try {
-        const top = git(resolve(o.anchor), ['rev-parse', '--show-toplevel'])
-        if (!top.ok) return false // not a git repo, nothing to land
-        const root = top.out
+        const root = gitRoot(resolve(o.anchor))?.top
+        if (root == null) return false // not a git repo, nothing to land
         // an anchor inside a nested shipkit repo would land on the parent's branch
         if (nestedConfigRoot(resolve(o.anchor), root) != null) return false
         // a detached HEAD or a repo with no commit yet has nowhere sane to land