@davstack/tui 0.2.0

package/src/lib/kill-tree.test.ts

@@ -0,0 +1,69 @@
+// Verifies killTree shells out to taskkill on Windows and uses
+// process.kill on POSIX. We can't actually fork+kill in unit tests
+// reliably across platforms, so we mock child_process / process.kill.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+
+vi.mock("node:child_process", () => {
+  return {
+    exec: vi.fn(
+      (
+        _cmd: string,
+        cb: (err: Error | null, stdout: string, stderr: string) => void,
+      ) => {
+        cb(null, "", "")
+      },
+    ),
+  }
+})
+
+import { exec } from "node:child_process"
+import { killTree } from "./kill-tree.ts"
+
+const originalPlatform = process.platform
+
+function setPlatform(p: NodeJS.Platform): void {
+  Object.defineProperty(process, "platform", { value: p, configurable: true })
+}
+
+describe("killTree", () => {
+  beforeEach(() => {
+    vi.mocked(exec).mockClear()
+  })
+
+  afterEach(() => {
+    setPlatform(originalPlatform)
+  })
+
+  test("Windows path shells out to taskkill /T /F /PID", async () => {
+    setPlatform("win32")
+    await killTree(1234, "SIGTERM")
+    expect(exec).toHaveBeenCalledTimes(1)
+    const cmd = vi.mocked(exec).mock.calls[0][0]
+    expect(cmd).toBe("taskkill /T /F /PID 1234")
+  })
+
+  test("Windows ignores SIGKILL/SIGTERM distinction (always /F)", async () => {
+    setPlatform("win32")
+    await killTree(99, "SIGKILL")
+    const cmd = vi.mocked(exec).mock.calls[0][0]
+    expect(cmd).toBe("taskkill /T /F /PID 99")
+  })
+
+  test("POSIX path calls process.kill with the given signal", async () => {
+    setPlatform("linux")
+    const spy = vi.spyOn(process, "kill").mockImplementation(() => true)
+    await killTree(1234, "SIGTERM")
+    expect(spy).toHaveBeenCalledWith(1234, "SIGTERM")
+    spy.mockRestore()
+  })
+
+  test("POSIX swallows ESRCH (process already gone)", async () => {
+    setPlatform("linux")
+    const spy = vi.spyOn(process, "kill").mockImplementation(() => {
+      throw new Error("ESRCH")
+    })
+    await expect(killTree(1234, "SIGKILL")).resolves.toBeUndefined()
+    spy.mockRestore()
+  })
+})

package/src/lib/kill-tree.ts

@@ -0,0 +1,31 @@
+// Cross-platform process-tree kill.
+//
+// Windows: shell out to `taskkill /T /F /PID <pid>`. `/T` kills the whole
+// tree (parent + descendants); `/F` is force — `/T` without `/F` is
+// unreliable. The Windows path ignores the signal argument by design — we
+// always hard-terminate because Node's SIGTERM-on-Windows already maps to
+// TerminateProcess anyway, so "graceful" SIGTERM doesn't exist for us.
+//
+// POSIX: best-effort `process.kill(pid, signal)` to the immediate child.
+// We do NOT walk /proc — none of the davstack daemons fork grandchildren
+// on Linux per the spawn audit, and kernel SIGTERM-to-PGID would require
+// `detached:true` on spawn which we deliberately don't do.
+
+import { exec } from "node:child_process"
+
+export async function killTree(
+  pid: number,
+  signal: "SIGTERM" | "SIGKILL",
+): Promise<void> {
+  if (process.platform === "win32") {
+    await new Promise<void>((resolve) => {
+      exec(`taskkill /T /F /PID ${pid}`, () => resolve())
+    })
+    return
+  }
+  try {
+    process.kill(pid, signal)
+  } catch {
+    // Process already gone — nothing to do.
+  }
+}

package/src/lib/package-info.ts

