@seungyeop-lee/beads-ui 0.13.0

package/server/subscriptions.js

@@ -0,0 +1,305 @@
+/**
+ * @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, _board_column?: string }>
+ *  - `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, _board_column?: string }} 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 ||
+      p._board_column !== meta._board_column
+    ) {
+      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, _board_column?: string }>} 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;
+    }
+    const _board_column =
+      typeof it._board_column === 'string' ? it._board_column : undefined;
+    map.set(it.id, { updated_at, closed_at, _board_column });
+  }
+  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, _board_column?: string }>} 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/validators.js

@@ -0,0 +1,153 @@
+/**
+ * Validation helpers for protocol payloads.
+ *
+ * Provides schema checks for subscription specs and selected mutations.
+ */
+
+/**
+ * Known subscription types supported by the server.
+ *
+ * @type {Set<string>}
+ */
+const SUBSCRIPTION_TYPES = new Set([
+  'all-issues',
+  'epics',
+  'board-issues',
+  'blocked-issues',
+  'ready-issues',
+  'in-progress-issues',
+  'closed-issues',
+  'filtered-issues',
+  'issue-detail'
+]);
+
+/**
+ * Allowed status tokens for `filtered-issues.params.statuses`.
+ *
+ * @type {Set<string>}
+ */
+const FILTERED_ISSUE_STATUSES = new Set(['open', 'in_progress', 'closed']);
+
+/**
+ * Validate a subscribe-list payload and normalize to a SubscriptionSpec.
+ *
+ * @param {unknown} payload
+ * @returns {{ ok: true, id: string, spec: { type: string, params?: Record<string, string|number|boolean> } } | { ok: false, code: 'bad_request', message: string }}
+ */
+export function validateSubscribeListPayload(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: 'payload must be an object'
+    };
+  }
+  const any =
+    /** @type {{ id?: unknown, type?: unknown, params?: unknown }} */ (payload);
+
+  const id = typeof any.id === 'string' ? any.id : '';
+  if (id.length === 0) {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: 'payload.id must be a non-empty string'
+    };
+  }
+
+  const type = typeof any.type === 'string' ? any.type : '';
+  if (type.length === 0 || !SUBSCRIPTION_TYPES.has(type)) {
+    return {
+      ok: false,
+      code: 'bad_request',
+      message: `payload.type must be one of: ${Array.from(SUBSCRIPTION_TYPES).join(', ')}`
+    };
+  }
+
+  /** @type {Record<string, string|number|boolean> | undefined} */
+  let params;
+  if (any.params !== undefined) {
+    if (
+      !any.params ||
+      typeof any.params !== 'object' ||
+      Array.isArray(any.params)
+    ) {
+      return {
+        ok: false,
+        code: 'bad_request',
+        message: 'payload.params must be an object when provided'
+      };
+    }
+    params = /** @type {Record<string, string|number|boolean>} */ (any.params);
+  }
+
+  // Per-type param schemas
+  if (type === 'issue-detail') {
+    const id = String(params?.id ?? '').trim();
+    if (id.length === 0) {
+      return {
+        ok: false,
+        code: 'bad_request',
+        message: 'params.id must be a non-empty string'
+      };
+    }
+    params = { id };
+  } else if (type === 'closed-issues') {
+    if (params && 'since' in params) {
+      const since = params.since;
+      const n = typeof since === 'number' ? since : Number.NaN;
+      if (!Number.isFinite(n) || n < 0) {
+        return {
+          ok: false,
+          code: 'bad_request',
+          message: 'params.since must be a non-negative number (epoch ms)'
+        };
+      }
+      params = { since: n };
+    } else {
+      params = undefined;
+    }
+  } else if (type === 'filtered-issues') {
+    if (params && 'statuses' in params) {
+      const raw = params.statuses;
+      if (typeof raw !== 'string') {
+        return {
+          ok: false,
+          code: 'bad_request',
+          message: 'params.statuses must be a comma-separated string'
+        };
+      }
+      const arr = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      if (arr.length === 0) {
+        params = undefined;
+      } else {
+        for (const s of arr) {
+          if (!FILTERED_ISSUE_STATUSES.has(s)) {
+            return {
+              ok: false,
+              code: 'bad_request',
+              message: `params.statuses contains invalid value: ${s}`
+            };
+          }
+        }
+        params = { statuses: arr.join(',') };
+      }
+    } else {
+      params = undefined;
+    }
+  } else {
+    // Other types do not accept params
+    if (params && Object.keys(params).length > 0) {
+      return {
+        ok: false,
+        code: 'bad_request',
+        message: `type ${type} does not accept params`
+      };
+    }
+    params = undefined;
+  }
+
+  return { ok: true, id, spec: { type, params } };
+}

