spexcode 0.1.5 → 0.2.0

package/spec-cli/src/boardDelta.ts

@@ -0,0 +1,90 @@
+import { createHash } from 'node:crypto'
+
+// @@@ board-delta — the pure core of the board's incremental push: decompose a board snapshot into a keyed
+// UNIT MAP, tag it, and diff two unit maps into a minimal {set, del} patch. The transport ([[board-stream]])
+// chains these patches over SSE (`from`/`to` tags) so a subscribed dashboard applies a few KB per change
+// instead of refetching the full ~600KB snapshot; the client-side mirror of apply/reconstruct lives in the
+// dashboard's data layer. Everything here is pure and synchronous — no fs, no git, no stream — so the
+// equivalence argument (see the spec node's equivalence.md) is checkable by the property tests alone.
+//
+// Unit keys: `node:<id>` (one spec node), `sess:<id>` (one session row), `nodes#order` / `sess#order`
+// (id sequences, preserving array order), `meta` (every other top-level field as one small object).
+// Precondition P: node ids and session ids are collision-free. unitize REPORTS P (`ok`) rather than
+// assuming it — on a violation the transport falls back to full-snapshot sends, so a delta is only ever
+// chained between snapshots where the decomposition is a real bijection.
+
+export type Units = Map<string, { j: string; v: unknown }>
+export type Delta = { from: string; to: string; set: Record<string, unknown>; del: string[] }
+
+type Boardish = { nodes?: unknown; sessions?: unknown; [k: string]: unknown }
+
+// decompose a board into units. `ok` = the bijection precondition held (arrays are arrays, ids unique &
+// non-empty); when false the map is still returned (usable for tagging) but must not seed a delta chain.
+export function unitize(board: Boardish): { units: Units; ok: boolean } {
+  const units: Units = new Map()
+  let ok = true
+  const keyed = (arr: unknown, prefix: string, orderKey: string): void => {
+    const list = Array.isArray(arr) ? arr : (ok = false, [])
+    const order: string[] = []
+    for (const item of list) {
+      const id = (item as { id?: unknown })?.id
+      if (typeof id !== 'string' || !id || units.has(`${prefix}${id}`)) { ok = false; continue }
+      units.set(`${prefix}${id}`, { j: JSON.stringify(item), v: item })
+      order.push(id)
+    }
+    units.set(orderKey, { j: JSON.stringify(order), v: order })
+  }
+  const { nodes, sessions, ...meta } = board
+  keyed(nodes, 'node:', 'nodes#order')
+  keyed(sessions, 'sess:', 'sess#order')
+  units.set('meta', { j: JSON.stringify(meta), v: meta })
+  return { units, ok }
+}
+
+// the snapshot tag: a digest over every unit's key + content hash, order-independent (keys sorted). Two
+// builds serializing equal content get equal tags; JSON.stringify equality is conservative (equal strings ⇒
+// equal values; a key-order difference at worst re-sends an unchanged unit, never misses a changed one).
+export function tagOf(units: Units): string {
+  const h = createHash('sha1')
+  for (const key of [...units.keys()].sort()) {
+    const u = units.get(key)!
+    h.update(key).update('\0').update(u.j).update('\0')
+  }
+  return h.digest('hex')
+}
+
+// diff two unit maps into the minimal patch: units whose serialized content moved land in `set` (with the
+// NEW value), units that vanished land in `del`. apply(prev, diff(prev, next)) = next — the round-trip
+// lemma the property tests pin down.
+export function diffUnits(prev: Units, next: Units): { set: Record<string, unknown>; del: string[] } {
+  const set: Record<string, unknown> = {}
+  const del: string[] = []
+  for (const [key, u] of next) {
+    const p = prev.get(key)
+    if (!p || p.j !== u.j) set[key] = u.v
+  }
+  for (const key of prev.keys()) if (!next.has(key)) del.push(key)
+  return { set, del }
+}
+
+// apply a patch to a unit-value map — the exact algorithm the dashboard mirrors in data.js, kept here so
+// the round-trip property is provable against the real shape, not a paraphrase of it.
+export function applyDelta(values: Map<string, unknown>, d: Pick<Delta, 'set' | 'del'>): Map<string, unknown> {
+  const out = new Map(values)
+  for (const key of d.del) out.delete(key)
+  for (const [key, v] of Object.entries(d.set)) out.set(key, v)
+  return out
+}
+
+// reconstruct the board from unit values — R(U(B)) = B on the P-satisfying subspace (the client's render
+// input after every applied patch). Order rides the #order units, so array order survives the round trip.
+export function boardFromUnits(values: Map<string, unknown>): Boardish {
+  const pick = (prefix: string, orderKey: string): unknown[] => {
+    const order = (values.get(orderKey) as string[] | undefined) || []
+    return order.map((id) => values.get(`${prefix}${id}`))
+  }
+  const meta = (values.get('meta') as Record<string, unknown> | undefined) || {}
+  return { ...meta, nodes: pick('node:', 'nodes#order'), sessions: pick('sess:', 'sess#order') }
+}
+
+export const unitValues = (units: Units): Map<string, unknown> => new Map([...units].map(([k, u]) => [k, u.v]))

