@rsktash/beads-ui 0.1.0

package/server/logging.js

@@ -0,0 +1,23 @@
+/**
+ * Debug logger helper for Node server/CLI.
+ */
+import createDebug from 'debug';
+
+/**
+ * Create a namespaced logger for Node runtime.
+ *
+ * @param {string} ns - Module namespace suffix (e.g., 'ws', 'watcher').
+ */
+export function debug(ns) {
+  return createDebug(`beads-ui:${ns}`);
+}
+
+/**
+ * Enable all `beads-ui:*` debug logs at runtime for Node/CLI.
+ * Safe to call multiple times.
+ */
+export function enableAllDebug() {
+  // `debug` exposes a global enable/disable API.
+  // Enabling after loggers are created updates their `.enabled` state.
+  createDebug.enable(process.env.DEBUG || 'beads-ui:*');
+}

package/server/registry-watcher.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { debug } from './logging.js';
+
+const log = debug('registry-watcher');
+
+/**
+ * In-memory registry of workspaces registered dynamically via the API.
+ * These supplement the file-based registry at ~/.beads/registry.json.
+ *
+ * @type {Map<string, { path: string, database: string, pid: number, version: string }>}
+ */
+const inMemoryWorkspaces = new Map();
+
+/**
+ * Register a workspace dynamically (in-memory).
+ * This allows `bdui start` to register workspaces when the server is already running.
+ *
+ * @param {{ path: string, database: string }} workspace
+ */
+export function registerWorkspace(workspace) {
+  const normalized = path.resolve(workspace.path);
+  log('registering workspace: %s (db: %s)', normalized, workspace.database);
+  inMemoryWorkspaces.set(normalized, {
+    path: normalized,
+    database: workspace.database,
+    pid: process.pid,
+    version: 'dynamic'
+  });
+}
+
+/**
+ * Get all dynamically registered workspaces (in-memory only).
+ *
+ * @returns {Array<{ path: string, database: string, pid: number, version: string }>}
+ */
+export function getInMemoryWorkspaces() {
+  return Array.from(inMemoryWorkspaces.values());
+}
+
+/**
+ * @typedef {Object} RegistryEntry
+ * @property {string} workspace_path
+ * @property {string} socket_path
+ * @property {string} database_path
+ * @property {number} pid
+ * @property {string} version
+ * @property {string} started_at
+ */
+
+/**
+ * Get the path to the global beads registry file.
+ *
+ * @returns {string}
+ */
+export function getRegistryPath() {
+  return path.join(os.homedir(), '.beads', 'registry.json');
+}
+
+/**
+ * Read and parse the registry file.
+ *
+ * @returns {RegistryEntry[]}
+ */
+export function readRegistry() {
+  const registry_path = getRegistryPath();
+  try {
+    const content = fs.readFileSync(registry_path, 'utf8');
+    const data = JSON.parse(content);
+    if (Array.isArray(data)) {
+      return data;
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Find the registry entry that matches the given root directory.
+ * Matches if the root_dir is the same as or a subdirectory of the workspace_path.
+ *
+ * @param {string} root_dir
+ * @returns {RegistryEntry | null}
+ */
+export function findWorkspaceEntry(root_dir) {
+  const entries = readRegistry();
+  const normalized = path.resolve(root_dir);
+
+  // First, try exact match
+  for (const entry of entries) {
+    if (path.resolve(entry.workspace_path) === normalized) {
+      return entry;
+    }
+  }
+
+  // Then try to find if root_dir is inside a workspace
+  for (const entry of entries) {
+    const workspace = path.resolve(entry.workspace_path);
+    if (normalized.startsWith(workspace + path.sep)) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all available workspaces from both the file-based registry and
+ * dynamically registered in-memory workspaces.
+ *
+ * @returns {Array<{ path: string, database: string, pid: number, version: string }>}
+ */
+export function getAvailableWorkspaces() {
+  const entries = readRegistry();
+  const fileWorkspaces = entries.map((entry) => ({
+    path: entry.workspace_path,
+    database: entry.database_path,
+    pid: entry.pid,
+    version: entry.version
+  }));
+
+  // Merge in-memory workspaces, avoiding duplicates by path
+  const seen = new Set(fileWorkspaces.map((w) => path.resolve(w.path)));
+  const inMemory = getInMemoryWorkspaces().filter(
+    (w) => !seen.has(path.resolve(w.path))
+  );
+
+  return [...fileWorkspaces, ...inMemory];
+}
+
+/**
+ * Watch the global beads registry file and invoke callback when it changes.
+ *
+ * @param {(entries: RegistryEntry[]) => void} onChange
+ * @param {{ debounce_ms?: number }} [options]
+ * @returns {{ close: () => void }}
+ */
+export function watchRegistry(onChange, options = {}) {
+  const debounce_ms = options.debounce_ms ?? 500;
+  const registry_path = getRegistryPath();
+  const registry_dir = path.dirname(registry_path);
+  const registry_file = path.basename(registry_path);
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {fs.FSWatcher | undefined} */
+  let watcher;
+
+  const schedule = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      try {
+        const entries = readRegistry();
+        onChange(entries);
+      } catch (err) {
+        log('error reading registry on change: %o', err);
+      }
+    }, debounce_ms);
+    timer.unref?.();
+  };
+
+  try {
+    // Ensure the directory exists before watching
+    if (!fs.existsSync(registry_dir)) {
+      log('registry directory does not exist: %s', registry_dir);
+      return { close: () => {} };
+    }
+
+    watcher = fs.watch(
+      registry_dir,
+      { persistent: true },
+      (event_type, filename) => {
+        if (filename && String(filename) !== registry_file) {
+          return;
+        }
+        if (event_type === 'change' || event_type === 'rename') {
+          log('registry %s %s', event_type, filename || '');
+          schedule();
+        }
+      }
+    );
+  } catch (err) {
+    log('unable to watch registry directory: %o', err);
+    return { close: () => {} };
+  }
+
+  return {
+    close() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+    }
+  };
+}

package/server/subscriptions.js

@@ -0,0 +1,299 @@
+/**
+ * @import { WebSocket } from 'ws'
+ */
+/**
+ * Server-side subscription registry for list-like data.
+ *
+ * Maintains per-subscription entries keyed by a stable string derived from
+ * `{ type, params }`. Each entry stores:
+ *  - `itemsById`: Map<string, { updated_at: number, closed_at: number|null }>
+ *  - `subscribers`: Set<WebSocket>
+ *  - `lock`: Promise chain to serialize refresh/update operations per key
+ *
+ * No TTL eviction; entries are swept when sockets disconnect (and only when
+ * that leaves the subscriber set empty).
+ */
+
+/**
+ * @typedef {{
+ *   type: string,
+ *   params?: Record<string, string | number | boolean>
+ * }} SubscriptionSpec
+ */
+
+/**
+ * @typedef {{ updated_at: number, closed_at: number | null }} ItemMeta
+ */
+
+/**
+ * @typedef {{
+ *   itemsById: Map<string, ItemMeta>,
+ *   subscribers: Set<WebSocket>,
+ *   lock: Promise<void>
+ * }} Entry
+ */
+
+/**
+ * Create a new, empty entry object.
+ *
+ * @returns {Entry}
+ */
+function createEntry() {
+  return {
+    itemsById: new Map(),
+    subscribers: new Set(),
+    lock: Promise.resolve()
+  };
+}
+
+/**
+ * Generate a stable subscription key string from a spec. Sorts params keys.
+ *
+ * @param {SubscriptionSpec} spec
+ * @returns {string}
+ */
+export function keyOf(spec) {
+  const type = String(spec.type || '').trim();
+  /** @type {Record<string, string>} */
+  const flat = {};
+  if (spec.params && typeof spec.params === 'object') {
+    const keys = Object.keys(spec.params).sort();
+    for (const k of keys) {
+      const v = spec.params[k];
+      flat[k] = String(v);
+    }
+  }
+  const enc = new URLSearchParams(flat).toString();
+  return enc.length > 0 ? `${type}?${enc}` : type;
+}
+
+/**
+ * Compute a delta between previous and next item maps.
+ *
+ * @param {Map<string, ItemMeta>} prev
+ * @param {Map<string, ItemMeta>} next
+ * @returns {{ added: string[], updated: string[], removed: string[] }}
+ */
+export function computeDelta(prev, next) {
+  /** @type {string[]} */
+  const added = [];
+  /** @type {string[]} */
+  const updated = [];
+  /** @type {string[]} */
+  const removed = [];
+
+  for (const [id, meta] of next) {
+    const p = prev.get(id);
+    if (!p) {
+      added.push(id);
+      continue;
+    }
+    if (p.updated_at !== meta.updated_at || p.closed_at !== meta.closed_at) {
+      updated.push(id);
+    }
+  }
+  for (const id of prev.keys()) {
+    if (!next.has(id)) {
+      removed.push(id);
+    }
+  }
+  return { added, updated, removed };
+}
+
+/**
+ * Normalize array of issue-like objects into an itemsById map.
+ *
+ * @param {Array<{ id: string, updated_at: number, closed_at?: number|null }>} items
+ * @returns {Map<string, ItemMeta>}
+ */
+export function toItemsMap(items) {
+  /** @type {Map<string, ItemMeta>} */
+  const map = new Map();
+  for (const it of items) {
+    if (!it || typeof it.id !== 'string') {
+      continue;
+    }
+    const updated_at = Number(it.updated_at) || 0;
+    /** @type {number|null} */
+    let closed_at = null;
+    if (it.closed_at === null || it.closed_at === undefined) {
+      closed_at = null;
+    } else {
+      const n = Number(it.closed_at);
+      closed_at = Number.isFinite(n) ? n : null;
+    }
+    map.set(it.id, { updated_at, closed_at });
+  }
+  return map;
+}
+
+/**
+ * Create a subscription registry with attach/detach and per-key locking.
+ */
+export class SubscriptionRegistry {
+  constructor() {
+    /** @type {Map<string, Entry>} */
+    this._entries = new Map();
+  }
+
+  /**
+   * Get an entry by key, or null if missing.
+   *
+   * @param {string} key
+   * @returns {Entry | null}
+   */
+  get(key) {
+    return this._entries.get(key) || null;
+  }
+
+  /**
+   * Ensure an entry exists for a spec; returns the key and entry.
+   *
+   * @param {SubscriptionSpec} spec
+   * @returns {{ key: string, entry: Entry }}
+   */
+  ensure(spec) {
+    const key = keyOf(spec);
+    let entry = this._entries.get(key);
+    if (!entry) {
+      entry = createEntry();
+      this._entries.set(key, entry);
+    }
+    return { key, entry };
+  }
+
+  /**
+   * Attach a subscriber to a spec. Creates the entry if missing.
+   *
+   * @param {SubscriptionSpec} spec
+   * @param {WebSocket} ws
+   * @returns {{ key: string, subscribed: true }}
+   */
+  attach(spec, ws) {
+    const { key, entry } = this.ensure(spec);
+    entry.subscribers.add(ws);
+    return { key, subscribed: true };
+  }
+
+  /**
+   * Detach a subscriber from the spec. Keeps entry even if empty; eviction
+   * is handled by `onDisconnect` sweep.
+   *
+   * @param {SubscriptionSpec} spec
+   * @param {WebSocket} ws
+   * @returns {boolean} true when the subscriber was removed
+   */
+  detach(spec, ws) {
+    const key = keyOf(spec);
+    const entry = this._entries.get(key);
+    if (!entry) {
+      return false;
+    }
+    return entry.subscribers.delete(ws);
+  }
+
+  /**
+   * On socket disconnect, remove it from all subscriber sets and evict any
+   * entries that become empty as a result of this sweep.
+   *
+   * @param {WebSocket} ws
+   */
+  onDisconnect(ws) {
+    /** @type {string[]} */
+    const empties = [];
+    for (const [key, entry] of this._entries) {
+      entry.subscribers.delete(ws);
+      if (entry.subscribers.size === 0) {
+        empties.push(key);
+      }
+    }
+    for (const key of empties) {
+      this._entries.delete(key);
+    }
+  }
+
+  /**
+   * Serialize a function against a key so only one runs at a time per key.
+   *
+   * @template T
+   * @param {string} key
+   * @param {() => Promise<T>} fn
+   * @returns {Promise<T>}
+   */
+  async withKeyLock(key, fn) {
+    let entry = this._entries.get(key);
+    if (!entry) {
+      entry = createEntry();
+      this._entries.set(key, entry);
+    }
+    // Chain onto the existing lock
+    const prev = entry.lock;
+    // Create our own release function and store it locally (not in shared state)
+    // to avoid race conditions when multiple operations queue concurrently
+    /** @type {(v?: void) => void} */
+    let release = () => {};
+    const our_lock = new Promise((resolve) => {
+      release = resolve;
+    });
+    // Update the entry's lock to our lock so the next operation waits on us
+    entry.lock = our_lock;
+    // Wait for previous operations to finish
+    await prev.catch(() => {});
+    try {
+      const result = await fn();
+      return result;
+    } finally {
+      // Release our lock for the next queued operation
+      // Use the locally-captured release function, not entry.lockTail
+      try {
+        release();
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * Replace items for a key and compute the delta, storing the new map.
+   *
+   * @param {string} key
+   * @param {Map<string, ItemMeta>} next_map
+   * @returns {{ added: string[], updated: string[], removed: string[] }}
+   */
+  applyNextMap(key, next_map) {
+    let entry = this._entries.get(key);
+    if (!entry) {
+      entry = createEntry();
+      this._entries.set(key, entry);
+    }
+    const prev = entry.itemsById;
+    const delta = computeDelta(prev, next_map);
+    entry.itemsById = new Map(next_map);
+    return delta;
+  }
+
+  /**
+   * Convenience: update items from an array of objects with id/updated_at/closed_at.
+   *
+   * @param {string} key
+   * @param {Array<{ id: string, updated_at: number, closed_at?: number|null }>} items
+   * @returns {{ added: string[], updated: string[], removed: string[] }}
+   */
+  applyItems(key, items) {
+    const next_map = toItemsMap(items);
+    return this.applyNextMap(key, next_map);
+  }
+
+  /**
+   * Clear all entries from the registry. Used when switching workspaces.
+   * Does not close WebSocket connections; they will re-subscribe on refresh.
+   */
+  clear() {
+    this._entries.clear();
+  }
+}
+
+/**
+ * Default singleton registry used by the ws server.
+ */
+export const registry = new SubscriptionRegistry();

package/server/subscriptions.test.js

@@ -0,0 +1,128 @@
+import { describe, expect, test, vi } from 'vitest';
+import {
+  SubscriptionRegistry,
+  computeDelta,
+  keyOf,
+  toItemsMap
+} from './subscriptions.js';
+
+describe('subscriptions registry', () => {
+  test('keyOf sorts params for stable keys', () => {
+    const a = keyOf({ type: 'list', params: { status: 'open', limit: 50 } });
+    const b = keyOf({ type: 'list', params: { limit: 50, status: 'open' } });
+    expect(a).toBe('list?limit=50&status=open');
+    expect(b).toBe('list?limit=50&status=open');
+  });
+
+  test('computeDelta returns added/updated/removed', () => {
+    const prev = toItemsMap([
+      { id: 'UI-1', updated_at: 1 },
+      { id: 'UI-2', updated_at: 2 }
+    ]);
+    const next = toItemsMap([
+      { id: 'UI-2', updated_at: 3 },
+      { id: 'UI-3', updated_at: 1 }
+    ]);
+    const d = computeDelta(prev, next);
+    expect(d.added).toEqual(['UI-3']);
+    expect(d.updated).toEqual(['UI-2']);
+    expect(d.removed).toEqual(['UI-1']);
+  });
+
+  test('computeDelta returns no changes for unchanged maps', () => {
+    const prev = toItemsMap([
+      { id: 'A', updated_at: 10, closed_at: null },
+      { id: 'B', updated_at: 20, closed_at: null }
+    ]);
+    const next = toItemsMap([
+      { id: 'A', updated_at: 10, closed_at: null },
+      { id: 'B', updated_at: 20, closed_at: null }
+    ]);
+    const d = computeDelta(prev, next);
+    expect(d.added).toEqual([]);
+    expect(d.updated).toEqual([]);
+    expect(d.removed).toEqual([]);
+  });
+
+  test('computeDelta handles empty sets', () => {
+    const empty = toItemsMap([]);
+    const some = toItemsMap([
+      { id: 'X', updated_at: 1, closed_at: null },
+      { id: 'Y', updated_at: 2, closed_at: null }
+    ]);
+
+    const d1 = computeDelta(empty, some);
+    expect(d1.added.sort()).toEqual(['X', 'Y']);
+    expect(d1.updated).toEqual([]);
+    expect(d1.removed).toEqual([]);
+
+    const d2 = computeDelta(some, empty);
+    expect(d2.added).toEqual([]);
+    expect(d2.updated).toEqual([]);
+    expect(d2.removed.sort()).toEqual(['X', 'Y']);
+  });
+
+  test('computeDelta returns only updates when ids unchanged', () => {
+    const prev = toItemsMap([
+      { id: 'A', updated_at: 1, closed_at: null },
+      { id: 'B', updated_at: 2, closed_at: null }
+    ]);
+    const next = toItemsMap([
+      { id: 'A', updated_at: 3, closed_at: null },
+      { id: 'B', updated_at: 5, closed_at: null }
+    ]);
+    const d = computeDelta(prev, next);
+    expect(d.added).toEqual([]);
+    expect(d.removed).toEqual([]);
+    expect(d.updated.sort()).toEqual(['A', 'B']);
+  });
+
+  test('attach/detach and disconnect-driven eviction', () => {
+    const reg = new SubscriptionRegistry();
+    /** @type {any} */
+    const ws_a = { OPEN: 1, readyState: 1, send: vi.fn() };
+    /** @type {any} */
+    const ws_b = { OPEN: 1, readyState: 1, send: vi.fn() };
+
+    const spec = { type: 'list', params: { status: 'open' } };
+    const { key } = reg.attach(spec, ws_a);
+    reg.attach(spec, ws_b);
+
+    const entry1 = reg.get(key);
+    expect(entry1 && entry1.subscribers.size).toBe(2);
+
+    const removed_a = reg.detach(spec, ws_a);
+    expect(removed_a).toBe(true);
+    const entry2 = reg.get(key);
+    expect(entry2 && entry2.subscribers.size).toBe(1);
+
+    // Disconnecting B should sweep it and remove empty entry
+    reg.onDisconnect(ws_b);
+    const entry3 = reg.get(key);
+    expect(entry3).toBeNull();
+  });
+
+  test('applyItems stores map and returns correct delta', () => {
+    const reg = new SubscriptionRegistry();
+    /** @type {any} */
+    const ws = { OPEN: 1, readyState: 1, send: vi.fn() };
+    const spec = { type: 'list', params: { ready: true } };
+    const { key } = reg.attach(spec, ws);
+
+    const d1 = reg.applyItems(key, [
+      { id: 'A', updated_at: 1 },
+      { id: 'B', updated_at: 1 }
+    ]);
+    expect(d1.added.sort()).toEqual(['A', 'B']);
+    expect(d1.updated).toEqual([]);
+    expect(d1.removed).toEqual([]);
+
+    const d2 = reg.applyItems(key, [
+      { id: 'B', updated_at: 2 },
+      { id: 'C', updated_at: 1 }
+    ]);
+    expect(d2.added).toEqual(['C']);
+    expect(d2.updated).toEqual(['B']);
+    expect(d2.removed).toEqual(['A']);
+  });
+});