@davstack/tui 0.2.0

package/src/hooks/useNoColor.test.ts

@@ -0,0 +1,50 @@
+// useNoColor reads env once and caches. Tests must reset the cache
+// before each scenario because the module-level cache survives across
+// tests in the same worker.
+
+import { afterEach, beforeEach, expect, test } from "vitest"
+
+import { __resetNoColorCacheForTests, colorOrUndef, useNoColor } from "./useNoColor.ts"
+
+let prevNoColor: string | undefined
+let prevDavstackNoColor: string | undefined
+
+beforeEach(() => {
+  prevNoColor = process.env.NO_COLOR
+  prevDavstackNoColor = process.env.DAVSTACK_NO_COLOR
+  delete process.env.NO_COLOR
+  delete process.env.DAVSTACK_NO_COLOR
+  __resetNoColorCacheForTests()
+})
+
+afterEach(() => {
+  if (prevNoColor === undefined) delete process.env.NO_COLOR
+  else process.env.NO_COLOR = prevNoColor
+  if (prevDavstackNoColor === undefined) delete process.env.DAVSTACK_NO_COLOR
+  else process.env.DAVSTACK_NO_COLOR = prevDavstackNoColor
+  __resetNoColorCacheForTests()
+})
+
+test("returns false when no env is set", () => {
+  expect(useNoColor()).toBe(false)
+})
+
+test("returns true when NO_COLOR is set to any non-empty value", () => {
+  process.env.NO_COLOR = "1"
+  __resetNoColorCacheForTests()
+  expect(useNoColor()).toBe(true)
+})
+
+test("returns true when DAVSTACK_NO_COLOR is set (mirrors --no-color CLI flag)", () => {
+  process.env.DAVSTACK_NO_COLOR = "1"
+  __resetNoColorCacheForTests()
+  expect(useNoColor()).toBe(true)
+})
+
+test("colorOrUndef returns the value when noColor is false", () => {
+  expect(colorOrUndef("red", false)).toBe("red")
+})
+
+test("colorOrUndef returns undefined when noColor is true", () => {
+  expect(colorOrUndef("red", true)).toBeUndefined()
+})

package/src/hooks/useNoColor.ts

@@ -0,0 +1,35 @@
+// Reads the NO_COLOR signal once at module load. We honour two sources:
+//
+//   1. The `NO_COLOR` environment variable (https://no-color.org) — any
+//      non-empty value disables color.
+//   2. The `DAVSTACK_NO_COLOR` env (set by cli.ts when --no-color is passed).
+//
+// Components call this hook to decide whether to forward `color={...}`
+// props or leave them undefined. Ink doesn't expose a theme-level toggle
+// so each colored seam consults the hook explicitly.
+
+let cached: boolean | null = null
+
+function compute(): boolean {
+  const env = process.env.NO_COLOR
+  if (typeof env === "string" && env.length > 0) return true
+  const dav = process.env.DAVSTACK_NO_COLOR
+  if (typeof dav === "string" && dav.length > 0) return true
+  return false
+}
+
+export function useNoColor(): boolean {
+  if (cached === null) cached = compute()
+  return cached
+}
+
+// Test-only escape hatch — the cache lives at module scope so tests that
+// toggle env need to reset it.
+export function __resetNoColorCacheForTests(): void {
+  cached = null
+}
+
+// Helper for the common "maybe-color" pattern in components.
+export function colorOrUndef(value: string | undefined, noColor: boolean): string | undefined {
+  return noColor ? undefined : value
+}

package/src/hooks/useRingBuffer.test.tsx

