beads-ui 0.2.0 → 0.3.1

package/CHANGES.md

@@ -1,5 +1,19 @@
 # Changes
 
+## 0.3.1
+
+- [`3912ae5`](https://github.com/mantoni/beads-ui/commit/3912ae552b1cc97e61fbaaa0815ca77675c542e4)
+  Status filter intermittently not applied on Issues screen
+- [`a160484`](https://github.com/mantoni/beads-ui/commit/a16048479d1d7d61ed4ad4e53365a5736eb053af)
+  Upgrade eslint-plugin-jsdoc and switch config
+
+_Released by [Maximilian Antoni](https://github.com/mantoni) on 2025-10-27._
+
+## 0.3.0
+
+- 🍏 Rewrite data-exchange layer to push-only updates via WebSocket.
+- 🐛 Heaps of bug fixes.
+
 ## 0.2.0
 
 - 🍏 Add "Blocked" column to board

package/README.md

@@ -16,17 +16,17 @@
 ## Features
 
 - ✨ **Zero setup** – just run `bdui start`
-- 🎨 **Beautiful design** – Responsive and dark mode support
-- ⌨️ **Keyboard navigation** – Navigate and edit without touching the mouse
-- ⚡ **Live updates** – Monitors the beads database for changes
+- 📺 **Live updates** – Monitors the beads database for changes
 - 🔎 **Issues view** – Filter and search issues, edit inline
 - ⛰️ **Epics view** – Show progress per epic, expand rows, edit inline
 - 🏂 **Board view** – Open / Blocked / Ready / In progress / Closed columns
+- ⌨️ **Keyboard navigation** – Navigate and edit without touching the mouse
 
 ## Setup
 
 ```sh
-npm i -g beads-ui
+npm i beads-ui -g
+# In the project directory with a beads database:
 bdui start --open
 ```
 

package/app/data/list-selectors.js

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

@@ -2,143 +2,19 @@
  * @import { MessageType } from '../protocol.js'
  */
 /**
- * Data layer: typed wrappers around the ws transport for bd-backed queries.
+ * 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.
- * @param {(type: MessageType, handler: (payload: unknown) => void) => void} [onEvent] - Optional event subscription (used to invalidate caches on push updates).
- * @returns {{ getEpicStatus: () => Promise<unknown[]>, getReady: () => Promise<unknown[]>, getBlocked: () => Promise<unknown[]>, getOpen: () => Promise<unknown[]>, getInProgress: () => Promise<unknown[]>, getClosed: (limit?: number) => Promise<unknown[]>, getIssue: (id: string) => Promise<unknown>, updateIssue: (input: { id: string, title?: string, acceptance?: string, notes?: string, design?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }) => Promise<unknown> }}
+ * @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, onEvent) {
-  /** @type {{ list_ready?: unknown, list_blocked?: unknown, list_open?: unknown, list_in_progress?: unknown, list_closed_10?: unknown, epic_status?: unknown }} */
-  const cache = {};
-
-  // Invalidate caches on server push updates when available
-  if (onEvent) {
-    try {
-      onEvent('issues-changed', () => {
-        cache.list_ready = undefined;
-        cache.list_blocked = undefined;
-        cache.list_open = undefined;
-        cache.list_in_progress = undefined;
-        cache.list_closed_10 = undefined;
-        cache.epic_status = undefined;
-      });
-    } catch {
-      // noop
-    }
-  }
-
-  /**
-   * Get epic status groups via `bd epic status --json`.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getEpicStatus() {
-    if (Array.isArray(cache.epic_status)) {
-      return cache.epic_status;
-    }
-    const res = await transport('epic-status');
-    const arr = Array.isArray(res) ? res : [];
-    cache.epic_status = arr;
-    return arr;
-  }
-
-  /**
-   * Ready issues: `bd ready --json`.
-   * Sort by priority then updated_at on the UI; transport returns raw list.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getReady() {
-    if (Array.isArray(cache.list_ready)) {
-      return cache.list_ready;
-    }
-    /** @type {unknown} */
-    const res = await transport('list-issues', { filters: { ready: true } });
-    const arr = Array.isArray(res) ? res : [];
-    cache.list_ready = arr;
-    return arr;
-  }
-
-  /**
-   * Blocked issues: `bd blocked --json`.
-   * Sort by priority then updated_at on the UI; transport returns raw list.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getBlocked() {
-    if (Array.isArray(cache.list_blocked)) {
-      return cache.list_blocked;
-    }
-    /** @type {unknown} */
-    const res = await transport('list-issues', { filters: { blocked: true } });
-    const arr = Array.isArray(res) ? res : [];
-    cache.list_blocked = arr;
-    return arr;
-  }
-
-  /**
-   * Open issues: `bd list -s open --json`.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getOpen() {
-    if (Array.isArray(cache.list_open)) {
-      return cache.list_open;
-    }
-    const res = await transport('list-issues', {
-      filters: { status: 'open' }
-    });
-    const arr = Array.isArray(res) ? res : [];
-    cache.list_open = arr;
-    return arr;
-  }
-
-  /**
-   * In progress issues: `bd list -s in_progress --json`.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getInProgress() {
-    if (Array.isArray(cache.list_in_progress)) {
-      return cache.list_in_progress;
-    }
-    const res = await transport('list-issues', {
-      filters: { status: 'in_progress' }
-    });
-    const arr = Array.isArray(res) ? res : [];
-    cache.list_in_progress = arr;
-    return arr;
-  }
-
-  /**
-   * Closed issues: `bd list --status closed --json`.
-   * Note: Do not send a `limit` for closed. The board applies a timeframe
-   * filter (today/3/7 days) client-side and needs the full closed set.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getClosed() {
-    if (Array.isArray(cache.list_closed_10)) {
-      // Reuse existing cache slot for closed list to avoid widening cache API
-      return cache.list_closed_10;
-    }
-    const res = await transport('list-issues', {
-      filters: { status: 'closed' }
-    });
-    const arr = Array.isArray(res) ? res : [];
-    cache.list_closed_10 = arr;
-    return arr;
-  }
-
-  /**
-   * Show a single issue via `bd show <id> --json`.
-   * @param {string} id
-   * @returns {Promise<unknown>}
-   */
-  async function getIssue(id) {
-    /** @type {unknown} */
-    const res = await transport('show-issue', { id });
-    return res;
-  }
-
+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>}
    */
