@davstack/tui 0.2.0

package/src/state/daemons-context.tsx

@@ -0,0 +1,149 @@
+// Holds the live row state (status, lines, exit code) for every daemon
+// plus a controls registry that maps DaemonKey -> {start, stop}.
+//
+// Why not just useDaemonProcess inside this provider?
+// Each daemon needs its own hook call. Rules-of-hooks forbid calling
+// `useDaemonProcess(d)` in a loop where `d` may vary. We keep one
+// <DaemonSupervisor descriptor={d} /> child per descriptor and have it
+// publish state up via `registerRow` / `registerControls`.
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react"
+
+import type { LogLine } from "../hooks/useRingBuffer.ts"
+import type { DaemonStatus } from "../hooks/useDaemonProcess.ts"
+import type { DaemonDescriptor, DaemonKey } from "../lib/daemon-registry.ts"
+
+export type DaemonRow = {
+  descriptor: DaemonDescriptor
+  status: DaemonStatus
+  lines: LogLine[]
+  exitCode?: number | null
+}
+
+export type DaemonControls = {
+  start: () => void
+  stop: () => void
+  takeover?: () => void
+  clear?: () => void
+}
+
+function makeInitialRow(descriptor: DaemonDescriptor): DaemonRow {
+  return { descriptor, status: "idle", lines: [], exitCode: null }
+}
+
+function useDaemonsInner(descriptors: DaemonDescriptor[]) {
+  const [rows, setRows] = useState<DaemonRow[]>(() => descriptors.map(makeInitialRow))
+  const controlsRef = useRef<Map<DaemonKey, DaemonControls>>(new Map())
+  const rowsRef = useRef(rows)
+  rowsRef.current = rows
+
+  // Keep rows aligned with descriptors when discovery resolves later.
+  // We do this in a layout-ish callback (the parent invokes it after the
+  // discovery effect resolves) rather than auto-syncing here, to keep the
+  // provider passive — easier to reason about in tests.
+  const syncDescriptors = useCallback((next: DaemonDescriptor[]) => {
+    setRows((prev) => {
+      const byKey = new Map(prev.map((r) => [r.descriptor.key, r] as const))
+      return next.map((d) => byKey.get(d.key) ?? makeInitialRow(d))
+    })
+  }, [])
+
+  const registerRow = useCallback((row: DaemonRow) => {
+    setRows((prev) => {
+      const idx = prev.findIndex((r) => r.descriptor.key === row.descriptor.key)
+      if (idx === -1) return prev
+      const cur = prev[idx]
+      // Skip no-op updates to avoid React rerender churn.
+      if (
+        cur.status === row.status &&
+        cur.lines === row.lines &&
+        cur.exitCode === row.exitCode
+      ) {
+        return prev
+      }
+      const next = prev.slice()
+      next[idx] = row
+      return next
+    })
+  }, [])
+
+  const registerControls = useCallback((key: DaemonKey, controls: DaemonControls) => {
+    controlsRef.current.set(key, controls)
+  }, [])
+
+  const toggleByKey = useCallback((key: DaemonKey) => {
+    const row = rowsRef.current.find((r) => r.descriptor.key === key)
+    if (!row) return
+    const controls = controlsRef.current.get(key)
+    if (!controls) return
+    if (row.status === "running" || row.status === "starting") controls.stop()
+    else controls.start()
+  }, [])
+
+  const stopAll = useCallback(() => {
+    for (const controls of controlsRef.current.values()) controls.stop()
+  }, [])
+
+  const clearByKey = useCallback((key: DaemonKey) => {
+    const controls = controlsRef.current.get(key)
+    controls?.clear?.()
+  }, [])
+
+  const takeoverByKey = useCallback((key: DaemonKey) => {
+    const row = rowsRef.current.find((r) => r.descriptor.key === key)
+    if (!row || row.status !== "blocked") return
+    const controls = controlsRef.current.get(key)
+    controls?.takeover?.()
+  }, [])
+
+  const anyLive = useCallback(() => {
+    return rowsRef.current.some((r) => r.status === "running" || r.status === "starting")
+  }, [])
+
+  return useMemo(
+    () => ({
+      rows,
+      rowsRef,
+      syncDescriptors,
+      registerRow,
+      registerControls,
+      toggleByKey,
+      stopAll,
+      clearByKey,
+      takeoverByKey,
+      anyLive,
+    }),
+    [rows, syncDescriptors, registerRow, registerControls, toggleByKey, stopAll, clearByKey, takeoverByKey, anyLive],
+  )
+}
+
+type DaemonsContextValue = ReturnType<typeof useDaemonsInner>
+const DaemonsContext = createContext<DaemonsContextValue | undefined>(undefined)
+
+export function DaemonsProvider({
+  descriptors,
+  children,
+}: {
+  descriptors: DaemonDescriptor[]
+  children: ReactNode
+}) {
+  return (
+    <DaemonsContext.Provider value={useDaemonsInner(descriptors)}>
+      {children}
+    </DaemonsContext.Provider>
+  )
+}
+
+export function useDaemons(): DaemonsContextValue {
+  const value = useContext(DaemonsContext)
+  if (!value) throw new Error("useDaemons must be used within a DaemonsProvider")
+  return value
+}

