@o/run 0.16.19

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@o/run",
+  "version": "0.16.19",
+  "type": "module",
+  "main": "./src/run.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/run.ts",
+      "default": "./src/run.ts"
+    },
+    "./package.json": "./package.json",
+    "./helpers/*": {
+      "types": "./src/helpers/*.ts",
+      "default": "./src/helpers/*.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "scripts": {
+    "lint": "oxlint src",
+    "lint:fix": "oxfmt src && oxlint --fix --fix-suggestions src",
+    "test:bun": "bun test src/run-supervision.test.ts src/run-pty-supervision.test.ts",
+    "typecheck": "tko run typecheck"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.3",
+    "semver": "^7.7.3"
+  },
+  "devDependencies": {
+    "@types/semver": "^7.7.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/natew/orez.git",
+    "directory": "packages/run"
+  },
+  "files": [
+    "src",
+    "src/run-pty.mjs"
+  ],
+  "peerDependencies": null,
+  "optionalDependencies": null
+}

package/src/helpers/handleProcessExit.ts

@@ -0,0 +1,230 @@
+import { execSync } from 'node:child_process'
+import { appendFileSync, rmSync } from 'node:fs'
+
+import {
+  addProcessHandler,
+  setExitCleanupState,
+  type ProcessHandler,
+  type ProcessType,
+} from './process-state'
+
+type ExitCallback = (info: { signal: string }) => void | Promise<void>
+
+interface HandleProcessExitReturn {
+  addChildProcess: ProcessHandler
+  cleanup: () => Promise<void>
+  exit: (code?: number) => Promise<void>
+}
+
+const pidFilePath = `/tmp/tko-run-${process.pid}.pids`
+
+function writePidFile(pid: number) {
+  try {
+    appendFileSync(pidFilePath, `${pid}\n`)
+  } catch {}
+}
+
+function removePidFile() {
+  try {
+    rmSync(pidFilePath, { force: true })
+  } catch {}
+}
+
+// find descendant pids that survived the group kill
+// uses pgrep -P instead of ps (ps is a setuid binary blocked by sandbox-exec)
+function findStragglers(trackedPids: number[]): number[] {
+  try {
+    const descendants = new Set<number>()
+    const queue = [...trackedPids]
+    while (queue.length > 0) {
+      const current = queue.pop()!
+      try {
+        const output = execSync(`pgrep -P ${current}`, {
+          encoding: 'utf-8',
+          timeout: 2000,
+        })
+        for (const line of output.trim().split('\n')) {
+          const pid = parseInt(line, 10)
+          if (!isNaN(pid) && !descendants.has(pid)) {
+            descendants.add(pid)
+            queue.push(pid)
+          }
+        }
+      } catch {
+        // pgrep exits 1 when no children found, that's fine
+      }
+    }
+    return [...descendants]
+  } catch {
+    return []
+  }
+}
+
+// kill entire process group to prevent orphaned descendants
+function killProcess(
+  pid: number,
+  signal: NodeJS.Signals = 'SIGTERM',
+  forceful: boolean = false
+): void {
+  // kill process group first (negative pid), then direct process
+  try {
+    process.kill(-pid, signal)
+  } catch (_) {}
+  try {
+    process.kill(pid, signal)
+  } catch (_) {}
+
+  if (forceful && signal !== 'SIGKILL') {
+    setTimeout(() => {
+      try {
+        process.kill(-pid, 'SIGKILL')
+      } catch (_) {}
+      try {
+        process.kill(pid, 'SIGKILL')
+      } catch (_) {}
+    }, 100)
+  }
+}
+
+let isHandling = false
+
+export function handleProcessExit({
+  onExit,
+}: {
+  onExit?: ExitCallback
+} = {}): HandleProcessExitReturn {
+  if (isHandling) {
+    throw new Error(`Only one handleProcessExit per process should be registered!`)
+  }
+
+  isHandling = true
+  const processes: ProcessType[] = []
+  let cleanupPromise: Promise<void> | null = null
+
+  const cleanup = (signal: string = 'SIGTERM'): Promise<void> => {
+    // return existing cleanup promise if already running, so process.exit
+    // override waits for the real cleanup instead of exiting early
+    if (cleanupPromise) return cleanupPromise
+
+    cleanupPromise = doCleanup(signal)
+    return cleanupPromise
+  }
+
+  const doCleanup = async (signal: string) => {
+    setExitCleanupState(true)
+
+    if (onExit) {
+      try {
+        await onExit({ signal })
+      } catch (error) {
+        console.error('Error in exit callback:', error)
+      }
+    }
+
+    if (processes.length === 0) {
+      return
+    }
+
+    const isInterrupt = signal === 'SIGINT'
+    const killSignal = isInterrupt ? 'SIGTERM' : (signal as NodeJS.Signals)
+
+    for (const proc of processes) {
+      if (proc.pid) {
+        killProcess(proc.pid, killSignal, isInterrupt)
+      }
+    }
+
+    // brief wait for graceful shutdown
+    await new Promise((res) => setTimeout(res, isInterrupt ? 80 : 200))
+
+    // force kill any remaining
+    for (const proc of processes) {
+      if (proc.pid && !proc.exitCode) {
+        killProcess(proc.pid, 'SIGKILL')
+      }
+    }
+
+    // straggler walk: find any descendants that survived the group kill
+    const trackedPids = processes.map((p) => p.pid).filter(Boolean) as number[]
+    if (trackedPids.length > 0) {
+      const stragglers = findStragglers(trackedPids)
+      for (const pid of stragglers) {
+        try {
+          process.kill(pid, 'SIGKILL')
+        } catch {}
+      }
+    }
+
+    removePidFile()
+  }
+
+  const addChildProcess = (proc: ProcessType) => {
+    processes.push(proc)
+    if (proc.pid) writePidFile(proc.pid)
+  }
+
+  addProcessHandler(addChildProcess)
+
+  let finalized = false
+
+  const finalizeWithSignal = (signal: NodeJS.Signals, fallbackCode: number) => {
+    if (finalized) return
+    finalized = true
+    process.off('SIGINT', sigintHandler)
+    process.off('SIGTERM', sigtermHandler)
+    process.off('SIGHUP', sighupHandler)
+    process.off('beforeExit', beforeExitHandler)
+    process.exit = originalExit
+
+    try {
+      process.kill(process.pid, signal)
+    } catch {
+      originalExit(fallbackCode)
+    }
+  }
+
+  const sigtermHandler = () => {
+    cleanup('SIGTERM').then(() => {
+      finalizeWithSignal('SIGTERM', 143)
+    })
+  }
+
+  const sigintHandler = () => {
+    cleanup('SIGINT').then(() => {
+      finalizeWithSignal('SIGINT', 130)
+    })
+  }
+
+  const sighupHandler = () => {
+    cleanup('SIGHUP').then(() => {
+      finalizeWithSignal('SIGHUP', 129)
+    })
+  }
+
+  // intercept process.exit to ensure cleanup completes before exiting.
+  // if cleanup is already running, this awaits the SAME promise instead of
+  // early-returning and calling originalExit prematurely.
+  const originalExit = process.exit
+  process.exit = ((code?: number) => {
+    cleanup('SIGTERM').then(() => {
+      originalExit(code)
+    })
+  }) as typeof process.exit
+
+  const beforeExitHandler = () => cleanup('SIGTERM')
+  process.on('beforeExit', beforeExitHandler)
+  process.on('SIGINT', sigintHandler)
+  process.on('SIGTERM', sigtermHandler)
+  process.on('SIGHUP', sighupHandler)
+
+  const exit = async (code: number = 0) => {
+    await cleanup('SIGTERM')
+    process.exit(code)
+  }
+
+  return {
+    addChildProcess,
+    cleanup,
+    exit,
+  }
+}