@@ -197,13 +73,6 @@ export function createDataLayer(transport, onEvent) {
   }
 
   return {
-    getEpicStatus,
-    getReady,
-    getBlocked,
-    getOpen,
-    getInProgress,
-    getClosed,
-    getIssue,
     updateIssue
   };
 }

package/app/data/sort.js

@@ -0,0 +1,47 @@
+/**
+ * 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;
+}

package/app/data/subscription-issue-store.js

@@ -0,0 +1,161 @@
+/**
+ * @import { SubscriptionIssueStore, SubscriptionIssueStoreOptions } from '../../types/subscription-issue-store.js'
+ */
+import { cmpPriorityThenCreated } from './sort.js';
+
+/**
+ * Per-subscription issue store. Holds full Issue objects and exposes a
+ * deterministic, read-only snapshot for rendering. Applies snapshot/upsert/
+ * delete messages in revision order and preserves object identity per id.
+ */
+
+/**
+ * Create a SubscriptionIssueStore for a given subscription id.
+ *
+ * @param {string} id
+ * @param {SubscriptionIssueStoreOptions} [options]
+ * @returns {SubscriptionIssueStore}
+ */
+export function createSubscriptionIssueStore(id, options = {}) {
+  /** @type {Map<string, any>} */
+  const items_by_id = new Map();
+  /** @type {any[]} */
+  let ordered = [];
+  /** @type {number} */
+  let last_revision = 0;
+  /** @type {Set<() => void>} */
+  const listeners = new Set();
+  /** @type {boolean} */
+  let is_disposed = false;
+  /** @type {(a:any,b:any)=>number} */
+  const sort = options.sort || cmpPriorityThenCreated;
+
+  function emit() {
+    for (const fn of Array.from(listeners)) {
+      try {
+        fn();
+      } catch {
+        // ignore listener errors
+      }
+    }
+  }
+
+  function rebuildOrdered() {
+    ordered = Array.from(items_by_id.values()).sort(sort);
+  }
+
+  /**
+   * Apply snapshot/upsert/delete in revision order. Snapshots reset state.
+   * - Ignore messages with revision <= last_revision (except snapshot which resets first).
+   * - Preserve object identity when updating an existing item by mutating
+   *   fields in place rather than replacing the object reference.
+   *
+   * @param {{ type: 'snapshot'|'upsert'|'delete', id: string, revision: number, issues?: any[], issue?: any, issue_id?: string }} msg
+   */
+  function applyPush(msg) {
+    if (is_disposed) {
+      return;
+    }
+    if (!msg || msg.id !== id) {
+      return;
+    }
+    const rev = Number(msg.revision) || 0;
+    // Ignore stale messages for all types, including snapshots
+    if (rev <= last_revision && msg.type !== 'snapshot') {
+      return; // stale or duplicate non-snapshot
+    }
+    if (msg.type === 'snapshot') {
+      if (rev <= last_revision) {
+        return; // ignore stale snapshot
+      }
+      items_by_id.clear();
+      const items = Array.isArray(msg.issues) ? msg.issues : [];
+      for (const it of items) {
+        if (it && typeof it.id === 'string' && it.id.length > 0) {
+          items_by_id.set(it.id, it);
+        }
+      }
+      rebuildOrdered();
+      last_revision = rev;
+      emit();
+      return;
+    }
+    if (msg.type === 'upsert') {
+      const it = msg.issue;
+      if (it && typeof it.id === 'string' && it.id.length > 0) {
+        const existing = items_by_id.get(it.id);
+        if (!existing) {
+          items_by_id.set(it.id, it);
+        } else {
+          // Guard with updated_at; prefer newer
+          const prev_ts = Number.isFinite(existing.updated_at)
+            ? /** @type {number} */ (existing.updated_at)
+            : 0;
+          const next_ts = Number.isFinite(it.updated_at)
+            ? /** @type {number} */ (it.updated_at)
+            : 0;
+          if (prev_ts <= next_ts) {
+            // Mutate existing object to preserve reference
+            for (const k of Object.keys(existing)) {
+              if (!(k in it)) {
+                // remove keys that disappeared to avoid stale fields
+                delete existing[k];
+              }
+            }
+            for (const [k, v] of Object.entries(it)) {
+              // @ts-ignore - dynamic assignment
+              existing[k] = v;
+            }
+          } else {
+            // stale by timestamp; ignore
+          }
+        }
+        rebuildOrdered();
+      }
+      last_revision = rev;
+      emit();
+    } else if (msg.type === 'delete') {
+      const rid = String(msg.issue_id || '');
+      if (rid) {
+        items_by_id.delete(rid);
+        rebuildOrdered();
+      }
+      last_revision = rev;
+      emit();
+    }
+  }
+
+  return {
+    id,
+    /**
+     * @param {() => void} fn
+     */
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+    applyPush,
+    snapshot() {
+      // Return as read-only view; callers must not mutate
+      return ordered;
+    },
+    size() {
+      return items_by_id.size;
+    },
+    /**
+     * @param {string} xid
+     */
+    getById(xid) {
+      return items_by_id.get(xid);
+    },
+    dispose() {
+      is_disposed = true;
+      items_by_id.clear();
+      ordered = [];
+      listeners.clear();
+      last_revision = 0;
+    }
+  };
+}