@@ -0,0 +1,86 @@
+// Hook test for useRingBuffer via ink-testing-library probe. Asserts that
+// `push` triggers a re-render carrying the new lines, and `clear` resets.
+
+import React from "react"
+import { afterEach, expect, test } from "vitest"
+import { render } from "ink-testing-library"
+import { Text } from "ink"
+
+import { useRingBuffer, type UseRingBufferResult } from "./useRingBuffer.ts"
+
+function Probe({
+  onRender,
+}: {
+  onRender: (r: UseRingBufferResult) => void
+}): React.ReactElement {
+  const r = useRingBuffer(3)
+  onRender(r)
+  return React.createElement(Text, null, `n=${r.lines.length}`)
+}
+
+let active: ReturnType<typeof render> | null = null
+afterEach(() => {
+  active?.unmount()
+  active = null
+})
+
+async function tick(): Promise<void> {
+  await new Promise<void>((resolve) => setImmediate(resolve))
+}
+
+test("push triggers re-render with new lines; clear resets", async () => {
+  let captured: UseRingBufferResult | null = null
+  active = render(
+    React.createElement(Probe, {
+      onRender: (r) => {
+        captured = r
+      },
+    }),
+  )
+
+  expect(captured!.lines).toEqual([])
+
+  captured!.push({ ts: 1, stream: "out", text: "a" })
+  await tick()
+  captured!.push({ ts: 2, stream: "out", text: "b" })
+  await tick()
+  expect(captured!.lines.map((l) => l.text)).toEqual(["a", "b"])
+
+  // Wrap.
+  captured!.push({ ts: 3, stream: "out", text: "c" })
+  captured!.push({ ts: 4, stream: "err", text: "d" })
+  await tick()
+  expect(captured!.lines.map((l) => l.text)).toEqual(["b", "c", "d"])
+
+  captured!.clear()
+  await tick()
+  expect(captured!.lines).toEqual([])
+})
+
+test("lines array reference is stable across renders unless push/clear fires", async () => {
+  // Regression: without memoization, toArray() allocates a fresh array
+  // every render. Consumers that include `lines` in effect deps
+  // (DaemonSupervisor) then loop forever, even when contents are
+  // identical. Lines MUST share a reference between renders that didn't
+  // mutate the buffer.
+  const seenLines: LogLine[][] = []
+  const Spy = (): React.ReactElement => {
+    const r = useRingBuffer(3)
+    seenLines.push(r.lines)
+    return React.createElement(Text, null, " ")
+  }
+
+  active = render(React.createElement(Spy))
+  const initial = seenLines[0]
+  active.rerender(React.createElement(Spy))
+  active.rerender(React.createElement(Spy))
+  active.rerender(React.createElement(Spy))
+
+  expect(seenLines.length).toBeGreaterThanOrEqual(4)
+  for (const snap of seenLines) {
+    expect(snap).toBe(initial)
+  }
+})
+
+// Local type import for the regression test.
+type LogLine = { ts: number; stream: "out" | "err"; text: string }

package/src/hooks/useRingBuffer.ts

@@ -0,0 +1,46 @@
+// React hook wrapping a RingBuffer<LogLine> behind a re-render counter.
+//
+// We deliberately do NOT keep lines in React state — that would force a
+// copy on every push, which gets expensive for chatty daemons. Instead we
+// keep a stable ref, tick a counter on push, and snapshot `toArray()` on
+// each render.
+
+import { useCallback, useMemo, useRef, useState } from "react"
+
+import { RingBuffer } from "../lib/ring-buffer.ts"
+
+export type LogLine = {
+  ts: number
+  stream: "out" | "err"
+  text: string
+}
+
+export type UseRingBufferResult = {
+  lines: LogLine[]
+  push: (line: LogLine) => void
+  clear: () => void
+}
+
+export function useRingBuffer(capacity: number = 10_000): UseRingBufferResult {
+  const bufRef = useRef<RingBuffer<LogLine> | null>(null)
+  if (bufRef.current === null) bufRef.current = new RingBuffer<LogLine>(capacity)
+  const [tick, setTick] = useState(0)
+
+  const push = useCallback((line: LogLine) => {
+    bufRef.current!.push(line)
+    setTick((t) => (t + 1) | 0)
+  }, [])
+
+  const clear = useCallback(() => {
+    bufRef.current!.clear()
+    setTick((t) => (t + 1) | 0)
+  }, [])
+
+  // Snapshot the buffer only when tick changes. Without this memo
+  // every render produces a new array reference, and consumers that
+  // include `lines` in their effect deps (e.g. DaemonSupervisor) loop
+  // forever — even when the buffer's contents are identical.
+  const lines = useMemo(() => bufRef.current!.toArray(), [tick])
+
+  return { lines, push, clear }
+}