package/src/state/quit-context.tsx

@@ -0,0 +1,27 @@
+// Tracks the "confirm-before-quit" overlay state. Kept separate from
+// QuitController so the dispatcher (useHotkeys) can read `confirming`
+// without depending on the cascade-shutdown wiring.
+
+import React, { createContext, useCallback, useContext, useState, type ReactNode } from "react"
+
+function useQuitInner() {
+  const [confirming, setConfirming] = useState(false)
+
+  const requestConfirm = useCallback(() => setConfirming(true), [])
+  const cancelConfirm = useCallback(() => setConfirming(false), [])
+
+  return { confirming, requestConfirm, cancelConfirm }
+}
+
+type QuitContextValue = ReturnType<typeof useQuitInner>
+const QuitContext = createContext<QuitContextValue | undefined>(undefined)
+
+export function QuitProvider({ children }: { children: ReactNode }) {
+  return <QuitContext.Provider value={useQuitInner()}>{children}</QuitContext.Provider>
+}
+
+export function useQuit(): QuitContextValue {
+  const value = useContext(QuitContext)
+  if (!value) throw new Error("useQuit must be used within a QuitProvider")
+  return value
+}

package/src/state/view-context.tsx

@@ -0,0 +1,32 @@
+// Tracks which view is rendered (daemon list vs a single daemon's logs)
+// and which row in the list has focus. Pattern: useViewInner -> Provider
+// -> useView, see docs/react/client-state-management.mdx for rationale.
+
+import React, { createContext, useCallback, useContext, useState, type ReactNode } from "react"
+
+import type { DaemonKey } from "../lib/daemon-registry.ts"
+
+export type View = { kind: "list" } | { kind: "log"; key: DaemonKey }
+
+function useViewInner() {
+  const [view, setView] = useState<View>({ kind: "list" })
+  const [focusedIdx, setFocusedIdx] = useState(0)
+
+  const showList = useCallback(() => setView({ kind: "list" }), [])
+  const showLog = useCallback((key: DaemonKey) => setView({ kind: "log", key }), [])
+
+  return { view, focusedIdx, setFocusedIdx, showList, showLog }
+}
+
+type ViewContextValue = ReturnType<typeof useViewInner>
+const ViewContext = createContext<ViewContextValue | undefined>(undefined)
+
+export function ViewProvider({ children }: { children: ReactNode }) {
+  return <ViewContext.Provider value={useViewInner()}>{children}</ViewContext.Provider>
+}
+
+export function useView(): ViewContextValue {
+  const value = useContext(ViewContext)
+  if (!value) throw new Error("useView must be used within a ViewProvider")
+  return value
+}

package/src/views/ServerList.test.tsx

