beads-ui 0.3.0 → 0.4.0

package/server/list-adapters.js

@@ -3,6 +3,7 @@ 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[]}
  */
@@ -43,9 +44,10 @@ export function mapSubscriptionToBdArgs(spec) {
 
 /**
  * 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
+ * - 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>>}
  */
@@ -95,6 +97,7 @@ export function normalizeIssueList(value) {
 /**
  * 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>}
  */
@@ -171,6 +174,7 @@ export async function fetchListForSubscription(spec) {
 
 /**
  * Create a `bad_request` error object.
+ *
  * @param {string} message
  */
 function badRequest(message) {
@@ -182,6 +186,7 @@ function badRequest(message) {
 
 /**
  * Normalize arbitrary thrown values to a structured error object.
+ *
  * @param {unknown} err
  * @returns {FetchListResultFailure['error']}
  */
@@ -199,6 +204,7 @@ function toErrorObject(err) {
 /**
  * Parse a bd timestamp string to epoch ms using Date.parse.
  * Falls back to numeric coercion when parsing fails.
+ *
  * @param {unknown} v
  * @returns {number}
  */

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/subscriptions.js

@@ -36,6 +36,7 @@
 
 /**
  * Create a new, empty entry object.
+ *
  * @returns {Entry}
  */
 function createEntry() {
@@ -49,6 +50,7 @@ function createEntry() {
 
 /**
  * Generate a stable subscription key string from a spec. Sorts params keys.
+ *
  * @param {SubscriptionSpec} spec
  * @returns {string}
  */
@@ -69,6 +71,7 @@ export function keyOf(spec) {
 
 /**
  * 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[] }}
@@ -101,6 +104,7 @@ export function computeDelta(prev, next) {
 
 /**
  * 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>}
  */
@@ -136,6 +140,7 @@ export class SubscriptionRegistry {
 
   /**
    * Get an entry by key, or null if missing.
+   *
    * @param {string} key
    * @returns {Entry | null}
    */
@@ -145,6 +150,7 @@ export class SubscriptionRegistry {
 
   /**
    * Ensure an entry exists for a spec; returns the key and entry.
+   *
    * @param {SubscriptionSpec} spec
    * @returns {{ key: string, entry: Entry }}
    */
@@ -160,6 +166,7 @@ export class SubscriptionRegistry {
 
   /**
    * Attach a subscriber to a spec. Creates the entry if missing.
+   *
    * @param {SubscriptionSpec} spec
    * @param {WebSocket} ws
    * @returns {{ key: string, subscribed: true }}
@@ -173,6 +180,7 @@ export class SubscriptionRegistry {
   /**
    * 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
@@ -189,6 +197,7 @@ export class SubscriptionRegistry {
   /**
    * 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) {
@@ -207,6 +216,7 @@ export class SubscriptionRegistry {
 
   /**
    * Serialize a function against a key so only one runs at a time per key.
+   *
    * @template T
    * @param {string} key
    * @param {() => Promise<T>} fn
@@ -243,6 +253,7 @@ export class SubscriptionRegistry {
 
   /**
    * 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[] }}
@@ -261,6 +272,7 @@ export class SubscriptionRegistry {
 
   /**
    * 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[] }}

package/server/validators.js

@@ -6,6 +6,7 @@
 
 /**
  * Known subscription types supported by the server.
+ *
  * @type {Set<string>}
  */
 const SUBSCRIPTION_TYPES = new Set([
@@ -20,6 +21,7 @@ const SUBSCRIPTION_TYPES = new Set([
 
 /**
  * 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 }}
  */

package/server/watcher.js

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { resolveDbPath } from './db.js';
+import { debug } from './logging.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 {() => void} onChange - Called when changes are detected.
  * @param {{ debounce_ms?: number, explicit_db?: string }} [options]
@@ -12,6 +14,7 @@ import { resolveDbPath } from './db.js';
  */
 export function watchDb(root_dir, onChange, options = {}) {
   const debounce_ms = options.debounce_ms ?? 250;
+  const log = debug('watcher');
 
   /** @type {ReturnType<typeof setTimeout> | undefined} */
   let timer;
@@ -33,6 +36,7 @@ export function watchDb(root_dir, onChange, options = {}) {
 
   /**
    * Attach a watcher to the directory containing the resolved DB path.
+   *
    * @param {string} base_dir
    * @param {string | undefined} explicit_db
    */
@@ -42,10 +46,9 @@ export function watchDb(root_dir, onChange, options = {}) {
     current_dir = path.dirname(current_path);
     current_file = path.basename(current_path);
     if (!resolved.exists) {
-      console.warn(
-        'watchDb: resolved DB does not exist yet:',
-        current_path,
-        '\nHint: set --db, export BEADS_DB, or run `bd init` in your workspace.'
+      log(
+        'resolved DB missing: %s – Hint: set --db, export BEADS_DB, or run `bd init` in your workspace.',
+        current_path
       );
     }
 
@@ -59,12 +62,13 @@ export function watchDb(root_dir, onChange, options = {}) {
             return;
           }
           if (event_type === 'change' || event_type === 'rename') {
+            log('fs %s %s', event_type, filename || '');
             schedule();
           }
         }
       );
     } catch (err) {
-      console.warn('watchDb: unable to watch directory', current_dir, err);
+      log('unable to watch directory %s %o', current_dir, err);
     }
   };
 
@@ -84,6 +88,7 @@ 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 = {}) {

package/server/ws.js

@@ -6,10 +6,13 @@
 import { WebSocketServer } from 'ws';
 import { runBd, runBdJson } from './bd.js';
 import { fetchListForSubscription } from './list-adapters.js';
+import { debug } from './logging.js';
 import { isRequest, makeError, makeOk } from './protocol.js';
 import { keyOf, registry } from './subscriptions.js';
 import { validateSubscribeListPayload } from './validators.js';
 
+const log = debug('ws');
+
 /**
  * Debounced refresh scheduling for active list subscriptions.
  * A trailing window coalesces rapid change bursts into a single refresh run.
@@ -40,6 +43,7 @@ let MUTATION_GATE = null;
  * suppressed during the window.
  *
  * Fire-and-forget; callers should not await this.
+ *
  * @param {number} [timeout_ms]
  */
 function triggerMutationRefreshOnce(timeout_ms = 500) {
@@ -76,6 +80,7 @@ function triggerMutationRefreshOnce(timeout_ms = 500) {
 
   // After resolution, run a single refresh across active subs and clear gate
   void p.then(async () => {
+    log('mutation window resolved → refresh active subs');
     try {
       await refreshAllActiveListSubscriptions();
     } catch {
@@ -95,6 +100,7 @@ function triggerMutationRefreshOnce(timeout_ms = 500) {
 
 /**
  * Collect unique active list subscription specs across all connected clients.
+ *
  * @returns {Array<{ type: string, params?: Record<string,string|number|boolean> }>}
  */
 function collectActiveListSpecs() {
@@ -181,6 +187,7 @@ let CURRENT_WSS = null;
 
 /**
  * Get or initialize the subscription state for a socket.
+ *
  * @param {WebSocket} ws
  * @returns {any}
  */
@@ -199,6 +206,7 @@ function ensureSubs(ws) {
 
 /**
  * Get next monotonically increasing revision for a subscription key on this connection.
+ *
  * @param {WebSocket} ws
  * @param {string} key
  */
@@ -306,6 +314,7 @@ function emitSubscriptionDelete(ws, client_id, key, issue_id) {
 /**
  * Refresh a subscription spec: fetch via adapter, apply to registry and emit
  * per-subscription full-issue envelopes to subscribers. Serialized per key.
+ *
  * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
  */
 async function refreshAndPublish(spec) {
@@ -316,17 +325,17 @@ async function refreshAndPublish(spec) {
       return;
     }
     const items = applyClosedIssuesFilter(spec, res.items);
-    const prevSize = registry.get(key)?.itemsById.size || 0;
+    const prev_size = registry.get(key)?.itemsById.size || 0;
     const delta = registry.applyItems(key, items);
     const entry = registry.get(key);
     if (!entry || entry.subscribers.size === 0) {
       return;
     }
     /** @type {Map<string, any>} */
-    const byId = new Map();
+    const by_id = new Map();
     for (const it of items) {
       if (it && typeof it.id === 'string') {
-        byId.set(it.id, it);
+        by_id.set(it.id, it);
       }
     }
     for (const ws of entry.subscribers) {
@@ -334,20 +343,20 @@ async function refreshAndPublish(spec) {
       const s = ensureSubs(ws);
       const subs = s.list_subs || new Map();
       /** @type {string[]} */
-      const clientIds = [];
+      const client_ids = [];
       for (const [cid, v] of subs.entries()) {
-        if (v.key === key) clientIds.push(cid);
+        if (v.key === key) client_ids.push(cid);
       }
-      if (clientIds.length === 0) continue;
-      if (prevSize === 0) {
-        for (const cid of clientIds) {
+      if (client_ids.length === 0) continue;
+      if (prev_size === 0) {
+        for (const cid of client_ids) {
           emitSubscriptionSnapshot(ws, cid, key, items);
         }
         continue;
       }
-      for (const cid of clientIds) {
+      for (const cid of client_ids) {
         for (const id of [...delta.added, ...delta.updated]) {
-          const issue = byId.get(id);
+          const issue = by_id.get(id);
           if (issue) {
             emitSubscriptionUpsert(ws, cid, key, issue);
           }
@@ -362,6 +371,7 @@ async function refreshAndPublish(spec) {
 
 /**
  * Apply pre-diff filtering for closed-issues lists based on spec.params.since (epoch ms).
+ *
  * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
  * @param {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
  */
@@ -387,6 +397,7 @@ function applyClosedIssuesFilter(spec, items) {
 
 /**
  * Attach a WebSocket server to an existing HTTP server.
+ *
  * @param {Server} http_server
  * @param {{ path?: string, heartbeat_ms?: number, refresh_debounce_ms?: number }} [options]
  * @returns {{ wss: WebSocketServer, broadcast: (type: MessageType, payload?: unknown) => void, scheduleListRefresh: () => void }}
@@ -406,6 +417,7 @@ export function attachWsServer(http_server, options = {}) {
 
   // Heartbeat: track if client answered the last ping
   wss.on('connection', (ws) => {
+    log('client connected');
     // @ts-expect-error add marker property
     ws.isAlive = true;
 
@@ -451,6 +463,7 @@ export function attachWsServer(http_server, options = {}) {
 
   /**
    * Broadcast a server-initiated event to all open clients.
+   *
    * @param {MessageType} type
    * @param {unknown} [payload]
    */
@@ -478,6 +491,7 @@ export function attachWsServer(http_server, options = {}) {
 
 /**
  * Handle an incoming message frame and respond to the same socket.
+ *
  * @param {WebSocket} ws
  * @param {RawData} data
  */
@@ -498,6 +512,7 @@ export async function handleMessage(ws, data) {
   }
 
   if (!isRequest(json)) {
+    log('invalid request');
     const reply = {
       id: 'unknown',
       ok: false,
@@ -518,6 +533,7 @@ export async function handleMessage(ws, data) {
 
   // subscribe-list: payload { id: string, type: string, params?: object }
   if (req.type === 'subscribe-list') {
+    log('subscribe-list %s', /** @type {any} */ (req.payload)?.id || '');
     const validation = validateSubscribeListPayload(
       /** @type {any} */ (req.payload || {})
     );
@@ -553,6 +569,7 @@ export async function handleMessage(ws, data) {
 
   // unsubscribe-list: payload { id: string }
   if (req.type === 'unsubscribe-list') {
+    log('unsubscribe-list %s', /** @type {any} */ (req.payload)?.id || '');
     const { id: client_id } = /** @type {any} */ (req.payload || {});
     if (typeof client_id !== 'string' || client_id.length === 0) {
       ws.send(
@@ -637,6 +654,7 @@ export async function handleMessage(ws, data) {
 
   // update-status
   if (req.type === 'update-status') {
+    log('update-status');
     const { id, status } = /** @type {any} */ (req.payload);
     const allowed = new Set(['open', 'in_progress', 'closed']);
     if (
@@ -682,6 +700,7 @@ export async function handleMessage(ws, data) {
 
   // update-priority
   if (req.type === 'update-priority') {
+    log('update-priority');
     const { id, priority } = /** @type {any} */ (req.payload);
     if (
       typeof id !== 'string' ||
@@ -726,6 +745,7 @@ export async function handleMessage(ws, data) {
 
   // edit-text
   if (req.type === 'edit-text') {
+    log('edit-text');
     const { id, field, value } = /** @type {any} */ (req.payload);
     if (
       typeof id !== 'string' ||
@@ -789,6 +809,7 @@ export async function handleMessage(ws, data) {
 
   // create-issue
   if (req.type === 'create-issue') {
+    log('create-issue');
     const { title, type, priority, description } = /** @type {any} */ (
       req.payload || {}
     );

package/app/data/list-selectors.js

@@ -1,98 +0,0 @@
-/**
- * List selectors utility: compose subscription membership with issues entities
- * and apply view-specific sorting. Provides a lightweight `subscribe` that
- * triggers once per issues envelope to let views re-render.
- */
-/**
- * @typedef {{ id: string, title?: string, status?: 'open'|'in_progress'|'closed', priority?: number, issue_type?: string, created_at?: number, updated_at?: number, closed_at?: number }} IssueLite
- */
-import { cmpClosedDesc, cmpPriorityThenCreated } from './sort.js';
-
-/**
- * Factory for list selectors.
- *
- * Source of truth is per-subscription stores providing snapshots for a given
- * client id. Central issues store fallback has been removed.
- * @param {{ snapshotFor?: (client_id: string) => IssueLite[], subscribe?: (fn: () => void) => () => void }} [issue_stores]
- */
-export function createListSelectors(issue_stores = undefined) {
-  // Sorting comparators are centralized in app/data/sort.js
-
-  /**
-   * Get entities for a subscription id with Issues List sort (priority asc → created asc).
-   * @param {string} client_id
-   * @returns {IssueLite[]}
-   */
-  function selectIssuesFor(client_id) {
-    if (!issue_stores || typeof issue_stores.snapshotFor !== 'function') {
-      return [];
-    }
-    return issue_stores
-      .snapshotFor(client_id)
-      .slice()
-      .sort(cmpPriorityThenCreated);
-  }
-
-  /**
-   * Get entities for a Board column with column-specific sort.
-   * @param {string} client_id
-   * @param {'ready'|'blocked'|'in_progress'|'closed'} mode
-   * @returns {IssueLite[]}
-   */
-  function selectBoardColumn(client_id, mode) {
-    const arr =
-      issue_stores && issue_stores.snapshotFor
-        ? issue_stores.snapshotFor(client_id).slice()
-        : [];
-    if (mode === 'in_progress') {
-      arr.sort(cmpPriorityThenCreated);
-    } else if (mode === 'closed') {
-      arr.sort(cmpClosedDesc);
-    } else {
-      // ready/blocked share the same sort
-      arr.sort(cmpPriorityThenCreated);
-    }
-    return arr;
-  }
-
-  /**
-   * Get children for an epic subscribed as client id `epic:${id}`.
-   * Sorted as Issues List (priority asc → created asc).
-   * @param {string} epic_id
-   * @returns {IssueLite[]}
-   */
-  function selectEpicChildren(epic_id) {
-    if (!issue_stores || typeof issue_stores.snapshotFor !== 'function') {
-      return [];
-    }
-    // Epic detail subscription uses client id `detail:<id>` and contains the
-    // epic entity with a `dependents` array. Render children from that list.
-    const arr = /** @type {any[]} */ (
-      issue_stores.snapshotFor(`detail:${epic_id}`) || []
-    );
-    const epic = arr.find((it) => String(it?.id || '') === String(epic_id));
-    const dependents = Array.isArray(epic?.dependents) ? epic.dependents : [];
-    return /** @type {IssueLite[]} */ (
-      dependents.slice().sort(cmpPriorityThenCreated)
-    );
-  }
-
-  /**
-   * Subscribe for re-render; triggers once per issues envelope.
-   * @param {() => void} fn
-   * @returns {() => void}
-   */
-  function subscribe(fn) {
-    if (issue_stores && typeof issue_stores.subscribe === 'function') {
-      return issue_stores.subscribe(fn);
-    }
-    return () => {};
-  }
-
-  return {
-    selectIssuesFor,
-    selectBoardColumn,
-    selectEpicChildren,
-    subscribe
-  };
-}

package/app/data/providers.js

@@ -1,76 +0,0 @@
-/**
- * @import { MessageType } from '../protocol.js'
- */
-/**
- * Data layer: typed wrappers around the ws transport for mutations and
- * single-issue fetch. List reads have been removed in favor of push-only
- * stores and selectors (see docs/adr/001-push-only-lists.md).
- * @param {(type: MessageType, payload?: unknown) => Promise<unknown>} transport - Request/response function.
- * @returns {{ updateIssue: (input: { id: string, title?: string, acceptance?: string, notes?: string, design?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }) => Promise<unknown> }}
- */
-export function createDataLayer(transport) {
-  /**
-   * Update issue fields by dispatching specific mutations.
-   * Supported fields: title, acceptance, notes, design, status, priority, assignee.
-   * Returns the updated issue on success.
-   * @param {{ id: string, title?: string, acceptance?: string, notes?: string, design?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }} input
-   * @returns {Promise<unknown>}
-   */
-  async function updateIssue(input) {
-    const { id } = input;
-    /** @type {unknown} */
-    let last = null;
-    if (typeof input.title === 'string') {
-      last = await transport('edit-text', {
-        id,
-        field: 'title',
-        value: input.title
-      });
-    }
-    if (typeof input.acceptance === 'string') {
-      last = await transport('edit-text', {
-        id,
-        field: 'acceptance',
-        value: input.acceptance
-      });
-    }
-    if (typeof input.notes === 'string') {
-      last = await transport('edit-text', {
-        id,
-        field: 'notes',
-        value: input.notes
-      });
-    }
-    if (typeof input.design === 'string') {
-      last = await transport('edit-text', {
-        id,
-        field: 'design',
-        value: input.design
-      });
-    }
-    if (typeof input.status === 'string') {
-      last = await transport('update-status', {
-        id,
-        status: input.status
-      });
-    }
-    if (typeof input.priority === 'number') {
-      last = await transport('update-priority', {
-        id,
-        priority: input.priority
-      });
-    }
-    // type updates are not supported via UI
-    if (typeof input.assignee === 'string') {
-      last = await transport('update-assignee', {
-        id,
-        assignee: input.assignee
-      });
-    }
-    return last;
-  }
-
-  return {
-    updateIssue
-  };
-}

package/app/data/sort.js

@@ -1,45 +0,0 @@
-/**
- * Shared sort comparators for issues lists.
- * Centralizes sorting so views and stores stay consistent.
- */
-
-/**
- * @typedef {{ id: string, title?: string, status?: 'open'|'in_progress'|'closed', priority?: number, issue_type?: string, created_at?: number, updated_at?: number, closed_at?: number }} IssueLite
- */
-
-/**
- * Compare by priority asc, then created_at asc, then id asc.
- * @param {IssueLite} a
- * @param {IssueLite} b
- */
-export function cmpPriorityThenCreated(a, b) {
-  const pa = a.priority ?? 2;
-  const pb = b.priority ?? 2;
-  if (pa !== pb) {
-    return pa - pb;
-  }
-  const ca = a.created_at ?? 0;
-  const cb = b.created_at ?? 0;
-  if (ca !== cb) {
-    return ca < cb ? -1 : 1;
-  }
-  const ida = a.id;
-  const idb = b.id;
-  return ida < idb ? -1 : ida > idb ? 1 : 0;
-}
-
-/**
- * Compare by closed_at desc, then id asc for stability.
- * @param {IssueLite} a
- * @param {IssueLite} b
- */
-export function cmpClosedDesc(a, b) {
-  const ca = a.closed_at ?? 0;
-  const cb = b.closed_at ?? 0;
-  if (ca !== cb) {
-    return ca < cb ? 1 : -1;
-  }
-  const ida = a?.id;
-  const idb = b?.id;
-  return ida < idb ? -1 : ida > idb ? 1 : 0;
-}