@davstack/tui 0.2.0

package/src/hooks/useDaemonProcess.test.ts

@@ -0,0 +1,415 @@
+// Unit tests for useDaemonProcess via ink-testing-library: a small probe
+// component exposes the hook's return value to the test through a ref-like
+// callback so we can assert state transitions without a DOM dependency.
+
+import React from "react"
+import { EventEmitter } from "node:events"
+import { PassThrough } from "node:stream"
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+import { render } from "ink-testing-library"
+import { Text } from "ink"
+
+import {
+  useDaemonProcess,
+  type UseDaemonProcessDeps,
+  type UseDaemonProcessResult,
+} from "./useDaemonProcess.ts"
+import type { DaemonDescriptor } from "../lib/daemon-registry.ts"
+
+type FakeChild = EventEmitter & {
+  stdout: PassThrough
+  stderr: PassThrough
+  pid: number
+  kill: (sig?: string) => boolean
+  killCalls: string[]
+}
+
+let nextPid = 10000
+function makeFakeChild(): FakeChild {
+  const ee = new EventEmitter() as FakeChild
+  ee.stdout = new PassThrough()
+  ee.stderr = new PassThrough()
+  ee.pid = nextPid++
+  ee.killCalls = []
+  ee.kill = (sig?: string) => {
+    ee.killCalls.push(sig ?? "SIGTERM")
+    return true
+  }
+  return ee
+}
+
+function makeDescriptor(child: FakeChild): DaemonDescriptor {
+  return {
+    key: "logs",
+    label: "logs",
+    port: 0,
+    readyRegex: /listening on http:\/\//i,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    spawn: () => child as any,
+  }
+}
+
+function makeDeps(overrides: Partial<UseDaemonProcessDeps> = {}): {
+  deps: UseDaemonProcessDeps
+  killTreeCalls: Array<{ pid: number; signal: string }>
+  probeReturns: { value: boolean }
+} {
+  const killTreeCalls: Array<{ pid: number; signal: string }> = []
+  const probeReturns = { value: false }
+  const deps: UseDaemonProcessDeps = {
+    killTree: async (pid, signal) => {
+      killTreeCalls.push({ pid, signal })
+    },
+    probePort: async () => probeReturns.value,
+    registerChild: () => {},
+    unregisterChild: () => {},
+    ...overrides,
+  }
+  return { deps, killTreeCalls, probeReturns }
+}
+
+// Probe component: passes the hook result back through `onRender` each render.
+function Probe({
+  descriptor,
+  deps,
+  onRender,
+}: {
+  descriptor: DaemonDescriptor
+  deps: UseDaemonProcessDeps
+  onRender: (r: UseDaemonProcessResult) => void
+}): React.ReactElement {
+  const r = useDaemonProcess(descriptor, deps)
+  onRender(r)
+  return React.createElement(Text, null, r.status)
+}
+
+// Flush microtasks so React commits the state update.
+async function tick(): Promise<void> {
+  await new Promise<void>((resolve) => setImmediate(resolve))
+}
+
+// Two ticks — probePort resolves in a microtask, then doSpawn fires and
+// state settles in a second commit.
+async function tick2(): Promise<void> {
+  await tick()
+  await tick()
+}
+
+describe("useDaemonProcess", () => {
+  let captured: UseDaemonProcessResult | null = null
+  let active: ReturnType<typeof render> | null = null
+
+  beforeEach(() => {
+    captured = null
+    vi.useFakeTimers({ shouldAdvanceTime: true })
+  })
+
+  afterEach(() => {
+    active?.unmount()
+    active = null
+    vi.useRealTimers()
+  })
+
+  function mount(desc: DaemonDescriptor, deps: UseDaemonProcessDeps) {
+    active = render(
+      React.createElement(Probe, {
+        descriptor: desc,
+        deps,
+        onRender: (r) => {
+          captured = r
+        },
+      }),
+    )
+  }
+
+  test("idle -> starting -> running on ready line", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps } = makeDeps()
+    mount(desc, deps)
+
+    expect(captured!.status).toBe("idle")
+
+    captured!.start()
+    await tick()
+    expect(captured!.status).toBe("starting")
+    await tick2()
+
+    child.stdout.write("booting...\n")
+    await tick()
+    expect(captured!.status).toBe("starting")
+
+    child.stdout.write("log-server listening on http://127.0.0.1:7077  db=x\n")
+    await tick()
+    expect(captured!.status).toBe("running")
+    expect(captured!.lines.some((l) => l.text.includes("listening on http"))).toBe(true)
+  })
+
+  test("crashes on non-zero exit, captures exit code in state", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps } = makeDeps()
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+
+    child.emit("exit", 1, null)
+    await tick()
+
+    expect(captured!.status).toBe("crashed")
+    expect(captured!.exitCode).toBe(1)
+  })
+
+  test("stop() sends SIGTERM via killTree, escalates to SIGKILL after 2s", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps, killTreeCalls } = makeDeps()
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    child.stdout.write("listening on http://x\n")
+    await tick()
+    expect(captured!.status).toBe("running")
+
+    captured!.stop()
+    await tick()
+    expect(captured!.status).toBe("exiting")
+    expect(killTreeCalls.map((c) => c.signal)).toEqual(["SIGTERM"])
+    expect(killTreeCalls[0].pid).toBe(child.pid)
+
+    vi.advanceTimersByTime(2_001)
+    expect(killTreeCalls.map((c) => c.signal)).toEqual(["SIGTERM", "SIGKILL"])
+
+    child.emit("exit", null, "SIGKILL")
+    await tick()
+    expect(captured!.status).toBe("exited")
+  })
+
+  test("stop() is idempotent", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps, killTreeCalls } = makeDeps()
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    captured!.stop()
+    captured!.stop()
+    await tick()
+    expect(killTreeCalls.length).toBe(1)
+  })
+
+  test("captures stdout and stderr into lines", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps } = makeDeps()
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    child.stdout.write("hello\nworld\n")
+    child.stderr.write("warning!\n")
+    await tick()
+
+    const texts = captured!.lines.map((l) => `${l.stream}:${l.text}`)
+    expect(texts).toContain("out:hello")
+    expect(texts).toContain("out:world")
+    expect(texts).toContain("err:warning!")
+  })
+
+  test("port-probe returning true sets status=blocked and skips spawn", async () => {
+    const child = makeFakeChild()
+    const spawnSpy = vi.fn(() => child as never)
+    const desc: DaemonDescriptor = {
+      key: "logs",
+      label: "logs",
+      port: 7077,
+      readyRegex: /listening on http:\/\//i,
+      spawn: spawnSpy,
+    }
+    const { deps, probeReturns } = makeDeps()
+    probeReturns.value = true
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    expect(captured!.status).toBe("blocked")
+    expect(spawnSpy).not.toHaveBeenCalled()
+    expect(
+      captured!.lines.some((l) => /port 7077 already in use/.test(l.text)),
+    ).toBe(true)
+  })
+
+  test("takeover() kills external port owner, polls port free, then re-spawns", async () => {
+    const child = makeFakeChild()
+    const spawnSpy = vi.fn(() => child as never)
+    const desc: DaemonDescriptor = {
+      key: "logs",
+      label: "logs",
+      port: 7077,
+      readyRegex: /listening on http:\/\//i,
+      spawn: spawnSpy,
+    }
+    let probeCall = 0
+    const { deps, killTreeCalls } = makeDeps({
+      probePort: async () => {
+        probeCall++
+        // start preflight → blocked; takeover poll → still busy, then free; start preflight → ok
+        return probeCall === 1 || probeCall === 2
+      },
+      findPortOwner: async () => 9999,
+      isSupervisedChild: () => false,
+    })
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    expect(captured!.status).toBe("blocked")
+    expect(spawnSpy).not.toHaveBeenCalled()
+
+    captured!.takeover()
+    await tick()
+    await tick()
+    vi.advanceTimersByTime(250)
+    await tick()
+    await tick2()
+
+    expect(killTreeCalls).toEqual([{ pid: 9999, signal: "SIGKILL" }])
+    expect(spawnSpy).toHaveBeenCalledTimes(1)
+    expect(captured!.lines.some((l) => /taking over :7077 from PID 9999/.test(l.text))).toBe(true)
+
+    child.stdout.write("log-server listening on http://127.0.0.1:7077\n")
+    await tick()
+    expect(captured!.status).toBe("running")
+  })
+
+  test("Windows path routes kill through killTree (no child.kill)", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    const { deps, killTreeCalls } = makeDeps()
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    child.stdout.write("listening on http://x\n")
+    await tick()
+    captured!.stop()
+    await tick()
+    // We never call child.kill directly anymore — killTree owns it.
+    expect(child.killCalls).toEqual([])
+    expect(killTreeCalls[0]).toEqual({ pid: child.pid, signal: "SIGTERM" })
+  })
+
+  test("graceful /shutdown: POST succeeds + child exits within timeout, no killTree", async () => {
+    const child = makeFakeChild()
+    const desc: DaemonDescriptor = {
+      key: "vitest",
+      label: "vitest",
+      port: 0,
+      readyRegex: /listening on http:\/\//i,
+      shutdownUrl: "http://127.0.0.1:5179/shutdown",
+      shutdownTimeoutMs: 500,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      spawn: () => child as any,
+    }
+    const fetchCalls: Array<{ url: string; init?: RequestInit }> = []
+    const fakeFetch = (url: string | URL | Request, init?: RequestInit) => {
+      fetchCalls.push({ url: String(url), init })
+      return Promise.resolve(new Response("ok", { status: 200 }))
+    }
+    const { deps, killTreeCalls } = makeDeps({ fetch: fakeFetch as typeof fetch })
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    child.stdout.write("listening on http://x\n")
+    await tick()
+    expect(captured!.status).toBe("running")
+
+    captured!.stop()
+    await tick()
+    expect(captured!.status).toBe("exiting")
+
+    // Let the fetch microtask settle (it's a resolved Promise).
+    await tick()
+    await tick()
+    expect(fetchCalls).toHaveLength(1)
+    expect(fetchCalls[0].url).toBe("http://127.0.0.1:5179/shutdown")
+    expect(fetchCalls[0].init?.method).toBe("POST")
+
+    // Child exits cleanly before the escalation timer fires.
+    child.emit("exit", 0, null)
+    await tick()
+    expect(captured!.status).toBe("exited")
+    expect(killTreeCalls).toHaveLength(0)
+  })
+
+  test("graceful /shutdown: fetch rejects → falls back to killTree", async () => {
+    const child = makeFakeChild()
+    const desc: DaemonDescriptor = {
+      key: "vitest",
+      label: "vitest",
+      port: 0,
+      readyRegex: /listening on http:\/\//i,
+      shutdownUrl: "http://127.0.0.1:5179/shutdown",
+      shutdownTimeoutMs: 500,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      spawn: () => child as any,
+    }
+    const fakeFetch = () => Promise.reject(new Error("ECONNREFUSED"))
+    const { deps, killTreeCalls } = makeDeps({ fetch: fakeFetch as typeof fetch })
+    mount(desc, deps)
+
+    captured!.start()
+    await tick2()
+    child.stdout.write("listening on http://x\n")
+    await tick()
+
+    captured!.stop()
+    await tick()
+    // Fetch rejection microtask flush.
+    await tick()
+    await tick()
+
+    // Now advance past the shutdownTimeoutMs to trigger escalate().
+    vi.advanceTimersByTime(501)
+    await tick()
+
+    expect(killTreeCalls.map((c) => c.signal)).toEqual(["SIGTERM"])
+    expect(killTreeCalls[0].pid).toBe(child.pid)
+
+    // Confirm the error line landed in the ring buffer.
+    expect(
+      captured!.lines.some((l) => /\/shutdown.*ECONNREFUSED/i.test(l.text)),
+    ).toBe(true)
+  })
+
+  test("POSIX path: real killTree invokes process.kill", async () => {
+    const child = makeFakeChild()
+    const desc = makeDescriptor(child)
+    // Don't override killTree — use the real one via the default import path.
+    const { deps } = makeDeps()
+    delete (deps as Partial<UseDaemonProcessDeps>).killTree
+    // Force the POSIX branch.
+    const originalPlatform = process.platform
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true })
+    const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true)
+    try {
+      mount(desc, deps)
+      captured!.start()
+      await tick2()
+      child.stdout.write("listening on http://x\n")
+      await tick()
+      captured!.stop()
+      await tick()
+      // killTree runs via microtask — wait for it.
+      await tick()
+      expect(killSpy).toHaveBeenCalledWith(child.pid, "SIGTERM")
+    } finally {
+      Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true })
+      killSpy.mockRestore()
+    }
+  })
+})