@@ -0,0 +1,167 @@
+// ServerList now reads from view + daemons contexts. We wrap it in test
+// providers to render. The `s` toggle dispatches through the daemons
+// context's `toggleByKey`, so we assert at that seam via a controls
+// registry spy plumbed through a hidden helper component.
+
+import React, { useEffect } from "react"
+import { afterEach, expect, test, vi } from "vitest"
+import { render } from "ink-testing-library"
+
+import { ServerList } from "./ServerList.tsx"
+import { ViewProvider } from "../state/view-context.tsx"
+import { DaemonsProvider, useDaemons, type DaemonRow } from "../state/daemons-context.tsx"
+import { QuitProvider } from "../state/quit-context.tsx"
+import type { DaemonDescriptor } from "../lib/daemon-registry.ts"
+
+function makeDescriptor(key: "logs" | "vitest" | "playwright"): DaemonDescriptor {
+  return {
+    key,
+    label: key,
+    port: 1000,
+    readyRegex: /listening/i,
+    spawn: () => {
+      throw new Error("not spawned in this test")
+    },
+  }
+}
+
+// Helper that publishes seeded rows + controls into the context after
+// mount, mimicking what DaemonSupervisor does in production.
+function Seed({
+  rows,
+  startStop,
+}: {
+  rows: DaemonRow[]
+  startStop?: Record<string, { start: () => void; stop: () => void }>
+}): null {
+  const { registerRow, registerControls } = useDaemons()
+  useEffect(() => {
+    for (const row of rows) {
+      registerRow(row)
+      if (startStop?.[row.descriptor.key]) {
+        registerControls(row.descriptor.key, startStop[row.descriptor.key])
+      }
+    }
+  }, [rows, startStop, registerRow, registerControls])
+  return null
+}
+
+let active: ReturnType<typeof render> | null = null
+afterEach(() => {
+  active?.unmount()
+  active = null
+})
+
+test("legend advertises the new hotkeys", () => {
+  const descriptors = [makeDescriptor("logs")]
+  active = render(
+    <ViewProvider>
+      <DaemonsProvider descriptors={descriptors}>
+        <QuitProvider>
+          <ServerList />
+        </QuitProvider>
+      </DaemonsProvider>
+    </ViewProvider>,
+  )
+  const frame = active.lastFrame() ?? ""
+  expect(frame).toContain("s start/stop")
+  expect(frame).toContain("k takeover")
+  expect(frame).toContain("1-9 jump")
+})
+
+test("renders a row per descriptor with the focus marker on idx 0", () => {
+  const descriptors = [makeDescriptor("logs"), makeDescriptor("vitest")]
+  active = render(
+    <ViewProvider>
+      <DaemonsProvider descriptors={descriptors}>
+        <QuitProvider>
+          <ServerList />
+        </QuitProvider>
+      </DaemonsProvider>
+    </ViewProvider>,
+  )
+  const frame = active.lastFrame() ?? ""
+  expect(frame).toContain("› ")
+  expect(frame).toContain("logs")
+  expect(frame).toContain("vitest")
+})
+
+async function tick(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0))
+}
+
+test("toggleByKey dispatches stop() for a running daemon", async () => {
+  const descriptors = [makeDescriptor("logs"), makeDescriptor("vitest")]
+  const stopLogs = vi.fn()
+  const startLogs = vi.fn()
+
+  // Inline accessor to grab the daemons context value and invoke the
+  // toggle the same way the `s` hotkey would. This sidesteps Ink's
+  // raw-mode plumbing — we test the seam where the keystroke arrives.
+  let toggle: ((key: string) => void) | null = null
+  function Capture(): null {
+    const { toggleByKey } = useDaemons()
+    toggle = toggleByKey
+    return null
+  }
+
+  active = render(
+    <ViewProvider>
+      <DaemonsProvider descriptors={descriptors}>
+        <QuitProvider>
+          <Seed
+            rows={[
+              { descriptor: descriptors[0], status: "running", lines: [], exitCode: null },
+              { descriptor: descriptors[1], status: "idle", lines: [], exitCode: null },
+            ]}
+            startStop={{ logs: { start: startLogs, stop: stopLogs } }}
+          />
+          <Capture />
+          <ServerList />
+        </QuitProvider>
+      </DaemonsProvider>
+    </ViewProvider>,
+  )
+  await tick()
+
+  expect(toggle).not.toBeNull()
+  toggle!("logs")
+
+  expect(stopLogs).toHaveBeenCalledTimes(1)
+  expect(startLogs).not.toHaveBeenCalled()
+})
+
+test("toggleByKey dispatches start() for an idle daemon", async () => {
+  const descriptors = [makeDescriptor("logs")]
+  const stopLogs = vi.fn()
+  const startLogs = vi.fn()
+
+  let toggle: ((key: string) => void) | null = null
+  function Capture(): null {
+    const { toggleByKey } = useDaemons()
+    toggle = toggleByKey
+    return null
+  }
+
+  active = render(
+    <ViewProvider>
+      <DaemonsProvider descriptors={descriptors}>
+        <QuitProvider>
+          <Seed
+            rows={[
+              { descriptor: descriptors[0], status: "idle", lines: [], exitCode: null },
+            ]}
+            startStop={{ logs: { start: startLogs, stop: stopLogs } }}
+          />
+          <Capture />
+          <ServerList />
+        </QuitProvider>
+      </DaemonsProvider>
+    </ViewProvider>,
+  )
+  await tick()
+
+  toggle!("logs")
+  expect(startLogs).toHaveBeenCalledTimes(1)
+  expect(stopLogs).not.toHaveBeenCalled()
+})

