@take-out/scripts 0.1.39-1772673702585 → 0.1.39-1772740363029

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@take-out/scripts",
-  "version": "0.1.39-1772673702585",
+  "version": "0.1.39-1772740363029",
   "type": "module",
   "main": "./src/run.ts",
   "sideEffects": false,
@@ -30,7 +30,7 @@
   "dependencies": {
     "@clack/prompts": "^0.8.2",
     "@lydell/node-pty": "^1.2.0-beta.3",
-    "@take-out/helpers": "0.1.39-1772673702585",
+    "@take-out/helpers": "0.1.39-1772740363029",
     "picocolors": "^1.1.1"
   },
   "peerDependencies": {

package/src/helpers/handleProcessExit.ts

@@ -1,3 +1,6 @@
+import { execSync } from 'node:child_process'
+import { appendFileSync, rmSync } from 'node:fs'
+
 import {
   addProcessHandler,
   setExitCleanupState,
@@ -13,19 +16,76 @@ interface HandleProcessExitReturn {
   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
+function findStragglers(trackedPids: number[]): number[] {
+  try {
+    const output = execSync('ps -eo pid,ppid', { encoding: 'utf-8', timeout: 2000 })
+    const lines = output.trim().split('\n').slice(1) // skip header
+
+    const parentToChildren = new Map<number, number[]>()
+    for (const line of lines) {
+      const parts = line.trim().split(/\s+/)
+      if (parts.length < 2) continue
+      const pid = parseInt(parts[0]!, 10)
+      const ppid = parseInt(parts[1]!, 10)
+      if (isNaN(pid) || isNaN(ppid)) continue
+      if (!parentToChildren.has(ppid)) parentToChildren.set(ppid, [])
+      parentToChildren.get(ppid)!.push(pid)
+    }
+
+    // walk from each tracked pid to find all descendants
+    const descendants = new Set<number>()
+    const queue = [...trackedPids]
+    while (queue.length > 0) {
+      const current = queue.pop()!
+      const children = parentToChildren.get(current)
+      if (!children) continue
+      for (const child of children) {
+        if (!descendants.has(child)) {
+          descendants.add(child)
+          queue.push(child)
+        }
+      }
+    }
+    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 (_) {
-    // process already gone
-  }
+  } catch (_) {}
 
   if (forceful && signal !== 'SIGKILL') {
     setTimeout(() => {
+      try {
+        process.kill(-pid, 'SIGKILL')
+      } catch (_) {}
       try {
         process.kill(pid, 'SIGKILL')
       } catch (_) {}
@@ -90,10 +150,24 @@ export function handleProcessExit({
         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)

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

@@ -0,0 +1,141 @@
+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 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(isAlive(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(isAlive(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(isAlive(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/resolveScript.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it } from 'vitest'
+
+import { flattenScripts, type FlattenedScript } from './resolveScript'
+
+// scripts modeled after the real chat package.json
+const scripts: Record<string, string> = {
+  dev: 'bun tko run-all --flags=last backend:delayed agent-gateway frontend',
+  'backend:delayed': 'sleep 5 && bun backend',
+  backend: 'bun tko run backend:up backend:migrate-then-zero jobs',
+  'backend:up': 'bun env:dev docker compose up pgdb minio',
+  'backend:migrate-then-zero':
+    'bun backend:migrate && bun env:dev docker compose up zero',
+  'backend:migrate': 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/migrate.ts',
+  frontend: 'tko run-all --flags=last dev:kill-orphans watch-lazy dev:tunnel one:dev',
+  'dev:kill-orphans': 'tko dev kill-orphans',
+  'watch-lazy': 'sleep 8 && bun watch',
+  watch: 'tko run types:watch build:watch apps:watch',
+  'types:watch': 'bun check types --watch',
+  'build:watch': 'tko run --no-root watch',
+  'apps:watch': 'tko apps build -- --watch',
+  'dev:tunnel': 'tko dev tunnel --setup',
+  'one:dev': 'bun clear-ports --only web && bun run:dev one dev --port 8081',
+  'agent-gateway': 'tko dev agent-gateway',
+  jobs: 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/jobs.ts',
+  lite: 'bun run:dev tko run-all --pty --flags=last watch-lazy lite:backend one:dev agent-gateway',
+  'lite:backend': 'bun run:dev orez --data-dir=.orez',
+}
+
+describe('flattenScripts', () => {
+  it('passes through leaf commands that are not tko run', () => {
+    const result = flattenScripts(['jobs'], scripts)
+    expect(result).toEqual([
+      {
+        name: 'jobs',
+        command: 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/jobs.ts',
+        isRaw: false,
+      },
+    ])
+  })
+
+  it('passes through shell compounds as leaves', () => {
+    const result = flattenScripts(['backend:delayed'], scripts)
+    expect(result).toEqual([
+      { name: 'backend:delayed', command: 'sleep 5 && bun backend', isRaw: false },
+    ])
+  })
+
+  it('resolves bun tko run into child scripts', () => {
+    const result = flattenScripts(['backend'], scripts)
+    expect(result).toEqual([
+      {
+        name: 'backend:up',
+        command: 'bun env:dev docker compose up pgdb minio',
+        isRaw: false,
+      },
+      {
+        name: 'backend:migrate-then-zero',
+        command: 'bun backend:migrate && bun env:dev docker compose up zero',
+        isRaw: false,
+      },
+      {
+        name: 'jobs',
+        command: 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/jobs.ts',
+        isRaw: false,
+      },
+    ])
+  })
+
+  it('resolves tko run-all (without bun prefix)', () => {
+    const result = flattenScripts(['frontend'], scripts)
+    expect(result).toEqual([
+      { name: 'dev:kill-orphans', command: 'tko dev kill-orphans', isRaw: false },
+      { name: 'watch-lazy', command: 'sleep 8 && bun watch', isRaw: false },
+      { name: 'dev:tunnel', command: 'tko dev tunnel --setup', isRaw: false },
+      {
+        name: 'one:dev',
+        command: 'bun clear-ports --only web && bun run:dev one dev --port 8081',
+        isRaw: false,
+      },
+    ])
+  })
+
+  it('resolves nested tko run chains', () => {
+    // watch -> tko run types:watch build:watch apps:watch
+    // build:watch -> tko run --no-root watch -> watch is visited (cycle), emits as leaf
+    const result = flattenScripts(['watch'], scripts)
+    expect(result).toEqual([
+      { name: 'types:watch', command: 'bun check types --watch', isRaw: false },
+      {
+        name: 'watch',
+        command: 'tko run types:watch build:watch apps:watch',
+        isRaw: false,
+      },
+      { name: 'apps:watch', command: 'tko apps build -- --watch', isRaw: false },
+    ])
+  })
+
+  it('handles multiple input commands', () => {
+    const result = flattenScripts(['jobs', 'agent-gateway'], scripts)
+    expect(result).toEqual([
+      {
+        name: 'jobs',
+        command: 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/jobs.ts',
+        isRaw: false,
+      },
+      { name: 'agent-gateway', command: 'tko dev agent-gateway', isRaw: false },
+    ])
+  })
+
+  it('handles scripts not found in package.json as raw commands', () => {
+    const result = flattenScripts(['nonexistent'], scripts)
+    expect(result).toEqual([{ name: 'nonexistent', command: 'nonexistent', isRaw: true }])
+  })
+
+  it('detects cycles and stops recursion', () => {
+    const cyclicScripts: Record<string, string> = {
+      a: 'tko run b',
+      b: 'tko run a',
+    }
+    const result = flattenScripts(['a'], cyclicScripts)
+    // a -> b -> a (cycle). when 'a' is encountered again, it's emitted as a leaf
+    expect(result).toEqual([{ name: 'a', command: 'tko run b', isRaw: false }])
+  })
+
+  it('strips --flags=last, --no-root, --pty from tko commands when extracting children', () => {
+    // verify flags like --flags=last don't appear as script names
+    const simpleScripts: Record<string, string> = {
+      parent: 'bun tko run-all --flags=last --no-root --pty child1 child2',
+      child1: 'echo one',
+      child2: 'echo two',
+    }
+    const result = flattenScripts(['parent'], simpleScripts)
+    expect(result).toEqual([
+      { name: 'child1', command: 'echo one', isRaw: false },
+      { name: 'child2', command: 'echo two', isRaw: false },
+    ])
+  })
+
+  it('filters out scripts listed in BUN_RUN_SCRIPTS', () => {
+    const result = flattenScripts(['backend'], scripts, {
+      runningScripts: ['backend:up'],
+    })
+    expect(result).toEqual([
+      {
+        name: 'backend:migrate-then-zero',
+        command: 'bun backend:migrate && bun env:dev docker compose up zero',
+        isRaw: false,
+      },
+      {
+        name: 'jobs',
+        command: 'ALLOW_MISSING_ENV=1 bun run:dev scripts/dev/jobs.ts',
+        isRaw: false,
+      },
+    ])
+  })
+
+  it('handles tko run-all with --pty flag (lite script)', () => {
+    // lite = bun run:dev tko run-all --pty --flags=last watch-lazy lite:backend one:dev agent-gateway
+    // the "bun run:dev" prefix before tko means this is NOT a tko command at the top level
+    // it contains && or is a raw command - actually "bun run:dev tko run-all ..." IS a tko pattern
+    // but wrapped in "bun run:dev" so it should be treated as a leaf
+    const result = flattenScripts(['lite'], scripts)
+    expect(result).toEqual([
+      {
+        name: 'lite',
+        command:
+          'bun run:dev tko run-all --pty --flags=last watch-lazy lite:backend one:dev agent-gateway',
+        isRaw: false,
+      },
+    ])
+  })
+
+  it('deduplicates scripts that appear multiple times', () => {
+    const dupeScripts: Record<string, string> = {
+      a: 'tko run shared c',
+      b: 'tko run shared d',
+      shared: 'echo shared',
+      c: 'echo c',
+      d: 'echo d',
+    }
+    // both a and b reference "shared", if we flatten [a, b] we should not duplicate shared
+    const result = flattenScripts(['a', 'b'], dupeScripts)
+    const names = result.map((r) => r.name)
+    // shared appears from a's resolution, then from b's resolution it should be skipped
+    expect(names).toEqual(['shared', 'c', 'shared', 'd'])
+  })
+})

package/src/helpers/resolveScript.ts

@@ -0,0 +1,91 @@
+export interface FlattenedScript {
+  name: string
+  command: string
+  /** true when the script name doesn't exist in package.json */
+  isRaw: boolean
+}
+
+export interface FlattenOptions {
+  /** scripts already running (from BUN_RUN_SCRIPTS), will be filtered out */
+  runningScripts?: string[]
+}
+
+// matches: "bun tko run ...", "bun tko run-all ...", "tko run ...", "tko run-all ..."
+// but NOT "bun run:dev tko run-all ..." (has extra words between bun and tko)
+const TKO_RUN_RE = /^(?:bun\s+)?tko\s+(run(?:-all)?)\s+(.+)$/
+
+/**
+ * parse a tko run/run-all command string, extracting script names and flags
+ * returns null if the command is not a tko run/run-all pattern
+ */
+function parseTkoRun(command: string): { scriptNames: string[] } | null {
+  const match = command.match(TKO_RUN_RE)
+  if (!match) return null
+
+  const argsPart = match[2]!
+  const args = argsPart.split(/\s+/)
+  const scriptNames: string[] = []
+
+  for (const arg of args) {
+    if (arg.startsWith('--')) {
+      // skip known flags
+      continue
+    }
+    scriptNames.push(arg)
+  }
+
+  return { scriptNames }
+}
+
+/**
+ * recursively flatten script references into leaf commands.
+ * a "leaf" is anything that is NOT a tko run/run-all command,
+ * or a script whose definition contains shell operators (&&, ;, ||).
+ */
+export function flattenScripts(
+  commands: string[],
+  packageJsonScripts: Record<string, string>,
+  options?: FlattenOptions
+): FlattenedScript[] {
+  const runningScripts = new Set(options?.runningScripts ?? [])
+  const results: FlattenedScript[] = []
+
+  function resolve(name: string, visited: Set<string>) {
+    if (runningScripts.has(name)) return
+
+    const scriptCommand = packageJsonScripts[name]
+
+    // script doesn't exist in package.json - treat as raw command
+    if (scriptCommand === undefined) {
+      results.push({ name, command: name, isRaw: true })
+      return
+    }
+
+    // cycle detected - emit as leaf to avoid infinite recursion
+    if (visited.has(name)) {
+      results.push({ name, command: scriptCommand, isRaw: false })
+      return
+    }
+
+    // try to parse as tko run/run-all
+    const parsed = parseTkoRun(scriptCommand)
+
+    if (parsed) {
+      // recurse into child scripts
+      visited.add(name)
+      for (const childName of parsed.scriptNames) {
+        resolve(childName, visited)
+      }
+      return
+    }
+
+    // leaf command - not a tko run/run-all pattern
+    results.push({ name, command: scriptCommand, isRaw: false })
+  }
+
+  for (const cmd of commands) {
+    resolve(cmd, new Set())
+  }
+
+  return results
+}

package/src/process-cleanup.test.ts

@@ -0,0 +1,255 @@
+import { spawn } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, describe, expect, test } from 'vitest'
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function waitForCondition(
+  fn: () => boolean,
+  timeoutMs = 5000,
+  intervalMs = 50
+): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (fn()) return true
+    await new Promise((r) => setTimeout(r, intervalMs))
+  }
+  return false
+}
+
+async function waitForFile(path: string, timeoutMs = 5000): Promise<string> {
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(path)) {
+      const content = readFileSync(path, 'utf-8').trim()
+      if (content) return content
+    }
+    await new Promise((r) => setTimeout(r, 50))
+  }
+  throw new Error(`file never appeared: ${path}`)
+}
+
+const tmpDir = mkdtempSync(join(tmpdir(), 'proc-cleanup-'))
+const pidsToCleanup: number[] = []
+
+afterEach(async () => {
+  for (const pid of pidsToCleanup) {
+    try {
+      process.kill(pid, 'SIGKILL')
+    } catch {}
+    try {
+      process.kill(-pid, 'SIGKILL')
+    } catch {}
+  }
+  pidsToCleanup.length = 0
+})
+
+function makeChildScript(pidFile: string, opts?: { grandchild?: boolean }): string {
+  const path = join(
+    tmpDir,
+    `child-${Date.now()}-${Math.random().toString(36).slice(2)}.sh`
+  )
+  if (opts?.grandchild) {
+    const gcPidFile = pidFile.replace('.pid', '-gc.pid')
+    // use a separate script for grandchild to avoid escaping issues
+    const gcScript = join(
+      tmpDir,
+      `gc-${Date.now()}-${Math.random().toString(36).slice(2)}.sh`
+    )
+    writeFileSync(gcScript, `#!/bin/bash\necho $$ > ${gcPidFile}\nsleep 999\n`, {
+      mode: 0o755,
+    })
+    writeFileSync(
+      path,
+      `#!/bin/bash\necho $$ > ${pidFile}\nbash ${gcScript} &\nsleep 999\n`,
+      {
+        mode: 0o755,
+      }
+    )
+  } else {
+    writeFileSync(path, `#!/bin/bash\necho $$ > ${pidFile}\nsleep 999\n`, { mode: 0o755 })
+  }
+  return path
+}
+
+const handleProcessExitPath = join(__dirname, 'helpers', 'handleProcessExit.ts')
+
+// creates a parent node script that uses real handleProcessExit
+function createParentScript(opts: {
+  childScripts: string[]
+  parentPidFile: string
+}): string {
+  const scriptPath = join(
+    tmpDir,
+    `parent-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`
+  )
+  writeFileSync(
+    scriptPath,
+    `
+import { handleProcessExit } from '${handleProcessExitPath}'
+import { spawn } from 'node:child_process'
+import { writeFileSync } from 'node:fs'
+
+const { addChildProcess } = handleProcessExit()
+
+writeFileSync(${JSON.stringify(opts.parentPidFile)}, String(process.pid))
+
+const scripts = ${JSON.stringify(opts.childScripts)}
+for (const script of scripts) {
+  const child = spawn('bash', [script], { detached: true, stdio: 'ignore' })
+  child.unref()
+  addChildProcess(child)
+}
+
+setInterval(() => {}, 60000)
+`
+  )
+  return scriptPath
+}
+
+function spawnParent(scriptPath: string) {
+  const child = spawn('bun', [scriptPath], {
+    detached: true,
+    stdio: 'ignore',
+  })
+  child.unref()
+  pidsToCleanup.push(child.pid!)
+  return child
+}
+
+describe('process cleanup', { timeout: 15_000 }, () => {
+  test('SIGTERM kills all children', async () => {
+    const pidFiles = [join(tmpDir, 'a1.pid'), join(tmpDir, 'a2.pid')]
+    const parentPidFile = join(tmpDir, 'p-term.pid')
+    const childScripts = pidFiles.map((f) => makeChildScript(f))
+    const script = createParentScript({ childScripts, parentPidFile })
+
+    spawnParent(script)
+
+    const parentPid = parseInt(await waitForFile(parentPidFile))
+    pidsToCleanup.push(parentPid)
+    const childPids = await Promise.all(pidFiles.map((f) => waitForFile(f).then(Number)))
+    childPids.forEach((p) => pidsToCleanup.push(p))
+
+    expect(isAlive(parentPid)).toBe(true)
+    childPids.forEach((pid) => expect(isAlive(pid)).toBe(true))
+
+    process.kill(parentPid, 'SIGTERM')
+
+    const allDead = await waitForCondition(
+      () => !isAlive(parentPid) && childPids.every((p) => !isAlive(p)),
+      5000
+    )
+    expect(allDead).toBe(true)
+  })
+
+  test('SIGINT kills all children', async () => {
+    const pidFiles = [join(tmpDir, 'b1.pid')]
+    const parentPidFile = join(tmpDir, 'p-int.pid')
+    const childScripts = pidFiles.map((f) => makeChildScript(f))
+    const script = createParentScript({ childScripts, parentPidFile })
+
+    spawnParent(script)
+
+    const parentPid = parseInt(await waitForFile(parentPidFile))
+    pidsToCleanup.push(parentPid)
+    const childPid = parseInt(await waitForFile(pidFiles[0]!))
+    pidsToCleanup.push(childPid)
+
+    process.kill(parentPid, 'SIGINT')
+
+    const allDead = await waitForCondition(
+      () => !isAlive(parentPid) && !isAlive(childPid),
+      5000
+    )
+    expect(allDead).toBe(true)
+  })
+
+  test('SIGHUP kills all children', async () => {
+    const pidFiles = [join(tmpDir, 'c1.pid')]
+    const parentPidFile = join(tmpDir, 'p-hup.pid')
+    const childScripts = pidFiles.map((f) => makeChildScript(f))
+    const script = createParentScript({ childScripts, parentPidFile })
+
+    spawnParent(script)
+
+    const parentPid = parseInt(await waitForFile(parentPidFile))
+    pidsToCleanup.push(parentPid)
+    const childPid = parseInt(await waitForFile(pidFiles[0]!))
+    pidsToCleanup.push(childPid)
+
+    process.kill(parentPid, 'SIGHUP')
+
+    const allDead = await waitForCondition(
+      () => !isAlive(parentPid) && !isAlive(childPid),
+      5000
+    )
+    expect(allDead).toBe(true)
+  })
+
+  test('process group kill reaches grandchildren', async () => {
+    const pidFiles = [join(tmpDir, 'd1.pid')]
+    const parentPidFile = join(tmpDir, 'p-gc.pid')
+    const grandchildPidFile = join(tmpDir, 'd1-gc.pid')
+    const childScripts = pidFiles.map((f) => makeChildScript(f, { grandchild: true }))
+    const script = createParentScript({ childScripts, parentPidFile })
+
+    spawnParent(script)
+
+    const parentPid = parseInt(await waitForFile(parentPidFile))
+    pidsToCleanup.push(parentPid)
+    const childPid = parseInt(await waitForFile(pidFiles[0]!))
+    pidsToCleanup.push(childPid)
+    const gcPid = parseInt(await waitForFile(grandchildPidFile))
+    pidsToCleanup.push(gcPid)
+
+    expect(isAlive(childPid)).toBe(true)
+    expect(isAlive(gcPid)).toBe(true)
+
+    process.kill(parentPid, 'SIGTERM')
+
+    const allDead = await waitForCondition(
+      () => !isAlive(childPid) && !isAlive(gcPid),
+      5000
+    )
+    expect(allDead).toBe(true)
+  })
+
+  test('pid file is created and cleaned up', async () => {
+    const pidFiles = [join(tmpDir, 'e1.pid')]
+    const parentPidFile = join(tmpDir, 'p-pidfile.pid')
+    const childScripts = pidFiles.map((f) => makeChildScript(f))
+    const script = createParentScript({ childScripts, parentPidFile })
+
+    spawnParent(script)
+
+    const parentPid = parseInt(await waitForFile(parentPidFile))
+    pidsToCleanup.push(parentPid)
+    const childPid = parseInt(await waitForFile(pidFiles[0]!))
+    pidsToCleanup.push(childPid)
+
+    // pid file should exist while parent is running
+    const tkoFile = `/tmp/tko-run-${parentPid}.pids`
+    const pidFileExists = await waitForCondition(() => existsSync(tkoFile), 3000)
+    expect(pidFileExists).toBe(true)
+
+    const contents = readFileSync(tkoFile, 'utf-8').trim()
+    expect(contents).toContain(String(childPid))
+
+    // send SIGTERM and verify pid file is cleaned up
+    process.kill(parentPid, 'SIGTERM')
+
+    const cleaned = await waitForCondition(() => !existsSync(tkoFile), 5000)
+    expect(cleaned).toBe(true)
+  })
+})

package/src/run.ts

@@ -10,6 +10,7 @@ import { join, relative, resolve } from 'node:path'
 
 import { handleProcessExit } from '@take-out/scripts/helpers/handleProcessExit'
 
+import { flattenScripts } from './helpers/resolveScript'
 import { getIsExiting } from './helpers/run'
 import { checkNodeVersion } from './node-version-check'
 
@@ -28,38 +29,6 @@ const reset = '\x1b[0m'
 // eslint-disable-next-line no-control-regex
 const ansiPattern = /\x1b\[[0-9;]*m/g
 
-const args = process.argv.slice(2)
-const ownFlags = ['--no-root', '--bun', '--watch', '--flags=last']
-const runCommands: string[] = []
-const forwardArgs: string[] = []
-
-for (let i = 0; i < args.length; i++) {
-  const arg = args[i]!
-
-  if (arg.startsWith('--')) {
-    if (ownFlags.includes(arg)) continue
-    forwardArgs.push(arg)
-    const nextArg = args[i + 1]
-    if (nextArg && !nextArg.startsWith('--')) {
-      forwardArgs.push(nextArg)
-      i++
-    }
-  } else {
-    runCommands.push(arg)
-  }
-}
-
-const noRoot = args.includes('--no-root')
-const runBun = args.includes('--bun')
-const watch = args.includes('--watch')
-const flagsLast = args.includes('--flags=last')
-
-const MAX_RESTARTS = 3
-
-const parentRunningScripts = process.env.BUN_RUN_SCRIPTS
-  ? process.env.BUN_RUN_SCRIPTS.split(',')
-  : []
-
 interface ManagedProcess {
   proc: ReturnType<typeof spawn>
   name: string
@@ -70,22 +39,6 @@ interface ManagedProcess {
   shortcut: string
 }
 
-const managedProcesses: ManagedProcess[] = []
-const { addChildProcess, exit } = handleProcessExit()
-
-function getPrefix(index: number): string {
-  const managed = managedProcesses[index]
-  if (!managed) return ''
-  const color = colors[index % colors.length]
-  const sc = managed.shortcut || String(index + 1)
-  return `${color}${sc} ${managed.prefixLabel}${reset}`
-}
-
-if (runCommands.length === 0) {
-  console.error('Please provide at least one script name to run')
-  exit(1)
-}
-
 async function readPackageJson(directoryPath: string) {
   try {
     const packageJsonPath = join(directoryPath, 'package.json')
@@ -216,97 +169,7 @@ async function mapWorkspacesToScripts(
   return workspaceScriptMap
 }
 
-const runScript = async (
-  name: string,
-  cwd = '.',
-  prefixLabel: string = name,
-  restarts = 0,
-  extraArgs: string[] = [],
-  managedIndex?: number
-) => {
-  const index = managedIndex ?? managedProcesses.length
-
-  const runArgs = ['run', '--silent', runBun ? '--bun' : '', name, ...extraArgs].filter(
-    Boolean
-  )
-
-  const allRunningScripts = [...parentRunningScripts, ...runCommands].join(',')
-
-  const proc = spawn('bun', runArgs, {
-    stdio: ['ignore', 'pipe', 'pipe'],
-    shell: false,
-    env: {
-      ...process.env,
-      FORCE_COLOR: '3',
-      BUN_RUN_PARENT_SCRIPT: name,
-      BUN_RUN_SCRIPTS: allRunningScripts,
-      TKO_SILENT: '1',
-    } as any,
-    cwd: resolve(cwd),
-  })
-
-  const managed: ManagedProcess = {
-    proc,
-    name,
-    cwd,
-    prefixLabel,
-    extraArgs,
-    index,
-    shortcut: '',
-  }
-
-  if (managedIndex !== undefined) {
-    managedProcesses[managedIndex] = managed
-  } else {
-    managedProcesses.push(managed)
-  }
-
-  addChildProcess(proc)
-
-  proc.stdout!.on('data', (data) => {
-    if (getIsExiting()) return
-    const lines = data.toString().split('\n')
-    for (const line of lines) {
-      const stripped = line.replace(ansiPattern, '')
-      if (stripped.startsWith('$ ')) continue
-      if (line) console.info(`${getPrefix(index)} ${line}`)
-    }
-  })
-
-  proc.stderr!.on('data', (data) => {
-    if (getIsExiting()) return
-    const lines = data.toString().split('\n')
-    for (const line of lines) {
-      const stripped = line.replace(ansiPattern, '')
-      if (stripped.startsWith('$ ')) continue
-      if (line) console.error(`${getPrefix(index)} ${line}`)
-    }
-  })
-
-  proc.on('error', (error) => {
-    console.error(`${getPrefix(index)} Failed to start: ${error.message}`)
-  })
-
-  proc.on('close', (code) => {
-    if (getIsExiting()) return
-
-    if (code && code !== 0) {
-      console.error(`${getPrefix(index)} Process exited with code ${code}`)
-
-      if (watch && restarts < MAX_RESTARTS) {
-        const newRestarts = restarts + 1
-        console.info(`Restarting process ${name} (${newRestarts}/${MAX_RESTARTS} times)`)
-        runScript(name, cwd, prefixLabel, newRestarts, extraArgs, index)
-      } else {
-        exit(1)
-      }
-    }
-  })
-
-  return proc
-}
-
-function computeShortcuts() {
+function computeShortcuts(managedProcesses: ManagedProcess[]) {
   const initials = managedProcesses.map((p) => {
     const words = p.prefixLabel
       .toLowerCase()
@@ -350,28 +213,216 @@ function computeShortcuts() {
   }
 }
 
-async function main() {
-  checkNodeVersion().catch((err) => {
-    console.error(err.message)
+// --- exported interface for CLI direct-import ---
+
+export interface RunParallelScriptsOptions {
+  commands: string[]
+  noRoot?: boolean
+  flagsLast?: boolean
+  runBun?: boolean
+  watch?: boolean
+  forwardArgs?: string[]
+}
+
+export async function runParallelScripts(
+  options: RunParallelScriptsOptions
+): Promise<void> {
+  const {
+    commands: runCommands,
+    noRoot = false,
+    flagsLast = false,
+    runBun = false,
+    watch = false,
+    forwardArgs = [],
+  } = options
+
+  const MAX_RESTARTS = 3
+
+  const parentRunningScripts = process.env.BUN_RUN_SCRIPTS
+    ? process.env.BUN_RUN_SCRIPTS.split(',')
+    : []
+
+  const managedProcesses: ManagedProcess[] = []
+  const { addChildProcess, exit } = handleProcessExit()
+
+  function getPrefix(index: number): string {
+    const managed = managedProcesses[index]
+    if (!managed) return ''
+    const color = colors[index % colors.length]
+    const sc = managed.shortcut || String(index + 1)
+    return `${color}${sc} ${managed.prefixLabel}${reset}`
+  }
+
+  if (runCommands.length === 0) {
+    console.error('Please provide at least one script name to run')
     exit(1)
-  })
+    return
+  }
+
+  // spawns a single script process, optionally running a command directly via bash
+  const runScript = async (
+    name: string,
+    cwd = '.',
+    prefixLabel: string = name,
+    restarts = 0,
+    extraArgs: string[] = [],
+    managedIndex?: number,
+    directCommand?: string
+  ) => {
+    const index = managedIndex ?? managedProcesses.length
+
+    const allRunningScripts = [...parentRunningScripts, ...runCommands].join(',')
+
+    let proc: ReturnType<typeof spawn>
+
+    if (directCommand) {
+      // run the resolved command directly via bash, skipping the bun run layer
+      const command = extraArgs.length
+        ? `${directCommand} ${extraArgs.join(' ')}`
+        : directCommand
+      proc = spawn('bash', ['-c', command], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false,
+        detached: true,
+        env: {
+          ...process.env,
+          FORCE_COLOR: '3',
+          BUN_RUN_PARENT_SCRIPT: name,
+          BUN_RUN_SCRIPTS: allRunningScripts,
+          TKO_SILENT: '1',
+        } as any,
+        cwd: resolve(cwd),
+      })
+    } else {
+      const runArgs = [
+        'run',
+        '--silent',
+        runBun ? '--bun' : '',
+        name,
+        ...extraArgs,
+      ].filter(Boolean)
+      proc = spawn('bun', runArgs, {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false,
+        detached: true,
+        env: {
+          ...process.env,
+          FORCE_COLOR: '3',
+          BUN_RUN_PARENT_SCRIPT: name,
+          BUN_RUN_SCRIPTS: allRunningScripts,
+          TKO_SILENT: '1',
+        } as any,
+        cwd: resolve(cwd),
+      })
+    }
+
+    const managed: ManagedProcess = {
+      proc,
+      name,
+      cwd,
+      prefixLabel,
+      extraArgs,
+      index,
+      shortcut: '',
+    }
+
+    if (managedIndex !== undefined) {
+      managedProcesses[managedIndex] = managed
+    } else {
+      managedProcesses.push(managed)
+    }
+
+    addChildProcess(proc)
+
+    proc.stdout!.on('data', (data) => {
+      if (getIsExiting()) return
+      const lines = data.toString().split('\n')
+      for (const line of lines) {
+        const stripped = line.replace(ansiPattern, '')
+        if (stripped.startsWith('$ ')) continue
+        if (line) console.info(`${getPrefix(index)} ${line}`)
+      }
+    })
+
+    proc.stderr!.on('data', (data) => {
+      if (getIsExiting()) return
+      const lines = data.toString().split('\n')
+      for (const line of lines) {
+        const stripped = line.replace(ansiPattern, '')
+        if (stripped.startsWith('$ ')) continue
+        if (line) console.error(`${getPrefix(index)} ${line}`)
+      }
+    })
+
+    proc.on('error', (error) => {
+      console.error(`${getPrefix(index)} Failed to start: ${error.message}`)
+    })
+
+    proc.on('close', (code) => {
+      if (getIsExiting()) return
+
+      if (code && code !== 0) {
+        console.error(`${getPrefix(index)} Process exited with code ${code}`)
+
+        if (watch && restarts < MAX_RESTARTS) {
+          const newRestarts = restarts + 1
+          console.info(
+            `Restarting process ${name} (${newRestarts}/${MAX_RESTARTS} times)`
+          )
+          runScript(name, cwd, prefixLabel, newRestarts, extraArgs, index, directCommand)
+        } else {
+          exit(1)
+        }
+      }
+    })
+
+    return proc
+  }
 
   try {
+    checkNodeVersion().catch((err) => {
+      console.error(err.message)
+      exit(1)
+    })
+
     if (runCommands.length > 0) {
       const lastScript = runCommands[runCommands.length - 1]
 
       if (!noRoot) {
+        // read package.json scripts for flattening
+        const packageJson = await readPackageJson('.')
+        const pkgScripts = packageJson?.scripts ?? {}
+
         const filteredCommands = runCommands.filter(
           (name) => !parentRunningScripts.includes(name)
         )
-        const scriptPromises = filteredCommands.map((name) => {
-          const scriptArgs = !flagsLast || name === lastScript ? forwardArgs : []
-          return runScript(name, '.', name, 0, scriptArgs)
+
+        // flatten tko run/run-all chains into leaf commands
+        const flattened = flattenScripts(filteredCommands, pkgScripts, {
+          runningScripts: parentRunningScripts,
+        })
+
+        const lastLeaf = flattened[flattened.length - 1]
+        const scriptPromises = flattened.map((leaf) => {
+          const scriptArgs = !flagsLast || leaf === lastLeaf ? forwardArgs : []
+          // known scripts: run command directly via bash (skip bun run layer)
+          // unknown scripts: fall through to bun run --silent
+          const directCommand = !leaf.isRaw ? leaf.command : undefined
+          return runScript(
+            leaf.name,
+            '.',
+            leaf.name,
+            0,
+            scriptArgs,
+            undefined,
+            directCommand
+          )
         })
 
         await Promise.all(scriptPromises)
       }
 
+      // workspace scripts still use bun run (they need workspace cwd)
       const workspaceScriptMap = await mapWorkspacesToScripts(runCommands)
 
       for (const [workspace, { scripts, packageName }] of workspaceScriptMap.entries()) {
@@ -396,7 +447,7 @@ async function main() {
     if (managedProcesses.length === 0) {
       exit(0)
     } else {
-      computeShortcuts()
+      computeShortcuts(managedProcesses)
     }
   } catch (error) {
     console.error(`Error running scripts: ${error}`)
@@ -404,7 +455,43 @@ async function main() {
   }
 }
 
-main().catch((error) => {
-  console.error(`Error running scripts: ${error}`)
-  exit(1)
-})
+// --- CLI entry point (only runs when executed directly, not when imported) ---
+
+const ownFlags = ['--no-root', '--bun', '--watch', '--flags=last']
+
+export function parseRunArgs(args: string[]): RunParallelScriptsOptions {
+  const commands: string[] = []
+  const forwardArgs: string[] = []
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+
+    if (arg.startsWith('--')) {
+      if (ownFlags.includes(arg)) continue
+      forwardArgs.push(arg)
+      const nextArg = args[i + 1]
+      if (nextArg && !nextArg.startsWith('--')) {
+        forwardArgs.push(nextArg)
+        i++
+      }
+    } else {
+      commands.push(arg)
+    }
+  }
+
+  return {
+    commands,
+    noRoot: args.includes('--no-root'),
+    runBun: args.includes('--bun'),
+    watch: args.includes('--watch'),
+    flagsLast: args.includes('--flags=last'),
+    forwardArgs,
+  }
+}
+
+if (typeof Bun !== 'undefined' && Bun.main === import.meta.path) {
+  runParallelScripts(parseRunArgs(process.argv.slice(2))).catch((error) => {
+    console.error(`Error running scripts: ${error}`)
+    process.exit(1)
+  })
+}