package/src/hooks/useDaemonProcess.ts

@@ -0,0 +1,275 @@
+// Owns one supervised ChildProcess for one DaemonDescriptor.
+//
+// Lifecycle:
+//   idle -> starting -> running   (after stdout matches readyRegex)
+//   running -> exiting -> exited  (after stop() resolves cleanly)
+//   idle   -> blocked             (port-probe found external listener)
+//   * -> crashed                  (exit code non-zero / signal != SIGTERM)
+//
+// Cleanup: on unmount, stop() is invoked. The killTree module handles
+// Windows process-tree teardown so we don't orphan bun grandchildren.
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import type { ChildProcess } from "node:child_process"
+
+import { useRingBuffer, type LogLine } from "./useRingBuffer.ts"
+import type { DaemonDescriptor } from "../lib/daemon-registry.ts"
+import { killTree as defaultKillTree } from "../lib/kill-tree.ts"
+import { findPortOwner as defaultFindPortOwner } from "../lib/port-owner.ts"
+import { probePort as defaultProbePort } from "../lib/port-probe.ts"
+import {
+  isSupervisedChild as defaultIsSupervisedChild,
+  registerChild as defaultRegisterChild,
+  unregisterChild as defaultUnregisterChild,
+} from "../lib/global-teardown.ts"
+
+export type DaemonStatus =
+  | "idle"
+  | "starting"
+  | "running"
+  | "exiting"
+  | "exited"
+  | "crashed"
+  | "blocked"
+
+export type UseDaemonProcessResult = {
+  status: DaemonStatus
+  lines: LogLine[]
+  start: () => void
+  stop: () => void
+  takeover: () => void
+  clear: () => void
+  exitCode: number | null
+}
+
+// Injection seam — tests override these so they don't actually shell out
+// or open sockets.
+export type UseDaemonProcessDeps = {
+  killTree?: (pid: number, signal: "SIGTERM" | "SIGKILL") => Promise<void>
+  findPortOwner?: (host: string, port: number) => Promise<number | null>
+  isSupervisedChild?: (pid: number) => boolean
+  probePort?: (host: string, port: number, timeoutMs?: number) => Promise<boolean>
+  registerChild?: (pid: number) => void
+  unregisterChild?: (pid: number) => void
+  // Pluggable fetch so tests don't open real sockets. Defaults to global.
+  fetch?: typeof globalThis.fetch
+}
+
+const KILL_GRACE_MS = 2_000
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 1_500
+
+// Split incoming chunk into complete lines, buffering the trailing partial
+// line for the next chunk. Returns [completeLines, newBuffer].
+function splitLines(prev: string, chunk: string): [string[], string] {
+  const combined = prev + chunk
+  const parts = combined.split(/\r?\n/)
+  const trailing = parts.pop() ?? ""
+  return [parts, trailing]
+}
+
+export function useDaemonProcess(
+  descriptor: DaemonDescriptor,
+  deps: UseDaemonProcessDeps = {},
+): UseDaemonProcessResult {
+  const killTree = deps.killTree ?? defaultKillTree
+  const findPortOwner = deps.findPortOwner ?? defaultFindPortOwner
+  const isSupervisedChild = deps.isSupervisedChild ?? defaultIsSupervisedChild
+  const probePort = deps.probePort ?? defaultProbePort
+  const registerChild = deps.registerChild ?? defaultRegisterChild
+  const unregisterChild = deps.unregisterChild ?? defaultUnregisterChild
+  const doFetch = deps.fetch ?? globalThis.fetch
+
+  const { lines, push, clear } = useRingBuffer(10_000)
+  const [status, setStatus] = useState<DaemonStatus>("idle")
+  const [exitCode, setExitCode] = useState<number | null>(null)
+  const childRef = useRef<ChildProcess | null>(null)
+  const killTimerRef = useRef<NodeJS.Timeout | null>(null)
+  const readyRef = useRef(false)
+  const stoppingRef = useRef(false)
+  const statusRef = useRef(status)
+  statusRef.current = status
+
+  const clearKillTimer = useCallback(() => {
+    if (killTimerRef.current) {
+      clearTimeout(killTimerRef.current)
+      killTimerRef.current = null
+    }
+  }, [])
+
+  const start = useCallback(() => {
+    if (childRef.current) return
+    readyRef.current = false
+    stoppingRef.current = false
+    setExitCode(null)
+    setStatus("starting")
+
+    const host = descriptor.host ?? "127.0.0.1"
+
+    const doSpawn = (): void => {
+      const child = descriptor.spawn()
+      childRef.current = child
+      if (typeof child.pid === "number") registerChild(child.pid)
+
+      let outBuf = ""
+      let errBuf = ""
+
+      const handleLine = (stream: "out" | "err", text: string): void => {
+        push({ ts: Date.now(), stream, text })
+        if (!readyRef.current && descriptor.readyRegex.test(text)) {
+          readyRef.current = true
+          setStatus("running")
+        }
+      }
+
+      child.stdout?.on("data", (chunk: Buffer) => {
+        const [done, rest] = splitLines(outBuf, chunk.toString("utf8"))
+        outBuf = rest
+        for (const ln of done) handleLine("out", ln)
+      })
+      child.stderr?.on("data", (chunk: Buffer) => {
+        const [done, rest] = splitLines(errBuf, chunk.toString("utf8"))
+        errBuf = rest
+        for (const ln of done) handleLine("err", ln)
+      })
+
+      child.on("error", (err) => {
+        push({ ts: Date.now(), stream: "err", text: `[spawn error] ${err.message}` })
+        setStatus("crashed")
+        if (typeof child.pid === "number") unregisterChild(child.pid)
+        childRef.current = null
+        clearKillTimer()
+      })
+
+      child.on("exit", (code, signal) => {
+        // Flush any trailing buffered output.
+        if (outBuf.length > 0) handleLine("out", outBuf)
+        if (errBuf.length > 0) handleLine("err", errBuf)
+        outBuf = ""
+        errBuf = ""
+
+        setExitCode(code)
+        if (typeof child.pid === "number") unregisterChild(child.pid)
+        childRef.current = null
+        clearKillTimer()
+
+        const stopping = stoppingRef.current
+        // On Windows, taskkill /F sets code != 0 and signal === null even
+        // though we asked for the kill — treat any exit during stop() as
+        // intentional ("exited"), only mark "crashed" for unprompted death.
+        const clean = code === 0 || stopping
+        setStatus(clean ? "exited" : "crashed")
+      })
+    }
+
+    // Port preflight — refuse to spawn if something else is listening.
+    void (async (): Promise<void> => {
+      const inUse = await probePort(host, descriptor.port)
+      if (inUse) {
+        push({
+          ts: Date.now(),
+          stream: "err",
+          text: `port ${descriptor.port} already in use — refusing to spawn`,
+        })
+        setStatus("blocked")
+        return
+      }
+      doSpawn()
+    })()
+  }, [descriptor, push, clearKillTimer, probePort, registerChild, unregisterChild])
+
+  const stop = useCallback(() => {
+    const child = childRef.current
+    if (!child) return
+    if (stoppingRef.current) return
+    stoppingRef.current = true
+    setStatus("exiting")
+
+    const shutdownUrl = descriptor.shutdownUrl
+    const shutdownTimeoutMs = descriptor.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS
+
+    const escalate = (): void => {
+      const c = childRef.current
+      if (!c) return // child already exited cleanly via /shutdown
+      const pid = c.pid
+      if (typeof pid === "number") {
+        void killTree(pid, "SIGTERM")
+      }
+      killTimerRef.current = setTimeout(() => {
+        const cc = childRef.current
+        if (cc && typeof cc.pid === "number") {
+          void killTree(cc.pid, "SIGKILL")
+        }
+      }, KILL_GRACE_MS)
+    }
+
+    if (shutdownUrl) {
+      void (async (): Promise<void> => {
+        try {
+          await doFetch(shutdownUrl, {
+            method: "POST",
+            signal: AbortSignal.timeout(shutdownTimeoutMs),
+          })
+        } catch (err) {
+          // 404, connection refused, timeout — all fine. We log and fall
+          // through to SIGTERM. Don't crash the supervisor on a flaky
+          // shutdown endpoint.
+          const msg = err instanceof Error ? err.message : String(err)
+          push({
+            ts: Date.now(),
+            stream: "err",
+            text: `[shutdown ${descriptor.label}] HTTP /shutdown failed: ${msg}`,
+          })
+        }
+        // Give the child a tick to actually exit gracefully before SIGTERM.
+        killTimerRef.current = setTimeout(escalate, shutdownTimeoutMs)
+      })()
+      return
+    }
+
+    escalate()
+  }, [killTree, descriptor.shutdownUrl, descriptor.shutdownTimeoutMs, descriptor.label, doFetch, push])
+
+  const takeover = useCallback(() => {
+    void (async (): Promise<void> => {
+      if (statusRef.current !== "blocked") return
+      const host = descriptor.host ?? "127.0.0.1"
+      const owner = await findPortOwner(host, descriptor.port)
+      if (owner == null) {
+        push({
+          ts: Date.now(),
+          stream: "err",
+          text: `could not identify owner of :${descriptor.port} — kill it manually`,
+        })
+        return
+      }
+      if (isSupervisedChild(owner)) {
+        push({
+          ts: Date.now(),
+          stream: "out",
+          text: `port owner PID ${owner} is a supervised child — skipping kill`,
+        })
+        return
+      }
+      push({
+        ts: Date.now(),
+        stream: "out",
+        text: `taking over :${descriptor.port} from PID ${owner}`,
+      })
+      await killTree(owner, "SIGKILL")
+      for (let i = 0; i < 8; i++) {
+        if (!(await probePort(host, descriptor.port))) break
+        await new Promise((r) => setTimeout(r, 250))
+      }
+      setStatus("idle")
+      start()
+    })()
+  }, [descriptor, findPortOwner, isSupervisedChild, killTree, probePort, push, start])
+
+  useEffect(() => {
+    return () => {
+      stop()
+    }
+  }, [stop])
+
+  return { status, lines, start, stop, takeover, clear, exitCode }
+}