package/src/helpers/process-cleanup.test.ts

@@ -0,0 +1,150 @@
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterAll, afterEach, describe, expect, it } from 'vitest'
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function waitForDead(pid: number, timeoutMs = 3000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (!isAlive(pid)) return true
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  return false
+}
+
+async function waitForAlive(pid: number, timeoutMs = 3000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (isAlive(pid)) return true
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  return false
+}
+
+async function waitForFile(path: string, timeoutMs = 3000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(path)) return true
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  return false
+}
+
+describe('process cleanup', () => {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'tko-test-'))
+  const pids: number[] = []
+
+  afterEach(() => {
+    for (const pid of pids) {
+      try {
+        process.kill(-pid, 'SIGKILL')
+      } catch {}
+      try {
+        process.kill(pid, 'SIGKILL')
+      } catch {}
+    }
+    pids.length = 0
+  })
+
+  afterAll(() => {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true })
+    } catch {}
+  })
+
+  it('detached child gets its own process group', async () => {
+    const pidFile = join(tmpDir, 'child1.pid')
+    const child = spawn('bash', ['-c', `echo $$ > ${pidFile}; sleep 999`], {
+      detached: true,
+      stdio: 'ignore',
+    })
+    pids.push(child.pid!)
+    child.unref()
+
+    expect(await waitForFile(pidFile)).toBe(true)
+    const childPid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10)
+
+    expect(await waitForAlive(childPid)).toBe(true)
+
+    // killing the process group should kill it
+    try {
+      process.kill(-child.pid!, 'SIGKILL')
+    } catch {}
+    expect(await waitForDead(childPid)).toBe(true)
+  })
+
+  it('process group kill reaches grandchildren', async () => {
+    const grandchildPidFile = join(tmpDir, 'grandchild.pid')
+    // write a helper script so escaping is clean
+    const helperScript = join(tmpDir, 'grandchild-helper.sh')
+    writeFileSync(
+      helperScript,
+      `#!/bin/bash\necho $$ > ${grandchildPidFile}\nsleep 999\n`,
+      { mode: 0o755 }
+    )
+
+    const parent = spawn('bash', ['-c', `bash ${helperScript} & wait`], {
+      detached: true,
+      stdio: 'ignore',
+    })
+    pids.push(parent.pid!)
+
+    expect(await waitForFile(grandchildPidFile)).toBe(true)
+    const grandchildPid = parseInt(readFileSync(grandchildPidFile, 'utf-8').trim(), 10)
+    pids.push(grandchildPid)
+
+    expect(await waitForAlive(grandchildPid)).toBe(true)
+
+    // kill the process group — grandchild should die too
+    try {
+      process.kill(-parent.pid!, 'SIGKILL')
+    } catch {}
+    expect(await waitForDead(grandchildPid)).toBe(true)
+  })
+
+  it('SIGTERM on parent with trap kills children', async () => {
+    const childPidFile = join(tmpDir, 'term-child.pid')
+    const wrapperScript = join(tmpDir, 'wrapper.sh')
+    writeFileSync(
+      wrapperScript,
+      [
+        '#!/bin/bash',
+        'cleanup() { kill 0; exit 0; }',
+        'trap cleanup SIGTERM',
+        `bash -c 'echo $$ > ${childPidFile}; sleep 999' &`,
+        'wait',
+        '',
+      ].join('\n'),
+      { mode: 0o755 }
+    )
+
+    const parent = spawn('bash', [wrapperScript], {
+      detached: true,
+      stdio: 'ignore',
+    })
+    pids.push(parent.pid!)
+
+    expect(await waitForFile(childPidFile)).toBe(true)
+    const childPid = parseInt(readFileSync(childPidFile, 'utf-8').trim(), 10)
+    pids.push(childPid)
+
+    expect(await waitForAlive(childPid)).toBe(true)
+
+    // send SIGTERM to the process group
+    try {
+      process.kill(-parent.pid!, 'SIGTERM')
+    } catch {}
+    expect(await waitForDead(childPid, 5000)).toBe(true)
+  })
+})

package/src/helpers/process-state.ts

@@ -0,0 +1,26 @@
+import { type ChildProcess } from 'node:child_process'
+
+export type ProcessType = ChildProcess
+export type ProcessHandler = (process: ProcessType) => void
+
+// shared state: tracks if we're in cleanup (another process failed)
+let isInExitCleanup = false
+
+export function setExitCleanupState(state: boolean) {
+  isInExitCleanup = state
+}
+
+export function getIsExiting() {
+  return isInExitCleanup
+}
+
+// handlers called when any process is spawned via run()
+const processHandlers = new Set<ProcessHandler>()
+
+export const addProcessHandler = (cb: ProcessHandler) => {
+  processHandlers.add(cb)
+}
+
+export function notifyProcessHandlers(proc: ProcessType) {
+  processHandlers.forEach((cb) => cb(proc))
+}