package/src/views/ServerList.tsx

@@ -0,0 +1,109 @@
+// Daemon list view. Reads rows + focus from context, owns the row-level
+// hotkeys (`↑/↓`, `enter`, `s`). Global hotkeys (`1..9`, `esc`, `q`) live
+// in <GlobalHotkeys>.
+
+import React from "react"
+import { Box, Text, useInput } from "ink"
+
+import type { DaemonStatus } from "../hooks/useDaemonProcess.ts"
+import { useView } from "../state/view-context.tsx"
+import { useDaemons, type DaemonRow } from "../state/daemons-context.tsx"
+import { useHotkeys } from "../hooks/useHotkeys.ts"
+import { useNoColor, colorOrUndef } from "../hooks/useNoColor.ts"
+
+const STATUS_GLYPH: Record<DaemonStatus, string> = {
+  idle: "○",
+  starting: "◐",
+  running: "●",
+  exiting: "◐",
+  exited: "○",
+  crashed: "✗",
+  blocked: "⚠",
+}
+
+// Color scheme: green=running, gray=idle/exited, red=crashed, yellow=blocked.
+// Transition states (starting, exiting) ride along on yellow.
+const STATUS_COLOR: Record<DaemonStatus, string> = {
+  idle: "gray",
+  starting: "yellow",
+  running: "green",
+  exiting: "yellow",
+  exited: "gray",
+  crashed: "red",
+  blocked: "yellow",
+}
+
+export function ServerList(): React.ReactElement {
+  const { rows } = useDaemons()
+  const { focusedIdx, setFocusedIdx, showLog } = useView()
+  // Hotkeys hook gives us the toggle; quit isn't called here so we pass
+  // a noop — the global useInput owns the q routing.
+  const { onToggleFocused } = useHotkeys(() => {})
+
+  const rawModeSupported = process.stdin.isTTY === true
+  useInput(
+    (input, key) => {
+      if (rows.length === 0) return
+      if (key.upArrow) {
+        setFocusedIdx((focusedIdx - 1 + rows.length) % rows.length)
+      } else if (key.downArrow) {
+        setFocusedIdx((focusedIdx + 1) % rows.length)
+      } else if (key.return) {
+        const target = rows[focusedIdx]
+        if (target) showLog(target.descriptor.key)
+      } else if (input === "s") {
+        onToggleFocused()
+      }
+    },
+    { isActive: rawModeSupported },
+  )
+
+  return (
+    <Box flexDirection="column">
+      <Box marginBottom={1}>
+        <Text bold>Daemons</Text>
+      </Box>
+      {rows.map((row, i) => (
+        <DaemonListRow key={row.descriptor.key} row={row} focused={i === focusedIdx} />
+      ))}
+      <Box marginTop={1}>
+        <Text dimColor>
+          ↑/↓ focus  enter drill in  s start/stop  k takeover  1-9 jump  q quit  ● running  ✗ crashed  ⚠ blocked
+        </Text>
+      </Box>
+    </Box>
+  )
+}
+
+function DaemonListRow({ row, focused }: { row: DaemonRow; focused: boolean }): React.ReactElement {
+  const noColor = useNoColor()
+  const last = row.lines[row.lines.length - 1]
+  const lastText = last ? truncate(last.text, 60) : ""
+  const statusLabel =
+    row.status === "crashed" && typeof row.exitCode === "number"
+      ? `crashed (exit ${row.exitCode})`
+      : row.status === "blocked"
+        ? `blocked :${row.descriptor.port}`
+        : row.status
+  const rowColor = row.status === "crashed" ? "red" : undefined
+  return (
+    <Box>
+      <Text color={colorOrUndef(focused ? "cyan" : undefined, noColor)}>
+        {focused ? "› " : "  "}
+      </Text>
+      <Text color={colorOrUndef(STATUS_COLOR[row.status], noColor)}>
+        {STATUS_GLYPH[row.status]}
+      </Text>
+      <Text color={colorOrUndef(rowColor, noColor)}> {row.descriptor.label.padEnd(12)}</Text>
+      <Text color={colorOrUndef(rowColor, noColor)} dimColor={!rowColor}>
+        {statusLabel.padEnd(22)}
+      </Text>
+      <Text dimColor>{lastText}</Text>
+    </Box>
+  )
+}
+
+function truncate(s: string, n: number): string {
+  if (s.length <= n) return s
+  return s.slice(0, n - 1) + "…"
+}