package/server/watcher.js

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveWorkspaceDatabase } from './db.js';
+import { debug } from './logging.js';
+
+/**
+ * Watch the resolved workspace database target and invoke a callback after a
+ * debounce window.
+ *
+ * For SQLite workspaces this watches the DB file's parent directory and filters
+ * by file name. For non-SQLite backends (for example Dolt), this watches the
+ * workspace `.beads` directory.
+ *
+ * @param {string} root_dir - Project root directory (starting point for resolution).
+ * @param {() => void} onChange - Called when changes are detected.
+ * @param {{ debounce_ms?: number, cooldown_ms?: number, explicit_db?: string }} [options]
+ * @returns {{ close: () => void, rebind: (opts?: { root_dir?: string, explicit_db?: string }) => void, path: string }}
+ */
+export function watchDb(root_dir, onChange, options = {}) {
+  const debounce_ms = options.debounce_ms ?? 250;
+  const cooldown_ms = options.cooldown_ms ?? 1000;
+  const log = debug('watcher');
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {fs.FSWatcher | undefined} */
+  let watcher;
+  let cooldown_until = 0;
+  let current_path = '';
+  let current_dir = '';
+  let current_file = '';
+
+  /**
+   * Schedule the debounced onChange callback.
+   */
+  const schedule = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      onChange();
+      cooldown_until = Date.now() + cooldown_ms;
+    }, debounce_ms);
+    timer.unref();
+  };
+
+  /**
+   * Attach a watcher to the directory containing the resolved DB path.
+   *
+   * @param {string} base_dir
+   * @param {string | undefined} explicit_db
+   */
+  const bind = (base_dir, explicit_db) => {
+    const resolved = resolveWorkspaceDatabase({ cwd: base_dir, explicit_db });
+    current_path = resolved.path;
+    if (pathIsDirectory(current_path)) {
+      current_dir = current_path;
+      current_file = '';
+    } else {
+      current_dir = path.dirname(current_path);
+      current_file = path.basename(current_path);
+    }
+    if (!resolved.exists) {
+      log(
+        'resolved workspace database missing: %s – Hint: set --db, export BEADS_DB, or run `bd init` in your workspace.',
+        current_path
+      );
+    }
+
+    // (Re)create watcher
+    try {
+      watcher = fs.watch(
+        current_dir,
+        { persistent: true },
+        (event_type, filename) => {
+          if (current_file && filename && String(filename) !== current_file) {
+            return;
+          }
+          if (event_type === 'change' || event_type === 'rename') {
+            if (Date.now() < cooldown_until) {
+              return;
+            }
+            log('fs %s %s', event_type, filename || '');
+            schedule();
+          }
+        }
+      );
+    } catch (err) {
+      log('unable to watch directory %s %o', current_dir, err);
+    }
+  };
+
+  // initial bind
+  bind(root_dir, options.explicit_db);
+
+  return {
+    get path() {
+      return current_path;
+    },
+    close() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+    },
+    /**
+     * Re-resolve and reattach watcher when root_dir or explicit_db changes.
+     *
+     * @param {{ root_dir?: string, explicit_db?: string }} [opts]
+     */
+    rebind(opts = {}) {
+      const next_root = opts.root_dir ? String(opts.root_dir) : root_dir;
+      const next_explicit = opts.explicit_db ?? options.explicit_db;
+      const next_resolved = resolveWorkspaceDatabase({
+        cwd: next_root,
+        explicit_db: next_explicit
+      });
+      const next_path = next_resolved.path;
+      if (next_path !== current_path) {
+        // swap watcher
+        watcher?.close();
+        cooldown_until = 0;
+        bind(next_root, next_explicit);
+      }
+    }
+  };
+}
+
+/**
+ * @param {string} file_path
+ */
+function pathIsDirectory(file_path) {
+  try {
+    return fs.statSync(file_path).isDirectory();
+  } catch {
+    return false;
+  }
+}