package/src/lib/config-discovery.test.ts

@@ -0,0 +1,77 @@
+// Tests for discoverEnabledDaemons — fixture-driven, using a temp dir.
+
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, beforeEach, describe, expect, test } from "vitest"
+
+import { discoverEnabledDaemons, findConfigRoot } from "./config-discovery.ts"
+
+let tmpRoot = ""
+
+beforeEach(async () => {
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), "davstack-tui-cfg-"))
+})
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true })
+})
+
+async function writeConfig(name: string): Promise<void> {
+  const dir = path.join(tmpRoot, ".davstack", "config")
+  await fs.mkdir(dir, { recursive: true })
+  await fs.writeFile(path.join(dir, name), "export default {}\n", "utf8")
+}
+
+describe("discoverEnabledDaemons", () => {
+  test("returns all three keys when all configs present", async () => {
+    await writeConfig("logs-server.config.ts")
+    await writeConfig("vitest-server.config.ts")
+    await writeConfig("playwright-server.config.ts")
+    const set = await discoverEnabledDaemons(tmpRoot)
+    expect(set).toEqual(new Set(["logs", "vitest", "playwright"]))
+  })
+
+  test("returns only the subset that exists", async () => {
+    await writeConfig("logs-server.config.ts")
+    await writeConfig("vitest-server.config.ts")
+    const set = await discoverEnabledDaemons(tmpRoot)
+    expect(set).toEqual(new Set(["logs", "vitest"]))
+  })
+
+  test("returns empty set when .davstack/config is missing entirely", async () => {
+    const set = await discoverEnabledDaemons(tmpRoot)
+    expect(set.size).toBe(0)
+  })
+
+  test("ignores unrecognized files in the config dir", async () => {
+    await writeConfig("logs-server.config.ts")
+    await writeConfig("README.md")
+    await writeConfig("open-agents.config.ts")
+    const set = await discoverEnabledDaemons(tmpRoot)
+    expect(set).toEqual(new Set(["logs"]))
+  })
+})
+
+describe("findConfigRoot", () => {
+  test("returns the dir holding .davstack/config when called from itself", async () => {
+    await writeConfig("logs-server.config.ts")
+    expect(findConfigRoot(tmpRoot)).toBe(path.resolve(tmpRoot))
+  })
+
+  test("walks up from a workspace subdir to find the configs", async () => {
+    await writeConfig("logs-server.config.ts")
+    const sub = path.join(tmpRoot, "apps", "web", "src")
+    await fs.mkdir(sub, { recursive: true })
+    expect(findConfigRoot(sub)).toBe(path.resolve(tmpRoot))
+  })
+
+  test("returns null when no .davstack/config exists on the chain", async () => {
+    const lonelyDir = await fs.mkdtemp(path.join(os.tmpdir(), "davstack-noconf-"))
+    try {
+      expect(findConfigRoot(lonelyDir)).toBe(null)
+    } finally {
+      await fs.rm(lonelyDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/lib/config-discovery.ts

@@ -0,0 +1,57 @@
+// Discover which davstack daemons are configured in the current repo.
+//
+// v1 strategy: existence-check `.davstack/config/<tool>.config.ts`. The
+// daemon packages themselves load these via tsx — the TUI does NOT parse
+// them. Ports/hosts stay hardcoded in daemon-registry.ts for now.
+//
+// TODO: tolerant regex parse of `port:` / `host:` / `enabled:` from
+// the config file text, OR have the daemons emit a resolved config JSON
+// that the TUI can read.
+
+import fs from "node:fs/promises"
+import fsSync from "node:fs"
+import path from "node:path"
+
+import type { DaemonKey } from "./daemon-registry.ts"
+
+// File name -> daemon key. Mirrors the templates in
+// packages/init/src/templates/. Daemons whose config file isn't present
+// won't render a row in the TUI.
+const CONFIG_FILE_TO_KEY: Record<string, DaemonKey> = {
+  "logs-server.config.ts": "logs",
+  "vitest-server.config.ts": "vitest",
+  "playwright-server.config.ts": "playwright",
+}
+
+export async function discoverEnabledDaemons(repoRoot: string): Promise<Set<DaemonKey>> {
+  const configDir = path.join(repoRoot, ".davstack", "config")
+  const enabled = new Set<DaemonKey>()
+  let entries: string[]
+  try {
+    entries = await fs.readdir(configDir)
+  } catch {
+    return enabled
+  }
+  for (const entry of entries) {
+    const key = CONFIG_FILE_TO_KEY[entry]
+    if (key !== undefined) enabled.add(key)
+  }
+  return enabled
+}
+
+// Walk up from `startDir` looking for the nearest `.davstack/config/`
+// directory; returns the parent dir (treat as the config root) or null.
+// Consumers can park `.davstack/config/` at the monorepo root while
+// running the TUI from a workspace subdir.
+export function findConfigRoot(startDir: string): string | null {
+  let dir = path.resolve(startDir)
+  while (true) {
+    try {
+      const stat = fsSync.statSync(path.join(dir, ".davstack", "config"))
+      if (stat.isDirectory()) return dir
+    } catch {}
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}

package/src/lib/daemon-registry.ts

@@ -0,0 +1,143 @@
+// Static registry of supervisable davstack daemons.
+//
+// Each descriptor wraps a `spawn()` factory that returns an attached
+// ChildProcess with piped stdout/stderr (NOT inherited — we want the TUI
+// to capture the streams into a ring buffer).
+//
+// Per-daemon defaults (read from each daemon's `src/index.ts`):
+//
+//   logs-server       port=7077  ready=/listening on http:\/\//i
+//                     bin: packages/logs-server/bin/logs-server.mjs
+//                     shutdown route: NONE (no /shutdown endpoint; SIGTERM only)
+//
+//   vitest-server     port=5179  ready=/\[vitest-server\] listening on http:\/\//i
+//                     bin: packages/vitest-server/bin/vitest-server.mjs
+//                     shutdown route: POST http://127.0.0.1:5179/shutdown
+//                     (see packages/vitest-server/src/http.ts:60)
+//
+//   playwright-server port=5180  ready=/\[playwright-server\] listening on http:\/\//i
+//                     bin: packages/playwright-server/bin/playwright-server.mjs
+//                     shutdown route: POST http://127.0.0.1:5180/shutdown
+//                     (see packages/playwright-server/src/http.ts:76)
+//
+// TODO(P5+): parse `.davstack/config/<tool>.config.ts` to honor user-set
+// ports/hosts. For v1 we existence-check the config files (see
+// config-discovery.ts) and keep these hardcoded defaults.
+
+import { spawn, type ChildProcess } from "node:child_process"
+import fs from "node:fs"
+import path from "node:path"
+
+import { findRepoRoot } from "./repo-root.ts"
+
+export type DaemonKey = "logs" | "vitest" | "playwright"
+
+export type DaemonDescriptor = {
+  key: DaemonKey
+  label: string
+  port: number
+  host?: string
+  readyRegex: RegExp
+  spawn: () => ChildProcess
+  // When set, stop() POSTs to this URL before falling back to killTree.
+  shutdownUrl?: string
+  // Grace period for the HTTP /shutdown round-trip + clean child exit
+  // before SIGTERM escalation. Defaults to 1500ms in useDaemonProcess.
+  shutdownTimeoutMs?: number
+}
+
+const LOGS_DEFAULT_PORT = 7077
+const VITEST_DEFAULT_PORT = 5179
+const PLAYWRIGHT_DEFAULT_PORT = 5180
+
+const DEFAULT_HOST = "127.0.0.1"
+
+function pkgLauncher(pkgName: string, binName: string): string {
+  // Walk up from cwd looking for node_modules/@davstack/<pkg>/bin/<bin>.mjs.
+  // We can't use require.resolve('@davstack/<pkg>/package.json') because
+  // Node's strict exports field blocks subpath access to /package.json
+  // for every daemon package (they only export `.` and `./config`).
+  let dir = process.cwd()
+  while (true) {
+    const candidate = path.join(
+      dir,
+      "node_modules",
+      "@davstack",
+      pkgName,
+      "bin",
+      `${binName}.mjs`,
+    )
+    if (fs.existsSync(candidate)) return candidate
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  // Fallback: in-repo dev (running from the davstack monorepo itself).
+  const repoRoot = findRepoRoot(process.cwd())
+  return path.join(repoRoot, "packages", pkgName, "bin", `${binName}.mjs`)
+}
+
+function spawnLauncher(launcher: string, args: string[]): ChildProcess {
+  return spawn(process.execPath, [launcher, ...args], {
+    stdio: ["ignore", "pipe", "pipe"],
+    windowsHide: true,
+  })
+}
+
+export const daemonRegistry: DaemonDescriptor[] = [
+  {
+    key: "logs",
+    label: "logs",
+    port: LOGS_DEFAULT_PORT,
+    host: DEFAULT_HOST,
+    readyRegex: /listening on http:\/\//i,
+    spawn: () =>
+      spawnLauncher(pkgLauncher("logs-server", "logs-server"), [
+        "serve",
+        "--port",
+        String(LOGS_DEFAULT_PORT),
+        "--host",
+        DEFAULT_HOST,
+      ]),
+  },
+  {
+    key: "vitest",
+    label: "vitest",
+    port: VITEST_DEFAULT_PORT,
+    host: DEFAULT_HOST,
+    readyRegex: /\[vitest-server\] listening on http:\/\//i,
+    shutdownUrl: `http://${DEFAULT_HOST}:${VITEST_DEFAULT_PORT}/shutdown`,
+    spawn: () => {
+      const repoRoot = findRepoRoot(process.cwd())
+      return spawnLauncher(pkgLauncher("vitest-server", "vitest-server"), [
+        "serve",
+        "--port",
+        String(VITEST_DEFAULT_PORT),
+        "--host",
+        DEFAULT_HOST,
+        "--cwd",
+        repoRoot,
+      ])
+    },
+  },
+  {
+    key: "playwright",
+    label: "playwright",
+    port: PLAYWRIGHT_DEFAULT_PORT,
+    host: DEFAULT_HOST,
+    readyRegex: /\[playwright-server\] listening on http:\/\//i,
+    shutdownUrl: `http://${DEFAULT_HOST}:${PLAYWRIGHT_DEFAULT_PORT}/shutdown`,
+    spawn: () => {
+      const repoRoot = findRepoRoot(process.cwd())
+      return spawnLauncher(pkgLauncher("playwright-server", "playwright-server"), [
+        "serve",
+        "--port",
+        String(PLAYWRIGHT_DEFAULT_PORT),
+        "--host",
+        DEFAULT_HOST,
+        "--cwd",
+        repoRoot,
+      ])
+    },
+  },
+]

package/src/lib/global-teardown.test.ts

@@ -0,0 +1,75 @@
+// Register a fake PID, assert it shows up in the snapshot, install
+// handlers, fire an uncaughtException, assert taskkill/process.kill was
+// invoked. We mock child_process.exec so no real taskkill runs.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest"
+
+vi.mock("node:child_process", () => {
+  return { exec: vi.fn() }
+})
+
+import { exec } from "node:child_process"
+import {
+  _resetForTests,
+  _supervisedSnapshot,
+  installGlobalTeardown,
+  registerChild,
+  unregisterChild,
+} from "./global-teardown.ts"
+
+const originalPlatform = process.platform
+
+function setPlatform(p: NodeJS.Platform): void {
+  Object.defineProperty(process, "platform", { value: p, configurable: true })
+}
+
+describe("global-teardown", () => {
+  let exitSpy: ReturnType<typeof vi.spyOn>
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>
+
+  beforeEach(() => {
+    _resetForTests()
+    vi.mocked(exec).mockClear()
+    // Stub process.exit so the test doesn't actually terminate.
+    exitSpy = vi.spyOn(process, "exit").mockImplementation(((_c?: number) => {
+      return undefined as never
+    }) as never)
+    consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    setPlatform(originalPlatform)
+    process.removeAllListeners("uncaughtException")
+    process.removeAllListeners("unhandledRejection")
+    exitSpy.mockRestore()
+    consoleErrorSpy.mockRestore()
+    _resetForTests()
+  })
+
+  test("register/unregister manages the supervised set", () => {
+    registerChild(111)
+    registerChild(222)
+    expect(_supervisedSnapshot().sort()).toEqual([111, 222])
+    unregisterChild(111)
+    expect(_supervisedSnapshot()).toEqual([222])
+  })
+
+  test("uncaughtException handler kills registered children on Windows", () => {
+    setPlatform("win32")
+    registerChild(4242)
+    installGlobalTeardown()
+    process.emit("uncaughtException", new Error("boom"))
+    expect(exec).toHaveBeenCalledWith("taskkill /T /F /PID 4242")
+    expect(exitSpy).toHaveBeenCalledWith(1)
+  })
+
+  test("uncaughtException handler uses process.kill on POSIX", () => {
+    setPlatform("linux")
+    registerChild(7777)
+    const killSpy = vi.spyOn(process, "kill").mockImplementation(() => true)
+    installGlobalTeardown()
+    process.emit("uncaughtException", new Error("boom"))
+    expect(killSpy).toHaveBeenCalledWith(7777, "SIGKILL")
+    killSpy.mockRestore()
+  })
+})

package/src/lib/global-teardown.ts

@@ -0,0 +1,78 @@
+// Process-level emergency teardown.
+//
+// Keeps a module-level Set of supervised child PIDs. `useDaemonProcess`
+// registers on spawn and unregisters on exit. If the TUI itself dies
+// (uncaughtException / unhandledRejection / process.exit), we synchronously
+// best-effort kill the lot so we don't leave orphan bun/node grandchildren.
+//
+// `exit` is sync — we fire taskkill /T /F on Windows (the OS handles
+// reaping) and process.kill SIGKILL elsewhere. We do NOT await; if the
+// process is on its way out anyway, the OS will clean us up.
+
+import { exec } from "node:child_process"
+
+const supervised = new Set<number>()
+let installed = false
+
+export function registerChild(pid: number): void {
+  if (pid > 0) supervised.add(pid)
+}
+
+export function unregisterChild(pid: number): void {
+  supervised.delete(pid)
+}
+
+export function isSupervisedChild(pid: number): boolean {
+  return supervised.has(pid)
+}
+
+// Sync best-effort kill — used inside process exit handlers where async
+// has no time to run.
+function killAllSync(): void {
+  for (const pid of supervised) {
+    try {
+      if (process.platform === "win32") {
+        // Fire-and-forget. We're inside an exit handler — don't await.
+        exec(`taskkill /T /F /PID ${pid}`)
+      } else {
+        process.kill(pid, "SIGKILL")
+      }
+    } catch {
+      // Ignore — best effort.
+    }
+  }
+}
+
+export function installGlobalTeardown(): void {
+  if (installed) return
+  installed = true
+
+  process.on("exit", () => {
+    killAllSync()
+  })
+
+  process.on("uncaughtException", (err) => {
+    killAllSync()
+    // Re-surface so the user actually sees what crashed.
+    // eslint-disable-next-line no-console
+    console.error("[davstack tui] uncaughtException — killed children:", err)
+    process.exit(1)
+  })
+
+  process.on("unhandledRejection", (reason) => {
+    killAllSync()
+    // eslint-disable-next-line no-console
+    console.error("[davstack tui] unhandledRejection — killed children:", reason)
+    process.exit(1)
+  })
+}
+
+// Test-only helpers.
+export function _resetForTests(): void {
+  supervised.clear()
+  installed = false
+}
+
+export function _supervisedSnapshot(): number[] {
+  return Array.from(supervised)
+}