herm-tui 1.0.0-dev.1

package/src/utils/control.ts

@@ -0,0 +1,495 @@
+/**
+ * control.ts — HTTP control server for headless/automated interaction.
+ *
+ * Runs on CONTROL_PORT (default 7777) when CONTROL=1 env is set.
+ * Exposes imperative actions: tab navigation, message sending, perf dumps,
+ * key injection, and DOM queries for automated testing.
+ *
+ * Usage:
+ *   CONTROL=1 bun run dev              # start with control server
+ *   curl localhost:7777/status          # get app state
+ *   curl localhost:7777/tab/3           # switch to Sessions tab
+ *   curl -X POST localhost:7777/send -d '{"message":"hello"}'
+ *   curl -X POST localhost:7777/key -d '{"name":"tab"}'
+ *   curl localhost:7777/focus           # get focus tree
+ *   curl localhost:7777/perf            # dump perf report
+ *
+ * The bridge is set by AppInner via control.setBridge({...}).
+ *
+ * SAFETY: Key injection is blocked for keys that would mutate state
+ * on dangerous tabs (Config, Sessions) unless safe=false is passed.
+ */
+
+import * as perf from "./perf"
+import { TABS, TAB_MAX, CHAT_TAB } from "../app/tabs"
+
+const PORT = Number(process.env.CONTROL_PORT) || 7777
+export const enabled = process.env.CONTROL === "1"
+
+const TAB_NAMES: readonly string[] = TABS.map(t => t.name)
+
+type Bridge = {
+  tab: () => number
+  setTab: (n: number) => void
+  send: (msg: string) => void
+  ready: () => boolean
+  streaming: () => boolean
+  messages: () => number
+  session: () => string
+  input: () => string
+  setInput: (v: string) => void
+  focusRegion: () => "input" | "content"
+  setFocusRegion: (r: "input" | "content") => void
+  renderer: () => unknown // OpenTUI renderer instance
+  logs: (n?: number) => string
+}
+
+let bridge: Bridge | null = null
+let pendingTab: number | null = null
+
+export function setBridge(b: Bridge) {
+  bridge = b
+}
+
+function currentTab(): number {
+  if (pendingTab !== null) return pendingTab
+  return bridge?.tab() ?? 0
+}
+
+const json = (data: unknown, status = 200) =>
+  new Response(JSON.stringify(data), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  })
+
+// Keys that can mutate state on specific tabs
+const DANGEROUS_KEYS: Record<number, Set<string>> = {
+  1: new Set(["return"]),           // Chat: Enter sends message
+  3: new Set(["d", "delete", "return"]), // Sessions: d=delete, Enter=switch session
+  8: new Set(["space", "return", "h", "l", "]", "[", "ctrl+s"]), // Config: toggles, edits, save
+  9: new Set(["return", "space", "d", "delete"]), // Env: potential mutations
+}
+
+function isDangerous(tab: number, keyName: string, ctrl: boolean): boolean {
+  const set = DANGEROUS_KEYS[tab]
+  if (!set) return false
+  const id = ctrl ? `ctrl+${keyName}` : keyName
+  return set.has(id)
+}
+
+// ─── Key injection ───────────────────────────────────────────────────
+
+interface ParsedKey {
+  name: string
+  ctrl: boolean
+  meta: boolean
+  shift: boolean
+  option: boolean
+  sequence: string
+  number: boolean
+  raw: string
+  eventType: "press" | "release"
+  source: "raw" | "kitty"
+  repeated?: boolean
+}
+
+function makeKey(opts: {
+  name: string
+  ctrl?: boolean
+  shift?: boolean
+  meta?: boolean
+  raw?: string
+}): ParsedKey {
+  return {
+    name: opts.name,
+    ctrl: opts.ctrl ?? false,
+    meta: opts.meta ?? false,
+    shift: opts.shift ?? false,
+    option: false,
+    sequence: opts.raw ?? opts.name,
+    number: false,
+    raw: opts.raw ?? opts.name,
+    eventType: "press",
+    source: "raw",
+  }
+}
+
+function injectKey(renderer: unknown, key: ParsedKey): boolean {
+  const r = renderer as { keyInput?: { processParsedKey?: (k: ParsedKey) => boolean } }
+  if (!r?.keyInput?.processParsedKey) return false
+  return r.keyInput.processParsedKey(key)
+}
+
+// ─── Focus tree query ────────────────────────────────────────────────
+
+interface FocusNode {
+  type: string
+  focused: boolean
+  focusable: boolean
+  children: FocusNode[]
+  text?: string
+}
+
+type AnyNode = {
+  constructor?: { name?: string }
+  focused?: boolean
+  focusable?: boolean
+  getChildren?: () => AnyNode[]
+  getChildrenCount?: () => number
+  _childrenInLayoutOrder?: AnyNode[]
+  textContent?: string
+  text?: string
+  value?: string
+  id?: string
+  _type?: string
+  tagName?: string
+}
+
+function getNodeChildren(n: AnyNode): AnyNode[] {
+  if (n.getChildren) return n.getChildren()
+  if (n._childrenInLayoutOrder) return [...n._childrenInLayoutOrder]
+  return []
+}
+
+function getNodeType(n: AnyNode): string {
+  return n._type || n.tagName || n.constructor?.name || "unknown"
+}
+
+function buildFocusTree(node: unknown, depth = 0): FocusNode | null {
+  if (!node || typeof node !== "object") return null
+  const n = node as AnyNode
+
+  const type = getNodeType(n)
+  const focused = n.focused ?? false
+  const focusable = n.focusable ?? false
+  const children: FocusNode[] = []
+
+  if (depth < 20) {
+    for (const child of getNodeChildren(n)) {
+      const c = buildFocusTree(child, depth + 1)
+      if (c) children.push(c)
+    }
+  }
+
+  // Skip non-focusable nodes with no focusable descendants
+  const hasFocusable = focusable || children.some(c =>
+    c.focusable || c.focused || c.children.length > 0
+  )
+  if (!hasFocusable && !focused && depth > 0) return null
+
+  const text = (n.value || n.textContent || n.text || undefined) as string | undefined
+
+  return { type, focused, focusable, children, text }
+}
+
+function findFocused(node: unknown): string | null {
+  if (!node || typeof node !== "object") return null
+  const n = node as AnyNode
+  if (n.focused) return getNodeType(n)
+  for (const child of getNodeChildren(n)) {
+    const found = findFocused(child)
+    if (found) return found
+  }
+  return null
+}
+
+function countNodes(node: unknown): { total: number; focusable: number; focused: number } {
+  const result = { total: 0, focusable: 0, focused: 0 }
+  function walk(n: unknown) {
+    if (!n || typeof n !== "object") return
+    const nd = n as AnyNode
+    result.total++
+    if (nd.focusable) result.focusable++
+    if (nd.focused) result.focused++
+    for (const child of getNodeChildren(nd)) walk(child)
+  }
+  walk(node)
+  return result
+}
+
+// ─── Request handler ─────────────────────────────────────────────────
+
+async function handle(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const path = url.pathname
+
+  if (!bridge) return json({ error: "bridge not ready" }, 503)
+
+  // GET /status — app state snapshot
+  if (path === "/status") {
+    const m = process.memoryUsage()
+    const tab = currentTab()
+    // Clear pending tab once React has had time to commit
+    pendingTab = null
+    return json({
+      tab,
+      tabName: TAB_NAMES[tab] ?? "unknown",
+      ready: bridge.ready(),
+      streaming: bridge.streaming(),
+      messages: bridge.messages(),
+      session: bridge.session(),
+      input: bridge.input(),
+      focusRegion: bridge.focusRegion(),
+      rss: Math.round(m.rss / 1024 / 1024),
+      heap: Math.round(m.heapUsed / 1024 / 1024),
+    })
+  }
+
+  // GET /tab/:n — switch tab by injecting Ctrl+Right/Left key events
+  const tabMatch = path.match(/^\/tab\/(\d+)$/)
+  if (tabMatch) {
+    const n = Number(tabMatch[1])
+    if (n < 0 || n > TAB_MAX) return json({ error: `tab 0-${TAB_MAX}` }, 400)
+
+    const renderer = bridge.renderer()
+    if (renderer) {
+      // Inject Ctrl+Left/Right keys to navigate to target tab
+      const cur = bridge.tab()
+      const diff = n - cur
+      if (diff !== 0) {
+        const keyName = diff > 0 ? "right" : "left"
+        const steps = Math.abs(diff)
+        for (let i = 0; i < steps; i++) {
+          injectKey(renderer, makeKey({ name: keyName, ctrl: true }))
+        }
+      }
+    } else {
+      // Fallback to direct setState (may not work reliably)
+      bridge.setTab(n)
+    }
+    pendingTab = n
+    return json({ tab: n, tabName: TAB_NAMES[n] })
+  }
+
+  // POST /send — send a message
+  if (path === "/send" && req.method === "POST") {
+    const body = await req.json() as { message?: string }
+    if (!body.message) return json({ error: "message required" }, 400)
+    if (!bridge.ready()) return json({ error: "not connected" }, 503)
+    if (bridge.streaming()) return json({ error: "already streaming" }, 409)
+    bridge.send(body.message)
+    return json({ sent: true, message: body.message })
+  }
+
+  // POST /key — inject a key event
+  //
+  // Body: { name: "tab", ctrl?: bool, shift?: bool, meta?: bool, raw?: string, safe?: bool }
+  //
+  // safe (default true): blocks keys known to mutate state on current tab.
+  // Set safe=false to override (use for intentional mutation testing).
+  if (path === "/key" && req.method === "POST") {
+    const body = await req.json() as {
+      name?: string
+      ctrl?: boolean
+      shift?: boolean
+      meta?: boolean
+      raw?: string
+      safe?: boolean
+    }
+    if (!body.name) return json({ error: "name required" }, 400)
+
+    const renderer = bridge.renderer()
+    if (!renderer) return json({ error: "renderer not available" }, 503)
+
+    const safe = body.safe !== false // default true
+    const tab = currentTab()
+
+    if (safe && isDangerous(tab, body.name, !!body.ctrl)) {
+      return json({
+        error: "blocked",
+        reason: `Key "${body.ctrl ? "ctrl+" : ""}${body.name}" is dangerous on tab ${TAB_NAMES[tab]} (index ${tab}). Pass safe=false to override.`,
+        tab,
+        tabName: TAB_NAMES[tab],
+      }, 403)
+    }
+
+    const key = makeKey({
+      name: body.name,
+      ctrl: body.ctrl,
+      shift: body.shift,
+      meta: body.meta,
+      raw: body.raw ?? (body.name.length === 1 ? body.name : ""),
+    })
+
+    const handled = injectKey(renderer, key)
+    return json({ injected: true, handled, key: body.name, tab, tabName: TAB_NAMES[tab] })
+  }
+
+  // POST /keys — inject a sequence of key events
+  //
+  // Body: { keys: [{name, ctrl?, ...}, ...], delay?: number, safe?: bool }
+  if (path === "/keys" && req.method === "POST") {
+    const body = await req.json() as {
+      keys?: Array<{ name: string; ctrl?: boolean; shift?: boolean; meta?: boolean; raw?: string }>
+      delay?: number
+      safe?: boolean
+    }
+    if (!body.keys?.length) return json({ error: "keys array required" }, 400)
+
+    const renderer = bridge.renderer()
+    if (!renderer) return json({ error: "renderer not available" }, 503)
+
+    const safe = body.safe !== false
+    const tab = currentTab()
+    const delay = body.delay ?? 0
+    const results: Array<{ key: string; injected: boolean; handled: boolean; blocked?: boolean }> = []
+
+    for (const k of body.keys) {
+      if (safe && isDangerous(currentTab(), k.name, !!k.ctrl)) {
+        results.push({ key: k.name, injected: false, handled: false, blocked: true })
+        continue
+      }
+      const key = makeKey({
+        name: k.name,
+        ctrl: k.ctrl,
+        shift: k.shift,
+        meta: k.meta,
+        raw: k.raw ?? (k.name.length === 1 ? k.name : ""),
+      })
+      const handled = injectKey(renderer, key)
+      results.push({ key: k.name, injected: true, handled })
+      if (delay > 0) await new Promise(r => setTimeout(r, delay))
+    }
+
+    return json({ results, tab, tabName: TAB_NAMES[tab] })
+  }
+
+  // POST /type — inject a string as individual keystrokes
+  //
+  // Body: { text: "hello", safe?: bool, delay?: ms }
+  // delay paces characters for cinematic typing (demo recordings).
+  if (path === "/type" && req.method === "POST") {
+    const body = await req.json() as { text?: string; safe?: boolean; delay?: number }
+    if (!body.text) return json({ error: "text required" }, 400)
+
+    const renderer = bridge.renderer()
+    if (!renderer) return json({ error: "renderer not available" }, 503)
+
+    const safe = body.safe !== false
+    const tab = currentTab()
+    const delay = body.delay ?? 0
+    let count = 0
+
+    for (const ch of body.text) {
+      if (safe && isDangerous(tab, ch, false)) continue
+      const key = makeKey({ name: ch, raw: ch })
+      injectKey(renderer, key)
+      count++
+      if (delay > 0) await new Promise(r => setTimeout(r, delay))
+    }
+
+    return json({ typed: count, total: body.text.length, tab, tabName: TAB_NAMES[tab] })
+  }
+
+  // POST /input — set composer value in one shot (no per-char keys).
+  if (path === "/input" && req.method === "POST") {
+    const body = await req.json() as { text?: string }
+    bridge.setInput(body.text ?? "")
+    return json({ ok: true, text: body.text ?? "" })
+  }
+
+  // GET /quit — clean exit so a recording PTY sees EOF. Macrotask so the
+  // 200 flushes before the process dies.
+  if (path === "/quit") {
+    setTimeout(() => process.exit(0), 10)
+    return json({ ok: true })
+  }
+
+  // GET /focus — focus tree (focusable elements and their state)
+  if (path === "/focus") {
+    const r = bridge.renderer() as {
+      root?: unknown
+      currentFocusedRenderable?: AnyNode | null
+    } | null
+    if (!r?.root) return json({ error: "no renderer root" }, 503)
+    const counts = countNodes(r.root)
+    const tree = buildFocusTree(r.root)
+    const focused = findFocused(r.root)
+    const currentFocus = r.currentFocusedRenderable
+      ? getNodeType(r.currentFocusedRenderable)
+      : null
+    return json({ focused, currentFocus, counts, tree })
+  }
+
+  // GET /frame — current screen buffer as plain text. `?grep=pat` returns
+  // only matching lines. `?json=1` wraps in {frame, match, lines}.
+  if (path === "/frame") {
+    const r = bridge.renderer() as {
+      currentRenderBuffer?: { getRealCharBytes(nl: boolean): Uint8Array }
+    } | null
+    if (!r?.currentRenderBuffer) return json({ error: "no render buffer" }, 503)
+    const frame = new TextDecoder().decode(r.currentRenderBuffer.getRealCharBytes(true))
+    const grep = url.searchParams.get("grep")
+    const body = grep ? frame.split("\n").filter(l => l.includes(grep)).join("\n") : frame
+    if (url.searchParams.get("json") === "1") {
+      return json({
+        frame: body,
+        match: grep ? frame.includes(grep) : undefined,
+        lines: frame.split("\n").length,
+      })
+    }
+    return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } })
+  }
+
+  // GET /logs?n=N — gateway stderr ring buffer (same source as /logs dialog)
+  if (path === "/logs") {
+    const n = Number(url.searchParams.get("n")) || 200
+    return new Response(bridge.logs(n), { headers: { "Content-Type": "text/plain; charset=utf-8" } })
+  }
+
+  // GET /perf — return all profiling data as JSON
+  if (path === "/perf") {
+    const d = perf.data()
+    if (!d) return json({ error: "PERF not enabled" }, 400)
+    return json(d)
+  }
+
+  // GET /tabs — cycle through all tabs with a delay
+  if (path === "/tabs") {
+    const ms = Number(url.searchParams.get("delay") || "500")
+    for (let i = 0; i <= TAB_MAX; i++) {
+      bridge.setTab(i)
+      await new Promise(r => setTimeout(r, ms))
+    }
+    bridge.setTab(CHAT_TAB)
+    return json({ cycled: TAB_MAX + 1, delay: ms })
+  }
+
+  // GET /mem — memory snapshot
+  if (path === "/mem") {
+    perf.mem("control:snapshot")
+    const m = process.memoryUsage()
+    return json({
+      rss: Math.round(m.rss / 1024 / 1024),
+      heap: Math.round(m.heapUsed / 1024 / 1024),
+      heapTotal: Math.round(m.heapTotal / 1024 / 1024),
+      external: Math.round(m.external / 1024 / 1024),
+    })
+  }
+
+  return json({
+    error: "not found",
+    routes: [
+      "GET  /status",
+      "GET  /tab/:n",
+      "POST /send   {message}",
+      "POST /key    {name, ctrl?, shift?, meta?, raw?, safe?}",
+      "POST /keys   {keys: [{name, ...}], delay?, safe?}",
+      "POST /type   {text, delay?, safe?}",
+      "POST /input  {text}",
+      "GET  /quit",
+      "GET  /frame  ?grep=pat&json=1",
+      "GET  /logs   ?n=200",
+      "GET  /focus",
+      "GET  /perf",
+      "GET  /tabs",
+      "GET  /mem",
+    ],
+  }, 404)
+}
+
+export function start() {
+  if (!enabled) return
+  Bun.serve({ port: PORT, fetch: handle })
+  process.stderr.write(`\x1b[90m[control] http://localhost:${PORT}\x1b[0m\n`)
+}

