beads-ui 0.1.2 → 0.3.0

package/server/list-adapters.js

@@ -0,0 +1,218 @@
+import { runBdJson } from './bd.js';
+
+/**
+ * Build concrete `bd` CLI args for a subscription type + params.
+ * Always includes `--json` for parseable output.
+ * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
+ * @returns {string[]}
+ */
+export function mapSubscriptionToBdArgs(spec) {
+  const t = String(spec.type);
+  switch (t) {
+    case 'all-issues': {
+      return ['list', '--json'];
+    }
+    case 'epics': {
+      return ['epic', 'status', '--json'];
+    }
+    case 'blocked-issues': {
+      return ['blocked', '--json'];
+    }
+    case 'ready-issues': {
+      return ['ready', '--limit', '1000', '--json'];
+    }
+    case 'in-progress-issues': {
+      return ['list', '--json', '--status', 'in_progress'];
+    }
+    case 'closed-issues': {
+      return ['list', '--json', '--status', 'closed'];
+    }
+    case 'issue-detail': {
+      const p = spec.params || {};
+      const id = String(p.id || '').trim();
+      if (id.length === 0) {
+        throw badRequest('Missing param: params.id');
+      }
+      return ['show', id, '--json'];
+    }
+    default: {
+      throw badRequest(`Unknown subscription type: ${t}`);
+    }
+  }
+}
+
+/**
+ * Normalize bd list output to minimal Issue shape used by the registry.
+ * - Ensures `id` is a string
+ * - Coerces timestamps to numbers
+ * - `closed_at` defaults to null when missing or invalid
+ * @param {unknown} value
+ * @returns {Array<{ id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>}
+ */
+export function normalizeIssueList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  /** @type {Array<{ id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>} */
+  const out = [];
+  for (const it of value) {
+    const id = String(it.id ?? '');
+    if (id.length === 0) {
+      continue;
+    }
+    const created_at = parseTimestamp(/** @type {any} */ (it).created_at);
+    const updated_at = parseTimestamp(it.updated_at);
+    const closed_raw = it.closed_at;
+    /** @type {number | null} */
+    let closed_at = null;
+    if (closed_raw !== undefined && closed_raw !== null) {
+      const n = parseTimestamp(closed_raw);
+      closed_at = Number.isFinite(n) ? n : null;
+    }
+    out.push({
+      ...it,
+      id,
+      created_at: Number.isFinite(created_at) ? created_at : 0,
+      updated_at: Number.isFinite(updated_at) ? updated_at : 0,
+      closed_at
+    });
+  }
+  return out;
+}
+
+/**
+ * @typedef {Object} FetchListResultSuccess
+ * @property {true} ok
+ * @property {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
+ */
+
+/**
+ * @typedef {Object} FetchListResultFailure
+ * @property {false} ok
+ * @property {{ code: string, message: string, details?: Record<string, unknown> }} error
+ */
+
+/**
+ * Execute the mapped `bd` command for a subscription spec and return normalized items.
+ * Errors do not throw; they are surfaced as a structured object.
+ * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
+ * @returns {Promise<FetchListResultSuccess | FetchListResultFailure>}
+ */
+export async function fetchListForSubscription(spec) {
+  /** @type {string[]} */
+  let args;
+  try {
+    args = mapSubscriptionToBdArgs(spec);
+  } catch (err) {
+    const e = toErrorObject(err);
+    return { ok: false, error: e };
+  }
+
+  try {
+    const res = await runBdJson(args);
+    if (!res || res.code !== 0 || !('stdoutJson' in res)) {
+      return {
+        ok: false,
+        error: {
+          code: 'bd_error',
+          message: String(res?.stderr || 'bd failed'),
+          details: { exit_code: res?.code ?? -1 }
+        }
+      };
+    }
+    // bd show may return a single object; normalize to an array first
+    let raw = Array.isArray(res.stdoutJson)
+      ? res.stdoutJson
+      : res.stdoutJson && typeof res.stdoutJson === 'object'
+        ? [res.stdoutJson]
+        : [];
+
+    // Special-case mapping for `epics`: current bd output nests the epic under
+    // an `epic` key and exposes counters at the top level. Flatten so that
+    // each entry has a top-level `id` and core fields expected by the registry.
+    if (String(spec.type) === 'epics') {
+      raw = raw.map((it) => {
+        if (it && typeof it === 'object' && 'epic' in it) {
+          const e = /** @type {any} */ (it).epic || {};
+          /** @type {Record<string, unknown>} */
+          const flat = {
+            // Required minimal fields for registry + client rendering
+            id: String(e.id ?? ''),
+            title: e.title,
+            status: e.status,
+            issue_type: e.issue_type || 'epic',
+            created_at: e.created_at,
+            updated_at: e.updated_at,
+            closed_at: e.closed_at ?? null,
+            // Preserve useful counters from bd output
+            total_children: /** @type {any} */ (it).total_children,
+            closed_children: /** @type {any} */ (it).closed_children,
+            eligible_for_close: /** @type {any} */ (it).eligible_for_close
+          };
+          return flat;
+        }
+        return it;
+      });
+    }
+
+    const items = normalizeIssueList(raw);
+    return { ok: true, items };
+  } catch (err) {
+    return {
+      ok: false,
+      error: {
+        code: 'bd_error',
+        message:
+          (err && /** @type {any} */ (err).message) || 'bd invocation failed'
+      }
+    };
+  }
+}
+
+/**
+ * Create a `bad_request` error object.
+ * @param {string} message
+ */
+function badRequest(message) {
+  const e = new Error(message);
+  // @ts-expect-error add code
+  e.code = 'bad_request';
+  return e;
+}
+
+/**
+ * Normalize arbitrary thrown values to a structured error object.
+ * @param {unknown} err
+ * @returns {FetchListResultFailure['error']}
+ */
+function toErrorObject(err) {
+  if (err && typeof err === 'object') {
+    const any = /** @type {{ code?: unknown, message?: unknown }} */ (err);
+    const code = typeof any.code === 'string' ? any.code : 'bad_request';
+    const message =
+      typeof any.message === 'string' ? any.message : 'Request error';
+    return { code, message };
+  }
+  return { code: 'bad_request', message: 'Request error' };
+}
+
+/**
+ * Parse a bd timestamp string to epoch ms using Date.parse.
+ * Falls back to numeric coercion when parsing fails.
+ * @param {unknown} v
+ * @returns {number}
+ */
+function parseTimestamp(v) {
+  if (typeof v === 'string') {
+    const ms = Date.parse(v);
+    if (Number.isFinite(ms)) {
+      return ms;
+    }
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  }
+  if (typeof v === 'number') {
+    return Number.isFinite(v) ? v : 0;
+  }
+  return 0;
+}

package/server/subscriptions.js

@@ -0,0 +1,277 @@
+/**
+ * @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,111 @@
+/**
+ * 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

@@ -6,22 +6,19 @@ 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} on_change - 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 }}
  */
-export function watchDb(root_dir, on_change, options = {}) {
+export function watchDb(root_dir, onChange, options = {}) {
   const debounce_ms = options.debounce_ms ?? 250;
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   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,9 +26,9 @@ export function watchDb(root_dir, on_change, options = {}) {
       clearTimeout(timer);
     }
     timer = setTimeout(() => {
-      on_change({ ts: Date.now() });
+      onChange();
     }, debounce_ms);
-    timer.unref?.();
+    timer.unref();
   };
 
   /**
@@ -92,11 +89,11 @@ export function watchDb(root_dir, on_change, options = {}) {
     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();