package/spec-cli/src/boardStream.ts

@@ -0,0 +1,178 @@
+import { streamSSE } from 'hono/streaming'
+import type { Context } from 'hono'
+import { watch, mkdirSync, type FSWatcher } from 'node:fs'
+import { join } from 'node:path'
+import { sessionsRoot, gitCommonDir } from './layout.js'
+import { sessionSignature } from './sessions.js'
+import { getBoard, invalidateBoard } from './boardCache.js'
+import { unitize, tagOf, diffUnits, type Units } from './boardDelta.js'
+
+// @@@ board-stream — the board's freshness is PUSHED, not polled. A dashboard subscribes here ONCE; in
+// plain mode it gets a bare `board-changed` and refetches /api/board (the legacy protocol, kept verbatim
+// for old clients); in DELTA mode (`?mode=delta`) the server itself rebuilds on change and streams the
+// hash-chained patch ([[board-delta]]): a `board-full {to, board}` on connect, then `board-delta
+// {from, to, set, del}` per change — a few KB against the ~600KB snapshot, with a full-snapshot send
+// whenever the patch wouldn't win (bigger than the board, or the unit decomposition's id-uniqueness
+// precondition failed), so a delta subscriber is NEVER worse off than a full refetch.
+//
+// Event sources, ALL funneled into one debounced pipeline: (1) fs.watch on the per-user session store —
+// every lifecycle transition lands as a sessions/<id>/session.json write; (2) fs.watch on the shared git
+// dir's refs (+ packed-refs/HEAD) — a commit or merge moves a ref, so tree reshapes push instead of
+// waiting out a poll; (3) a subscriber-gated ~2s poll of the CHEAP tmux session signature ([[sessions]])
+// for liveness/activity, which never touch a file; (4) a delta-gated ~15s cold tick that rebuilds and
+// diffs server-side, catching what no watcher sees (uncommitted worktree spec edits, forge issues) — ONE
+// rebuild per tick total, replacing every open dashboard's own 15s full refetch. Plain mode without delta
+// subscribers keeps its zero-build behavior: sources just fan out `board-changed`.
+
+type Notify = () => void
+type Frame = { event: string; data: string }
+type DeltaSend = (frame: Frame) => void
+const plainSubs = new Set<Notify>()
+const deltaSubs = new Set<DeltaSend>()
+let debounce: ReturnType<typeof setTimeout> | null = null
+
+// ---- the rebuild→diff→broadcast pipeline (runs only while delta subscribers exist) ----
+// last successfully-broadcast snapshot: the delta chain's anchor. `lastFullFrame` is what a fresh
+// subscriber gets instantly; `lastUnits`+`lastTag` are what the next diff chains from. A snapshot that
+// failed the unitize precondition anchors nothing (lastUnits=null) so every following send is a full.
+let lastUnits: Units | null = null
+let lastTag = ''
+let lastFullFrame: Frame | null = null
+let building = false
+let dirty = false
+
+async function rebuildAndBroadcast(): Promise<void> {
+  if (building) { dirty = true; return }
+  building = true
+  try {
+    do {
+      dirty = false
+      let board: unknown
+      // share the route's single-flight build ([[board-cache]]); fireChanged() already invalidated the
+      // cache, so this gets a fresh build (or joins one a concurrent poll already started).
+      try { board = await getBoard() } catch { for (const n of [...plainSubs]) { try { n() } catch { /* swept on abort */ } }; continue }
+      const boardJson = JSON.stringify(board)
+      const { units, ok } = unitize(board as Record<string, unknown>)
+      const tag = tagOf(units)
+      if (tag === lastTag) continue
+      const fullFrame: Frame = { event: 'board-full', data: `{"to":"${tag}","board":${boardJson}}` }
+      let frame = fullFrame
+      if (lastUnits && ok) {
+        const { set, del } = diffUnits(lastUnits, units)
+        const deltaData = JSON.stringify({ from: lastTag, to: tag, set, del })
+        // guaranteed win: ship the patch only when it actually beats the snapshot
+        if (deltaData.length < fullFrame.data.length) frame = { event: 'board-delta', data: deltaData }
+      }
+      lastUnits = ok ? units : null
+      lastTag = tag
+      lastFullFrame = fullFrame
+      for (const send of [...deltaSubs]) { try { send(frame) } catch { /* swept on abort */ } }
+      for (const n of [...plainSubs]) { try { n() } catch { /* swept on abort */ } }
+    } while (dirty)
+  } finally { building = false }
+}
+
+// a merge/launch/close touches several record files at once; collapse the burst into ONE signal. With
+// delta subscribers the debounced fire rebuilds and broadcasts (plain subs then ride the same tag-moved
+// gate — no spurious refetches); without them it stays the zero-build legacy notify.
+function fireChanged(): void {
+  // invalidate the route's board cache ([[board-cache]]) on EVERY change signal, before the debounce guard
+  // — a plain-mode client that polls /api/board (no delta rebuild here) must still see fresh data on its
+  // next poll, and a delta rebuild below re-reads the same now-stale cache.
+  invalidateBoard()
+  if (debounce) return
+  debounce = setTimeout(() => {
+    debounce = null
+    if (deltaSubs.size) void rebuildAndBroadcast()
+    else for (const notify of [...plainSubs]) { try { notify() } catch { /* swept on abort */ } }
+  }, 150)
+}
+
+// ---- event source 0: an EXPLICIT server-side nudge ----
+// for the one mutation the watchers structurally cannot see: /rename writes the worktree's `.session`
+// (the name's ONE home, outside the watched store — [[session-rename]]). The route calls this instead of
+// double-writing the name into the store: a notification problem gets a notification solution, never a
+// second data home. Same debounced funnel as every other source.
+export const notifyBoardChanged = (): void => fireChanged()
+
+// ---- event source 1: the session store (lifecycle status writes) ----
+let watcher: FSWatcher | null = null
+function ensureWatcher(): void {
+  if (watcher) return
+  const root = sessionsRoot()
+  try { mkdirSync(root, { recursive: true }) } catch { /* best-effort; the watch below still tries */ }
+  try { watcher = watch(root, { recursive: true }, () => fireChanged()) } catch { watcher = null }
+}
+
+// ---- event source 2: git refs (a commit/merge reshapes the tree the moment the ref moves) ----
+// refs/ recursively for loose refs (heads, worktree branches), plus the common dir itself non-recursively
+// for packed-refs rewrites and HEAD flips. Best-effort like every source: no watch → the cold tick covers.
+let refsWatchers: FSWatcher[] | null = null
+function ensureRefsWatcher(): void {
+  if (refsWatchers) return
+  refsWatchers = []
+  try {
+    const common = gitCommonDir()
+    try { refsWatchers.push(watch(join(common, 'refs'), { recursive: true }, () => fireChanged())) } catch { /* loose refs unwatched */ }
+    try { refsWatchers.push(watch(common, (_e, f) => { if (f === 'packed-refs' || f === 'HEAD') fireChanged() })) } catch { /* packed refs unwatched */ }
+  } catch { /* not a repo? the cold tick still covers */ }
+}
+
+// ---- event source 3: the tmux-derived signature (liveness + activity — never a file write) ----
+let poller: ReturnType<typeof setInterval> | null = null
+let lastSig = ''
+function ensureLivePoll(): void {
+  if (poller) return
+  poller = setInterval(() => {
+    void sessionSignature().then((sig) => { if (sig !== lastSig) { lastSig = sig; fireChanged() } }).catch(() => {})
+  }, 2000)
+}
+
+// ---- event source 4: the cold tick — the server-side replacement for every client's slow fallback poll.
+// Rebuild+diff on a relaxed timer so what NO watcher sees (an uncommitted worktree spec edit, a forge
+// issue refresh) still lands; an unchanged tag broadcasts nothing. Delta-gated: plain-only clients keep
+// their own client-side fallback, so without delta subscribers this must not burn builds.
+let coldTick: ReturnType<typeof setInterval> | null = null
+function ensureColdTick(): void {
+  if (coldTick) return
+  coldTick = setInterval(() => { if (deltaSubs.size) void rebuildAndBroadcast() }, 15000)
+}
+
+function stopSourcesIfIdle(): void {
+  if (plainSubs.size + deltaSubs.size > 0) return
+  if (poller) { clearInterval(poller); poller = null; lastSig = '' }
+  if (coldTick) { clearInterval(coldTick); coldTick = null }
+}
+
+// GET /api/board/stream — one SSE per dashboard tab, server→client only, with a periodic `ping` so an
+// idle proxy never times the connection out. On a backend hot-reload the stream drops and EventSource
+// auto-reconnects to the fresh child; a delta subscriber's reconnect lands a fresh `board-full`, so the
+// chain re-anchors with no client-side repair logic.
+export function boardStream(c: Context) {
+  const delta = c.req.query('mode') === 'delta'
+  ensureWatcher()
+  ensureRefsWatcher()
+  return streamSSE(c, async (stream) => {
+    let aborted = false
+    const send: DeltaSend = (frame) => { void stream.writeSSE(frame).catch(() => {}) }
+    const notify: Notify = () => { void stream.writeSSE({ event: 'board-changed', data: 'x' }).catch(() => {}) }
+    if (delta) { deltaSubs.add(send); ensureColdTick() } else { plainSubs.add(notify) }
+    ensureLivePoll()
+    const unsub = (): void => { deltaSubs.delete(send); plainSubs.delete(notify); stopSourcesIfIdle() }
+    stream.onAbort(() => { aborted = true; unsub() })
+    try {
+      await stream.writeSSE({ event: 'ready', data: 'x' })
+      if (delta) {
+        // seed the chain: the cached anchor snapshot immediately (same tag the next delta chains from),
+        // then a fire so a connect during a quiet stretch converges to truly-current within one build.
+        if (lastFullFrame) { await stream.writeSSE(lastFullFrame).catch(() => {}) ; fireChanged() }
+        else void rebuildAndBroadcast()
+      }
+      while (!aborted) {
+        await stream.sleep(25000)
+        if (aborted) break
+        await stream.writeSSE({ event: 'ping', data: 'x' })
+      }
+    } finally { unsub() }
+  })
+}