package/src/views/ServerLogView.tsx

@@ -0,0 +1,79 @@
+// Drill-in log view: renders the tail of a daemon's ring buffer to fill
+// the visible terminal height. `esc` (handled by GlobalHotkeys) returns
+// to the list; `c` clears the ring buffer.
+
+import React from "react"
+import { Box, Text, useStdout } from "ink"
+
+import type { LogLine } from "../hooks/useRingBuffer.ts"
+import type { DaemonStatus } from "../hooks/useDaemonProcess.ts"
+import type { DaemonDescriptor } from "../lib/daemon-registry.ts"
+import { useNoColor, colorOrUndef } from "../hooks/useNoColor.ts"
+
+interface ServerLogViewProps {
+  descriptor: DaemonDescriptor
+  status: DaemonStatus
+  lines: LogLine[]
+  exitCode?: number | null
+}
+
+// Same scheme as ServerList — keep these two tables aligned by hand
+// rather than sharing a module, since their domain types differ.
+const STATUS_COLOR: Record<DaemonStatus, string> = {
+  idle: "gray",
+  starting: "yellow",
+  running: "green",
+  exiting: "yellow",
+  exited: "gray",
+  crashed: "red",
+  blocked: "yellow",
+}
+
+export function ServerLogView({
+  descriptor,
+  status,
+  lines,
+  exitCode,
+}: ServerLogViewProps): React.ReactElement {
+  const noColor = useNoColor()
+  const { stdout } = useStdout()
+  const rows = stdout?.rows ?? 24
+  // Reserve a couple of lines for header + footer.
+  const visible = Math.max(5, rows - 4)
+  const tail = lines.slice(-visible)
+
+  return (
+    <Box flexDirection="column">
+      <Box>
+        <Text bold>{descriptor.label}</Text>
+        <Text> </Text>
+        <Text color={colorOrUndef(STATUS_COLOR[status], noColor)}>({status})</Text>
+        <Text dimColor> — port {descriptor.port}</Text>
+      </Box>
+      {status === "crashed" ? (
+        <Box marginTop={1}>
+          <Text color={colorOrUndef("red", noColor)}>
+            daemon exited with code {exitCode ?? "?"} — last logs preserved
+          </Text>
+        </Box>
+      ) : null}
+      <Box flexDirection="column" marginTop={1}>
+        {tail.length === 0 ? (
+          <Text dimColor>(no output yet)</Text>
+        ) : (
+          tail.map((l, i) => (
+            // Per-line color intentionally left default. stderr is used
+            // by most daemons as a diagnostic channel (info/warn lines
+            // routed there to keep stdout clean), so painting it red
+            // misrepresents normal output. The status pill above is the
+            // signal for daemon-level health.
+            <Text key={i}>{l.text}</Text>
+          ))
+        )}
+      </Box>
+      <Box marginTop={1}>
+        <Text dimColor>esc back · c clear · q quit</Text>
+      </Box>
+    </Box>
+  )
+}