package/app/data/subscription-issue-stores.js

@@ -0,0 +1,128 @@
+/**
+ * @import { SubscriptionIssueStoreOptions } from '../../types/subscription-issue-store.js'
+ * @import { IssueLite } from './list-selectors.js'
+ */
+import { createSubscriptionIssueStore } from './subscription-issue-store.js';
+import { subKeyOf } from './subscriptions-store.js';
+
+/**
+ * Registry managing per-subscription issue stores. Stores receive full-issue
+ * push envelopes (snapshot/upsert/delete) per subscription id and expose
+ * read-only snapshots for rendering.
+ */
+export function createSubscriptionIssueStores() {
+  /** @type {Map<string, ReturnType<typeof createSubscriptionIssueStore>>} */
+  const stores_by_id = new Map();
+  /** @type {Map<string, string>} */
+  const key_by_id = new Map();
+  /** @type {Set<() => void>} */
+  const listeners = new Set();
+  /** @type {Map<string, () => void>} */
+  const store_unsubs = new Map();
+
+  function emit() {
+    for (const fn of Array.from(listeners)) {
+      try {
+        fn();
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * Ensure a store exists for client_id and attach a listener that fans out
+   * store-level updates to global listeners.
+   *
+   * @param {string} client_id
+   * @param {{ type: string, params?: Record<string, string|number|boolean> }} [spec]
+   * @param {SubscriptionIssueStoreOptions} [options]
+   */
+  function register(client_id, spec, options) {
+    const next_key = spec ? subKeyOf(spec) : '';
+    const prev_key = key_by_id.get(client_id) || '';
+    const has_store = stores_by_id.has(client_id);
+    // If the subscription spec changed for an existing client id, replace the
+    // underlying store to reset revision state and avoid ignoring a fresh
+    // snapshot with a lower revision (different server list).
+    if (has_store && prev_key && next_key && prev_key !== next_key) {
+      const prev_store = stores_by_id.get(client_id);
+      if (prev_store) {
+        try {
+          prev_store.dispose();
+        } catch {
+          // ignore
+        }
+      }
+      const off_prev = store_unsubs.get(client_id);
+      if (off_prev) {
+        try {
+          off_prev();
+        } catch {
+          // ignore
+        }
+        store_unsubs.delete(client_id);
+      }
+      const new_store = createSubscriptionIssueStore(client_id, options);
+      stores_by_id.set(client_id, new_store);
+      const off_new = new_store.subscribe(() => emit());
+      store_unsubs.set(client_id, off_new);
+    } else if (!has_store) {
+      const store = createSubscriptionIssueStore(client_id, options);
+      stores_by_id.set(client_id, store);
+      // Fan out per-store events to global subscribers
+      const off = store.subscribe(() => emit());
+      store_unsubs.set(client_id, off);
+    }
+    key_by_id.set(client_id, next_key);
+    return () => unregister(client_id);
+  }
+
+  /**
+   * @param {string} client_id
+   */
+  function unregister(client_id) {
+    key_by_id.delete(client_id);
+    const store = stores_by_id.get(client_id);
+    if (store) {
+      store.dispose();
+      stores_by_id.delete(client_id);
+    }
+    const off = store_unsubs.get(client_id);
+    if (off) {
+      try {
+        off();
+      } catch {
+        // ignore
+      }
+      store_unsubs.delete(client_id);
+    }
+  }
+
+  return {
+    register,
+    unregister,
+    /**
+     * @param {string} client_id
+     */
+    getStore(client_id) {
+      return stores_by_id.get(client_id) || null;
+    },
+    /**
+     * @param {string} client_id
+     * @returns {IssueLite[]}
+     */
+    snapshotFor(client_id) {
+      const s = stores_by_id.get(client_id);
+      return s ? /** @type {IssueLite[]} */ (s.snapshot().slice()) : [];
+    },
+    /**
+     * @param {() => void} fn
+     */
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    }
+    // No recompute helpers in vNext; stores are updated directly via push
+  };
+}