package/src/utils/drop.ts

@@ -0,0 +1,25 @@
+// Cheap client-side sniff for "this paste is probably a local file path".
+// Mirrors the starts_like_path gate in hermes cli._detect_file_drop — the
+// gateway's input.detect_drop RPC is the authority (it stats the file and
+// handles quoting/escapes/file://); this only decides whether to bother
+// asking. Kept deliberately narrow so prose that happens to start with `/`
+// (e.g. a pasted regex) still falls through to verbatim insert on miss.
+
+/** Windows drive prefix (`C:\` or `C:/`), optionally behind a quote. */
+const winDrive = (s: string, off = 0) =>
+  s.length >= off + 3 && /[A-Za-z]/.test(s[off]!) && s[off + 1] === ":" && (s[off + 2] === "\\" || s[off + 2] === "/")
+
+export function looksLikePath(s: string): boolean {
+  const t = s.trim()
+  if (!t || t.includes("\n")) return false
+  if (t.startsWith("file://")) return true
+  if (t.startsWith("/") || t.startsWith("~") || t.startsWith("./") || t.startsWith("../")) return true
+  if (winDrive(t)) return true
+  const q = t[0]
+  if (q === '"' || q === "'") {
+    const inner = t[1]
+    if (inner === "/" || inner === "~") return true
+    if (winDrive(t, 1)) return true
+  }
+  return false
+}

