beads-ui 0.2.0 → 0.3.1

package/server/subscriptions.js

@@ -0,0 +1,289 @@
+/**
+ * @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>,
+ *   lockTail: () => void
+ * }} Entry
+ */
+
+/**
+ * Create a new, empty entry object.
+ *
+ * @returns {Entry}
+ */
+function createEntry() {
+  return {
+    itemsById: new Map(),
+    subscribers: new Set(),
+    lock: Promise.resolve(),
+    lockTail: () => {}
+  };
+}
+
+/**
+ * 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;
+    /** @type {(v?: void) => void} */
+    let release = () => {};
+    entry.lock = new Promise((resolve) => {
+      release = resolve;
+    });
+    entry.lockTail = release;
+    // Wait for previous operations to finish
+    await prev.catch(() => {});
+    try {
+      const result = await fn();
+      return result;
+    } finally {
+      // Release lock for next queued op
+      try {
+        entry.lockTail();
+      } 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);
+  }
+}
+
+/**
+ * Default singleton registry used by the ws server.
+ */
+export const registry = new SubscriptionRegistry();

package/server/validators.js

@@ -0,0 +1,113 @@
+/**
+ * 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',
+  'blocked-issues',
+  'ready-issues',
+  'in-progress-issues',
+  'closed-issues',
+  'issue-detail'
+]);
+
+/**
+ * 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 {
+    // 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

@@ -5,8 +5,9 @@ import { resolveDbPath } from './db.js';
 /**
  * Watch the resolved beads SQLite DB file and invoke a callback after a debounce window.
  * The DB path is resolved following beads precedence and can be overridden via options.
+ *
  * @param {string} root_dir - Project root directory (starting point for resolution).
- * @param {(payload: { ts: number }) => void} onChange - Called when changes are detected.
+ * @param {() => void} onChange - Called when changes are detected.
  * @param {{ debounce_ms?: number, explicit_db?: string }} [options]
  * @returns {{ close: () => void, rebind: (opts?: { root_dir?: string, explicit_db?: string }) => void, path: string }}
  */
@@ -17,11 +18,8 @@ export function watchDb(root_dir, onChange, options = {}) {
   let timer;
   /** @type {fs.FSWatcher | undefined} */
   let watcher;
-  /** @type {string} */
   let current_path = '';
-  /** @type {string} */
   let current_dir = '';
-  /** @type {string} */
   let current_file = '';
 
   const schedule = () => {
@@ -29,13 +27,14 @@ export function watchDb(root_dir, onChange, options = {}) {
       clearTimeout(timer);
     }
     timer = setTimeout(() => {
-      onChange({ ts: Date.now() });
+      onChange();
     }, debounce_ms);
-    timer.unref?.();
+    timer.unref();
   };
 
   /**
    * Attach a watcher to the directory containing the resolved DB path.
+   *
    * @param {string} base_dir
    * @param {string | undefined} explicit_db
    */
@@ -87,16 +86,17 @@ export function watchDb(root_dir, onChange, options = {}) {
     },
     /**
      * 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 nextResolved = resolveDbPath({
+      const next_resolved = resolveDbPath({
         cwd: next_root,
         explicit_db: next_explicit
       });
-      const next_path = nextResolved.path;
+      const next_path = next_resolved.path;
       if (next_path !== current_path) {
         // swap watcher
         watcher?.close();