herm-tui 1.0.0-dev.1

package/src/commands/slash.ts

@@ -0,0 +1,151 @@
+/**
+ * Slash command definitions for the chat input.
+ *
+ * Commands are fetched dynamically from Hermes `GET /api/commands` — the
+ * unified registry of built-ins + skills + plugins + MCP prompts. There is
+ * no static fallback: if the gateway is unreachable, no slash commands are
+ * available (the popover simply won't open).
+ *
+ * `target` is derived: "local" if the name is a client-handled command,
+ * otherwise "gateway" (forwarded as /{name} to the Hermes API).
+ */
+
+export type SlashSource = "command" | "skill" | "plugin" | "mcp" | "local"
+
+export type SlashCommand = {
+  readonly name: string
+  readonly description: string
+  readonly category: string
+  readonly aliases: ReadonlyArray<string>
+  readonly argsHint: string
+  readonly subcommands: ReadonlyArray<string>
+  readonly source: SlashSource
+  readonly target: "local" | "gateway"
+  readonly keybind?: string
+}
+
+/**
+ * Names of purely client-side commands — intercepted before gateway dispatch.
+ * These are always treated as local regardless of what the gateway returns.
+ * Anything that must act on the *live* gateway session (not the slash-worker
+ * subprocess) belongs here — see docs/slash-parity-audit.md.
+ */
+export const LOCAL_NAMES = new Set([
+  "clear", "new", "theme", "help", "keys", "logs", "eikon", "title",
+  "rollback", "save", "history", "status", "usage", "profile", "steer",
+  "reload", "reload-mcp", "chafa", "splash",
+  // parity: session-mutating commands the slash-worker can't service
+  "resume", "branch", "compress", "undo", "retry", "model", "quit",
+  "copy", "paste", "image", "background", "voice", "mouse", "redraw", "queue",
+  // Ink-only UI toggles — local no-op with a note
+  "compact", "setup",
+])
+
+/**
+ * Descriptions for locally-handled commands. Used to render them in the
+ * popover when the gateway registry doesn't include them (or to override
+ * the gateway's description for things like /new, which we intercept).
+ */
+export const LOCAL_COMMANDS: ReadonlyArray<SlashCommand> = [
+  { name: "clear", description: "Clear chat messages",       category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "new",   description: "Start a new session",        category: "Client", aliases: ["reset"], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "theme", description: "Switch color theme",         category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "help",  description: "Show keyboard shortcuts",    category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "keys",  description: "Rebind keyboard shortcuts",  category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "logs",  description: "Show gateway stderr log",    category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "eikon", description: "Pick sidebar avatar",        category: "Client", aliases: [],       argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "title", description: "Set session title",          category: "Client", aliases: [],       argsHint: "[text]", subcommands: [], source: "local", target: "local" },
+  { name: "rollback", description: "Browse & restore checkpoints", category: "Client", aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "history",  description: "Server-side transcript viewer", category: "Info",   aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "status",  description: "Version, model, paths",       category: "Info",   aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "usage",   description: "Tokens, context fill, cost",   category: "Info",   aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "profile", description: "Active profile details",       category: "Info",   aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "steer",   description: "Inject a note mid-turn (no interrupt)", category: "Session", aliases: [], argsHint: "[text]", subcommands: [], source: "local", target: "local" },
+  { name: "reload-mcp", description: "Restart MCP servers & rediscover tools", category: "Session", aliases: [], argsHint: "[now|always]", subcommands: ["now", "always"], source: "local", target: "local" },
+  { name: "reload", description: "Hot-reload ~/.hermes/.env (API keys)", category: "Session", aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+  { name: "chafa",  description: "Render image via chafa (demo)",       category: "Client",  aliases: [], argsHint: "<path>", subcommands: [], source: "local", target: "local" },
+  { name: "splash", description: "Show the launch splash",              category: "Client",  aliases: [], argsHint: "", subcommands: [], source: "local", target: "local" },
+]
+
+/** Filter commands by prefix (text after `/`). Searches names + aliases. */
+export function filter(list: ReadonlyArray<SlashCommand>, prefix: string): SlashCommand[] {
+  if (!prefix) return [...list]
+  const q = prefix.toLowerCase()
+  return list.filter(c =>
+    c.name.toLowerCase().startsWith(q) ||
+    c.aliases.some(a => a.toLowerCase().startsWith(q))
+  )
+}
+
+type Resolved =
+  | { hit: SlashCommand }
+  | { miss: true }
+  | { ambiguous: string[] }
+
+/**
+ * Resolve a typed command name to a single SlashCommand. Exact name or
+ * alias wins even when it's also a prefix of something longer (`/status`
+ * vs `/statusbar`). Otherwise a unique prefix match across the names +
+ * aliases space resolves; multiple distinct targets is ambiguous.
+ */
+export function resolve(list: ReadonlyArray<SlashCommand>, name: string): Resolved {
+  const q = name.toLowerCase()
+  for (const c of list)
+    if (c.name.toLowerCase() === q || c.aliases.some(a => a.toLowerCase() === q))
+      return { hit: c }
+  const hits = new Set<SlashCommand>()
+  for (const c of list)
+    for (const n of [c.name, ...c.aliases])
+      if (n.toLowerCase().startsWith(q)) { hits.add(c); break }
+  if (hits.size === 1) return { hit: [...hits][0] }
+  if (hits.size === 0) return { miss: true }
+  return { ambiguous: [...hits].map(c => `/${c.name}`).sort() }
+}
+
+/**
+ * If input matches `/cmd <sub>` (with space) and the command has declared
+ * subcommands, return synthetic entries for subcommand completion.
+ */
+export function matchSub(list: ReadonlyArray<SlashCommand>, input: string): SlashCommand[] | null {
+  const m = input.match(/^\/(\w+)\s+(\S*)$/)
+  if (!m) return null
+  const name = m[1]
+  const sub = m[2]
+  const cmd = list.find(c => c.name === name || c.aliases.includes(name))
+  if (!cmd || cmd.subcommands.length === 0) return null
+  const q = sub.toLowerCase()
+  const matches = cmd.subcommands.filter(s => s.toLowerCase().startsWith(q))
+  if (matches.length === 0) return null
+  return matches.map(s => ({
+    ...cmd,
+    name: `${cmd.name} ${s}`,
+    description: `${cmd.name} → ${s}`,
+    argsHint: "",
+    subcommands: [],
+  }))
+}
+
+/** Category ordering for display. Unknown categories fall to the end. */
+const CATEGORY_ORDER = [
+  "Client",
+  "Session",
+  "Configuration",
+  "Config",
+  "Tools & Skills",
+  "Skills",
+  "Plugins",
+  "MCP",
+  "Info",
+  "Exit",
+] as const
+
+export function sort(list: ReadonlyArray<SlashCommand>): SlashCommand[] {
+  const idx = (c: string) => {
+    const i = (CATEGORY_ORDER as readonly string[]).indexOf(c)
+    return i < 0 ? 999 : i
+  }
+  return [...list].sort((a, b) => {
+    const ca = idx(a.category) - idx(b.category)
+    return ca !== 0 ? ca : a.name.localeCompare(b.name)
+  })
+}

package/src/components/avatar/AnimatedAvatar.tsx

@@ -0,0 +1,66 @@
+import { useState, useEffect, useRef, memo } from "react"
+import { STATE_FRAMES, FPS, type AvatarState } from "./states"
+import type { ParsedEikon } from "./eikon"
+import { useTheme } from "../../theme"
+import * as perf from "../../utils/perf"
+
+/**
+ * Animation loop:
+ *   1. Pause on frame 0 for PAUSE_FIRST ms
+ *   2. Play forward (0 → last) at FPS
+ *   3. Pause on last frame for PAUSE_LAST ms
+ *   4. Play reverse (last → 0) at FPS
+ *   5. Goto 1
+ *
+ * Restarts from frame 0 whenever `state` changes.
+ *
+ * When an `eikon` is supplied and it defines the current state, its
+ * frames and fps take precedence over the baked-in set; states missing
+ * from the eikon fall back to the baked-in frames.
+ */
+
+export const AnimatedAvatar = memo(({ state = "idle", eikon }: { state?: AvatarState; eikon?: ParsedEikon }) => {
+  const theme = useTheme().theme
+  const [frame, setFrame] = useState(0)
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const ext = eikon?.states.get(state)
+  const frames: string[][] = ext ? ext.frames : STATE_FRAMES[state]
+  const fps = ext?.fps ?? FPS
+  const count = frames.length
+
+  // Restart animation loop when state or source changes
+  useEffect(() => {
+    let idx = 0
+    let dir = 1
+
+    const tick = () => {
+      perf.count("avatar:tick")
+      idx += dir
+      if (idx >= count - 1) dir = -1
+      if (idx <= 0) dir = 1
+      setFrame(idx)
+      timer.current = setTimeout(tick, 1000 / fps)
+    }
+
+    setFrame(0)
+    timer.current = setTimeout(tick, 1000 / fps)
+    return () => { if (timer.current) clearTimeout(timer.current) }
+  }, [state, count, fps])
+
+  const end = perf.mark("avatar:render")
+  const idx = Math.min(frame, count - 1)
+  const lines = frames[idx] ?? []
+
+  const result = (
+    <box flexDirection="column">
+      {lines.map((line, i) => (
+        <text key={i}>
+          <span fg={theme.hermAvatar}>{line}</span>
+        </text>
+      ))}
+    </box>
+  )
+  end()
+  return result
+})

package/src/components/avatar/eikon.ts

@@ -0,0 +1,144 @@
+/**
+ * .eikon file parser — NDJSON stateful ASCII animation format.
+ *
+ * Line 1 is a header object. Subsequent lines are either state
+ * declarations (`{state, fps, frame_count, ...}`) or frame objects
+ * (`{f, data, ...}`) belonging to the most recent state. Unknown
+ * fields are ignored; unknown format versions are tolerated.
+ *
+ * Spec: https://github.com/liftaris/eikon (separate repo).
+ */
+
+import { readdirSync, openSync, readSync, closeSync } from "fs"
+import { join } from "path"
+
+export type EikonMeta = {
+  version: number
+  name: string
+  author?: string
+  width: number
+  height: number
+  states: string[]
+  [k: string]: unknown
+}
+
+export type EikonState = {
+  fps: number
+  /** Each frame as an array of lines (row-per-string). */
+  frames: string[][]
+}
+
+export type ParsedEikon = {
+  meta: EikonMeta
+  states: Map<string, EikonState>
+}
+
+type Row = Record<string, unknown>
+
+const num = (v: unknown, d: number) => typeof v === "number" && isFinite(v) ? v : d
+const str = (v: unknown, d = "") => typeof v === "string" ? v : d
+
+function parse(line: string, n: number): Row {
+  try { return JSON.parse(line) as Row }
+  catch (e) {
+    const msg = e instanceof Error ? e.message : String(e)
+    throw new Error(`eikon: malformed JSON on line ${n}: ${msg}`)
+  }
+}
+
+function median(xs: number[]): number {
+  const s = [...xs].sort((a, b) => a - b)
+  const m = s.length >> 1
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
+}
+
+/** Parse a full .eikon NDJSON document. Throws with line number on bad JSON. */
+export function parseEikon(text: string): ParsedEikon {
+  const lines = text.split("\n")
+  if (!lines[0]?.trim()) throw new Error("eikon: empty file (no header on line 1)")
+
+  const head = parse(lines[0], 1)
+  const meta: EikonMeta = {
+    ...head,
+    version: num(head.eikon ?? head.version, 1),
+    name: str(head.name, "unnamed"),
+    author: typeof head.author === "string" ? head.author : undefined,
+    width: num(head.width, 0),
+    height: num(head.height, 0),
+    states: Array.isArray(head.states) ? (head.states as string[]) : [],
+  }
+
+  const states = new Map<string, EikonState>()
+  let cur: { name: string; fps?: number; frames: string[][]; durs: number[] } | null = null
+
+  const seal = () => {
+    if (!cur) return
+    const fps = cur.fps ?? (cur.durs.length ? Math.round(1000 / median(cur.durs)) || 12 : 12)
+    states.set(cur.name, { fps, frames: cur.frames })
+    cur = null
+  }
+
+  for (let i = 1; i < lines.length; i++) {
+    const raw = lines[i]
+    if (!raw || !raw.trim()) continue
+    const obj = parse(raw, i + 1)
+
+    if (typeof obj.state === "string") {
+      seal()
+      cur = {
+        name: obj.state,
+        fps: typeof obj.fps === "number" ? obj.fps : undefined,
+        frames: [],
+        durs: [],
+      }
+      continue
+    }
+
+    // Frame line — attach to current state.
+    if (!cur) continue
+    const data = typeof obj.data === "string"
+      ? obj.data.split("\n")
+      : Array.isArray(obj.lines) ? (obj.lines as string[]) : []
+    cur.frames.push(data)
+    const ms = num(obj.duration_ms, 0) || num(obj.pause, 0) * 1000
+    if (ms > 0) cur.durs.push(ms)
+  }
+  seal()
+
+  if (meta.states.length === 0) meta.states = Array.from(states.keys())
+  return { meta, states }
+}
+
+/** Read just the header (line 1) of a .eikon file without loading the rest. */
+function peek(path: string): EikonMeta | null {
+  const fd = openSync(path, "r")
+  try {
+    const buf = Buffer.alloc(8192)
+    const n = readSync(fd, buf, 0, buf.length, 0)
+    const first = buf.toString("utf8", 0, n).split("\n", 1)[0]
+    if (!first) return null
+    return parseEikon(first).meta
+  } catch {
+    return null
+  } finally {
+    closeSync(fd)
+  }
+}
+
+/**
+ * Scan directories (non-recursive per dir, but walks one level deep) for
+ * `*.eikon` files and return their header metadata. Missing dirs are
+ * silently skipped.
+ */
+export function listEikons(dirs: string[]): { path: string; meta: EikonMeta }[] {
+  return dirs.flatMap(dir => {
+    let entries: string[]
+    try { entries = readdirSync(dir, { recursive: true }) as string[] }
+    catch { return [] }
+    return entries
+      .filter(e => e.endsWith(".eikon"))
+      .map(e => join(dir, e))
+      .map(path => ({ path, meta: peek(path) }))
+      .filter((x): x is { path: string; meta: EikonMeta } => x.meta !== null)
+  })
+}