package/src/utils/editor.ts

@@ -0,0 +1,33 @@
+// Suspend the renderer, open $VISUAL/$EDITOR on a tmpfile seeded with the
+// current input, read it back. Returns undefined if no editor configured
+// or the user emptied the file.
+
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { rm } from "node:fs/promises"
+import type { CliRenderer } from "@opentui/core"
+
+export async function editInEditor(renderer: CliRenderer, seed: string): Promise<string | undefined> {
+  const cmd = process.env.VISUAL || process.env.EDITOR
+  if (!cmd) return undefined
+
+  const path = join(tmpdir(), `herm-${Date.now()}.md`)
+  await Bun.write(path, seed)
+
+  renderer.suspend()
+  renderer.currentRenderBuffer.clear()
+  try {
+    const parts = cmd.split(" ")
+    const proc = Bun.spawn([...parts, path], {
+      stdin: "inherit", stdout: "inherit", stderr: "inherit",
+    })
+    await proc.exited
+    const text = await Bun.file(path).text().catch(() => "")
+    return text.trim() || undefined
+  } finally {
+    rm(path, { force: true }).catch(() => {})
+    renderer.currentRenderBuffer.clear()
+    renderer.resume()
+    renderer.requestRender()
+  }
+}

package/src/utils/fuzzy.ts