@@ -0,0 +1,35 @@
+// Small helpers for the empty-state block — package version + repo root.
+// Pulled out so MainView doesn't need to deal with JSON-import gymnastics
+// or repo-root throw-paths.
+
+import fs from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { findRepoRoot } from "./repo-root.ts"
+
+let cachedVersion: string | null = null
+
+export function getPackageVersion(): string {
+  if (cachedVersion !== null) return cachedVersion
+  try {
+    // package-info.ts lives at packages/tui/src/lib/. The package.json is
+    // two dirs up.
+    const here = path.dirname(fileURLToPath(import.meta.url))
+    const pkgPath = path.join(here, "..", "..", "package.json")
+    const raw = fs.readFileSync(pkgPath, "utf8")
+    const parsed = JSON.parse(raw) as { version?: string }
+    cachedVersion = parsed.version ?? "0.0.0"
+  } catch {
+    cachedVersion = "0.0.0"
+  }
+  return cachedVersion
+}
+
+export function getRepoRootSafe(): string {
+  try {
+    return findRepoRoot(process.cwd())
+  } catch {
+    return process.cwd()
+  }
+}

package/src/lib/port-owner.test.ts

@@ -0,0 +1,105 @@
+// Mock child_process.exec for netstat / lsof shell-outs. Assert parse for:
+// zero matches → null, single match → that PID, multiple matches → first PID.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+
+vi.mock("node:child_process", () => {
+  return {
+    exec: vi.fn(
+      (
+        _cmd: string,
+        cb: (err: Error | null, stdout: string, stderr: string) => void,
+      ) => {
+        cb(null, "", "")
+      },
+    ),
+  }
+})
+
+import { exec } from "node:child_process"
+import { findPortOwner } from "./port-owner.ts"
+
+const originalPlatform = process.platform
+
+function setPlatform(p: NodeJS.Platform): void {
+  Object.defineProperty(process, "platform", { value: p, configurable: true })
+}
+
+function mockExecStdout(stdout: string): void {
+  vi.mocked(exec).mockImplementation(
+    (_cmd, cb) => {
+      ;(cb as (err: null, stdout: string, stderr: string) => void)(null, stdout, "")
+      return undefined as never
+    },
+  )
+}
+
+describe("findPortOwner", () => {
+  beforeEach(() => {
+    vi.mocked(exec).mockClear()
+  })
+
+  afterEach(() => {
+    setPlatform(originalPlatform)
+  })
+
+  test("Windows: zero netstat matches → null", async () => {
+    setPlatform("win32")
+    mockExecStdout("  TCP    127.0.0.1:8080    0.0.0.0:0    LISTENING    999\n")
+    expect(await findPortOwner("127.0.0.1", 7077)).toBeNull()
+  })
+
+  test("Windows: single LISTENING match → that PID", async () => {
+    setPlatform("win32")
+    mockExecStdout(
+      "  TCP    127.0.0.1:7077         0.0.0.0:0              LISTENING       4242\n",
+    )
+    expect(await findPortOwner("127.0.0.1", 7077)).toBe(4242)
+  })
+
+  test("Windows: 0.0.0.0 bind matches 127.0.0.1 host", async () => {
+    setPlatform("win32")
+    mockExecStdout(
+      "  TCP    0.0.0.0:7077           0.0.0.0:0              LISTENING       5555\n",
+    )
+    expect(await findPortOwner("127.0.0.1", 7077)).toBe(5555)
+  })
+
+  test("Windows: multiple matches → first PID", async () => {
+    setPlatform("win32")
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    mockExecStdout(
+      [
+        "  TCP    127.0.0.1:7077         0.0.0.0:0              LISTENING       1111",
+        "  TCP    0.0.0.0:7077           0.0.0.0:0              LISTENING       2222",
+      ].join("\n"),
+    )
+    expect(await findPortOwner("127.0.0.1", 7077)).toBe(1111)
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  test("POSIX: single lsof match → that PID", async () => {
+    setPlatform("linux")
+    mockExecStdout("4242\n")
+    const pid = await findPortOwner("127.0.0.1", 7077)
+    const cmd = vi.mocked(exec).mock.calls[0][0]
+    expect(cmd).toBe("lsof -nP -iTCP:7077 -sTCP:LISTEN -t")
+    expect(pid).toBe(4242)
+  })
+
+  test("POSIX: empty lsof output → null", async () => {
+    setPlatform("linux")
+    mockExecStdout("")
+    expect(await findPortOwner("127.0.0.1", 7077)).toBeNull()
+  })
+
+  test("POSIX: multiple PIDs → first", async () => {
+    setPlatform("linux")
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {})
+    mockExecStdout("1111\n2222\n")
+    expect(await findPortOwner("127.0.0.1", 7077)).toBe(1111)
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+})

package/src/lib/port-owner.ts

@@ -0,0 +1,90 @@
+// Resolve the PID listening on a TCP port. Pure lookup — no side effects.
+//
+// Windows: `netstat -ano -p tcp` (no admin). POSIX: `lsof` only in v1 — if
+// missing, return null and log rather than trying ss/fuser fallbacks.
+
+import { exec } from "node:child_process"
+
+function execStdout(cmd: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec(cmd, (err, stdout) => {
+      if (err) reject(err)
+      else resolve(stdout)
+    })
+  })
+}
+
+export async function findPortOwner(host: string, port: number): Promise<number | null> {
+  if (process.platform === "win32") {
+    return findPortOwnerWindows(host, port)
+  }
+  return findPortOwnerPosix(port)
+}
+
+function matchesHost(localHost: string, targetHost: string): boolean {
+  if (localHost === "0.0.0.0" || localHost === "[::]" || localHost === "::") return true
+  if (targetHost === "127.0.0.1" && localHost === "127.0.0.1") return true
+  if (targetHost === "localhost" && localHost === "127.0.0.1") return true
+  if (targetHost === "::1" && (localHost === "::1" || localHost === "[::1]")) return true
+  return localHost === targetHost || localHost === `[${targetHost}]`
+}
+
+function parseNetstatLine(line: string, host: string, port: number): number | null {
+  if (!line.includes("LISTENING")) return null
+  const parts = line.trim().split(/\s+/)
+  if (parts.length < 5 || parts[3] !== "LISTENING") return null
+
+  const local = parts[1]
+  const portMatch = local.match(/:(\d+)$/)
+  if (!portMatch || Number(portMatch[1]) !== port) return null
+
+  const localHost = local.slice(0, local.lastIndexOf(":"))
+  if (!matchesHost(localHost, host)) return null
+
+  const pid = Number(parts[4])
+  return Number.isFinite(pid) && pid > 0 ? pid : null
+}
+
+function pickFirstPid(pids: number[], port: number): number | null {
+  if (pids.length === 0) return null
+  if (pids.length > 1) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[davstack tui] multiple PIDs listening on :${port}, using first (${pids[0]})`,
+    )
+  }
+  return pids[0]
+}
+
+async function findPortOwnerWindows(host: string, port: number): Promise<number | null> {
+  try {
+    const stdout = await execStdout("netstat -ano -p tcp")
+    const pids: number[] = []
+    for (const line of stdout.split(/\r?\n/)) {
+      const pid = parseNetstatLine(line, host, port)
+      if (pid != null) pids.push(pid)
+    }
+    return pickFirstPid(pids, port)
+  } catch {
+    return null
+  }
+}
+
+async function findPortOwnerPosix(port: number): Promise<number | null> {
+  try {
+    const stdout = await execStdout(`lsof -nP -iTCP:${port} -sTCP:LISTEN -t`)
+    const pids = stdout
+      .split(/\r?\n/)
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .map(Number)
+      .filter((p) => Number.isFinite(p) && p > 0)
+    return pickFirstPid(pids, port)
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") {
+      // eslint-disable-next-line no-console
+      console.warn("[davstack tui] lsof not found — cannot identify port owner")
+    }
+    return null
+  }
+}

package/src/lib/port-probe.test.ts

@@ -0,0 +1,41 @@
+// 3 cases: open port (real listener), refused (unbound port), timeout.
+
+import net from "node:net"
+import { describe, expect, test } from "vitest"
+
+import { probePort } from "./port-probe.ts"
+
+function listenOn(port: number): Promise<net.Server> {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer()
+    srv.on("error", reject)
+    srv.listen(port, "127.0.0.1", () => resolve(srv))
+  })
+}
+
+function close(srv: net.Server): Promise<void> {
+  return new Promise((resolve) => srv.close(() => resolve()))
+}
+
+describe("probePort", () => {
+  test("returns true when a listener is bound", async () => {
+    const srv = await listenOn(0)
+    const addr = srv.address() as net.AddressInfo
+    const open = await probePort("127.0.0.1", addr.port, 500)
+    expect(open).toBe(true)
+    await close(srv)
+  })
+
+  test("returns false on ECONNREFUSED (no listener)", async () => {
+    // Pick a high port unlikely to be bound. 1 is reserved, never bound.
+    const open = await probePort("127.0.0.1", 1, 500)
+    expect(open).toBe(false)
+  })
+
+  test("returns false on timeout (route to TEST-NET-1)", async () => {
+    // 192.0.2.0/24 is RFC-5737 TEST-NET-1, guaranteed not routable.
+    // With a 50ms timeout we should never connect.
+    const open = await probePort("192.0.2.1", 9, 50)
+    expect(open).toBe(false)
+  })
+})

package/src/lib/port-probe.ts

@@ -0,0 +1,29 @@
+// Single-shot TCP probe — does anything answer on <host>:<port>?
+// Returns true if a connection succeeds (then immediately destroys the
+// socket), false on ECONNREFUSED or timeout. Used as a preflight before
+// spawning a daemon so we can surface "blocked by external process"
+// instead of letting the daemon crash with EADDRINUSE.
+
+import net from "node:net"
+
+export async function probePort(
+  host: string,
+  port: number,
+  timeoutMs: number = 250,
+): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    const sock = new net.Socket()
+    let settled = false
+    const finish = (open: boolean): void => {
+      if (settled) return
+      settled = true
+      sock.destroy()
+      resolve(open)
+    }
+    sock.setTimeout(timeoutMs)
+    sock.once("connect", () => finish(true))
+    sock.once("timeout", () => finish(false))
+    sock.once("error", () => finish(false))
+    sock.connect(port, host)
+  })
+}

package/src/lib/repo-root.test.ts

@@ -0,0 +1,36 @@
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+import { test, expect, describe } from "vitest"
+
+import { findRepoRoot } from "./repo-root.ts"
+
+function mkTmp(prefix: string): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix))
+}
+
+describe("findRepoRoot", () => {
+  test("locates root via pnpm-workspace.yaml from a nested dir", () => {
+    const root = mkTmp("davstack-rr-")
+    fs.writeFileSync(path.join(root, "pnpm-workspace.yaml"), "packages:\n  - 'packages/*'\n")
+    const nested = path.join(root, "packages", "foo", "src", "deep")
+    fs.mkdirSync(nested, { recursive: true })
+    // realpath: tmpdir on macOS/Windows can be a symlink alias.
+    expect(fs.realpathSync(findRepoRoot(nested))).toBe(fs.realpathSync(root))
+  })
+
+  test("locates root via private package.json when no workspace yaml", () => {
+    const root = mkTmp("davstack-rr-")
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "x", private: true }))
+    const nested = path.join(root, "a", "b")
+    fs.mkdirSync(nested, { recursive: true })
+    expect(fs.realpathSync(findRepoRoot(nested))).toBe(fs.realpathSync(root))
+  })
+
+  test("throws when not inside a davstack-shaped repo", () => {
+    const root = mkTmp("davstack-rr-nope-")
+    // No workspace yaml, no private package.json.
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ name: "x" }))
+    expect(() => findRepoRoot(root)).toThrow(/not inside a davstack-shaped repo/)
+  })
+})

package/src/lib/repo-root.ts

@@ -0,0 +1,30 @@
+// Walk up from a starting directory to find the davstack repo root.
+// A davstack-shaped repo has either a `pnpm-workspace.yaml` or a top-level
+// `package.json` with `"private": true` at its root.
+
+import fs from "node:fs"
+import path from "node:path"
+
+export function findRepoRoot(startDir: string): string {
+  let cur = path.resolve(startDir)
+  // Stop at filesystem root.
+  while (true) {
+    if (fs.existsSync(path.join(cur, "pnpm-workspace.yaml"))) return cur
+    const pkgPath = path.join(cur, "package.json")
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const raw = fs.readFileSync(pkgPath, "utf8")
+        const parsed = JSON.parse(raw) as { private?: boolean }
+        if (parsed.private === true) return cur
+      } catch {
+        // Ignore malformed package.json and keep walking.
+      }
+    }
+    const parent = path.dirname(cur)
+    if (parent === cur) break
+    cur = parent
+  }
+  throw new Error(
+    `findRepoRoot: not inside a davstack-shaped repo (no pnpm-workspace.yaml or private package.json found walking up from ${startDir})`,
+  )
+}

package/src/lib/ring-buffer.test.ts

@@ -0,0 +1,63 @@
+import { test, expect, describe } from "vitest"
+
+import { RingBuffer } from "./ring-buffer.ts"
+
+describe("RingBuffer", () => {
+  test("empty buffer has size 0 and empty array", () => {
+    const rb = new RingBuffer<number>(5)
+    expect(rb.size).toBe(0)
+    expect(rb.toArray()).toEqual([])
+  })
+
+  test("partial fill preserves insertion order", () => {
+    const rb = new RingBuffer<number>(5)
+    rb.push(1)
+    rb.push(2)
+    rb.push(3)
+    expect(rb.size).toBe(3)
+    expect(rb.toArray()).toEqual([1, 2, 3])
+  })
+
+  test("exactly-full fill preserves all entries in order", () => {
+    const rb = new RingBuffer<number>(3)
+    rb.push(1)
+    rb.push(2)
+    rb.push(3)
+    expect(rb.size).toBe(3)
+    expect(rb.toArray()).toEqual([1, 2, 3])
+  })
+
+  test("wraps once: oldest entry overwritten", () => {
+    const rb = new RingBuffer<number>(3)
+    rb.push(1)
+    rb.push(2)
+    rb.push(3)
+    rb.push(4)
+    expect(rb.size).toBe(3)
+    expect(rb.toArray()).toEqual([2, 3, 4])
+  })
+
+  test("wraps many times: only last `capacity` entries remain", () => {
+    const rb = new RingBuffer<number>(3)
+    for (let i = 1; i <= 10; i++) rb.push(i)
+    expect(rb.size).toBe(3)
+    expect(rb.toArray()).toEqual([8, 9, 10])
+  })
+
+  test("clear resets size and contents but capacity remains", () => {
+    const rb = new RingBuffer<number>(3)
+    rb.push(1)
+    rb.push(2)
+    rb.clear()
+    expect(rb.size).toBe(0)
+    expect(rb.toArray()).toEqual([])
+    rb.push(42)
+    expect(rb.toArray()).toEqual([42])
+  })
+
+  test("rejects non-positive capacity", () => {
+    expect(() => new RingBuffer<number>(0)).toThrow()
+    expect(() => new RingBuffer<number>(-1)).toThrow()
+    expect(() => new RingBuffer<number>(1.5)).toThrow()
+  })
+})

package/src/lib/ring-buffer.ts

@@ -0,0 +1,47 @@
+// Fixed-capacity circular buffer. Oldest entries overwritten when full.
+// Used to cap memory for live daemon stdout/stderr streams in the TUI.
+
+export class RingBuffer<T> {
+  private buf: (T | undefined)[]
+  private writeIdx = 0
+  private count = 0
+  private readonly capacity: number
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity <= 0) {
+      throw new Error(`RingBuffer capacity must be a positive integer, got ${capacity}`)
+    }
+    this.capacity = capacity
+    this.buf = new Array(capacity)
+  }
+
+  push(item: T): void {
+    this.buf[this.writeIdx] = item
+    this.writeIdx = (this.writeIdx + 1) % this.capacity
+    if (this.count < this.capacity) this.count++
+  }
+
+  toArray(): T[] {
+    const out: T[] = []
+    if (this.count < this.capacity) {
+      for (let i = 0; i < this.count; i++) out.push(this.buf[i] as T)
+      return out
+    }
+    // Full — oldest entry sits at writeIdx (the next slot to overwrite).
+    for (let i = 0; i < this.capacity; i++) {
+      const idx = (this.writeIdx + i) % this.capacity
+      out.push(this.buf[idx] as T)
+    }
+    return out
+  }
+
+  get size(): number {
+    return this.count
+  }
+
+  clear(): void {
+    this.buf = new Array(this.capacity)
+    this.writeIdx = 0
+    this.count = 0
+  }
+}