@@ -0,0 +1,45 @@
+/**
+ * Fuzzy subsequence scorer.
+ *
+ * Returns a positive number when `needle` is a (case-insensitive) subsequence
+ * of `hay`, weighted so that tighter / earlier / boundary-aligned matches rank
+ * higher. Returns 0 when the needle cannot be found as a subsequence.
+ *
+ * Bonuses:
+ *  - start of string
+ *  - consecutive characters
+ *  - word boundaries: after `_ - / . space` or a lower→Upper camel hump
+ *  - exact prefix (guarantees prefix matches outrank scattered ones)
+ */
+
+const SEP = new Set(["-", "_", "/", " ", "."])
+
+function boundary(hay: string, i: number) {
+  if (i === 0) return true
+  const prev = hay[i - 1]
+  if (SEP.has(prev)) return true
+  if (prev === prev.toLowerCase() && hay[i] !== hay[i].toLowerCase()) return true
+  return false
+}
+
+export function score(needle: string, hay: string): number {
+  if (!needle) return 0
+  const n = needle.toLowerCase()
+  const h = hay.toLowerCase()
+  let pts = 0
+  let from = 0
+  let prev = -2
+  for (let i = 0; i < n.length; i++) {
+    const at = h.indexOf(n[i], from)
+    if (at < 0) return 0
+    pts += 1
+    if (at === 0) pts += 8
+    if (at === prev + 1) pts += 5
+    if (at !== prev + 1 && boundary(hay, at)) pts += 4
+    pts -= (at - (prev < 0 ? 0 : prev + 1)) * 0.1
+    prev = at
+    from = at + 1
+  }
+  if (h.startsWith(n)) pts += 100
+  return pts - hay.length * 0.01
+}