beads-ui 0.1.2 → 0.3.0

package/CHANGES.md

@@ -1,12 +1,39 @@
 # Changes
 
+## 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
+- 🍏 Support `design` in issue details
+- 🍏 Add filter to closed column and improve sorting
+- 🍏 Unblock issue description editing
+- 🍏 CLI: require --open to launch browser, also on restart
+- 🍏 Up/down/left/right keyboard navigation on board
+- 🍏 Up/down keyboard navigation on issues list
+- 🍏 CLI: require --open to launch browser
+- 🍏 Make issue notes editable
+- 🍏 Show toast on disconnect/reconnect
+- 🍏 Support creating a new issue via "New" dialog
+- 🍏 Copy issue IDs to clipboard
+- 🍏 Open issue details in dialog
+- 🐛 Remove --limit 10 when fetching closed issues
+- ✨ Events: coalesce issues-changed to avoid redundant full refresh
+- ✨ Update issues
+- ✨ Align callback function naming
+- 📚 Improve README
+- 📚 Add package description, homepage and repo
+
 ## 0.1.2
 
-- 📦 Specify files to package (Maximilian Antoni)
+- 📦 Specify files to package
 
 ## 0.1.1
 
-- 📚 Make screenshot src absolute and add license (Maximilian Antoni)
+- 📚 Make screenshot src absolute and add license
 
 ## 0.1.0
 

package/README.md

@@ -1,64 +1,63 @@
-# beads-ui
+<h1 align="center">
+  Beads UI
+</h1>
+<p align="center">
+  <b>Local‑first UI for the <code>bd</code> CLI – <a href="https://github.com/steveyegge/beads">Beads</a></b>
+</p>
+<div align="center">
+  <a href="https://www.npmjs.com/package/beads-ui"><img src="https://img.shields.io/npm/v/beads-ui.svg" alt="npm Version"></a>
+  <a href="https://semver.org"><img src="https://img.shields.io/:semver-%E2%9C%93-blue.svg" alt="SemVer"></a>
+  <a href="https://github.com/mantoni/beads-ui/actions/worflows/ci.yml"><img src="https://github.com/mantoni/eslint_d.js/actions/workflows/ci.yml/badge.svg" alt="Build Status"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/npm/l/eslint_d.svg" alt="MIT License"></a>
+  <br>
+  <br>
+</div>
 
-Local‑first UI for the `bd` CLI (beads) — a fast, dependency‑aware issue
-tracker.
+## Features
 
-beads-ui complements the upstream beads project by providing a single‑page web
-app served from a local Node.js server. It talks to `bd` over a local WebSocket
-to list issues, show details, and apply edits. All changes happen by executing
-`bd` commands, and live updates flow in as the database changes on disk.
+- ✨ **Zero setup** – just run `bdui start`
+- 📺 **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
 
-Upstream beads (CLI and docs): https://github.com/steveyegge/beads
+## Setup
 
-## Features
+```sh
+npm i beads-ui -g
+# In the project directory with a beads database:
+bdui start --open
+```
 
-- Issues list with inline edits, quick filters, and keyboard navigation
-- Epics view grouped by epic (from `bd epic status --json`) with expandable rows
-- Board view with Ready / In progress / Closed columns
-- Deep links for navigation; state persists across reloads
-- Live updates via FS watch + WebSocket; optimistic UI with rollbacks on error
-- Dark theme toggle, saved per user
-- Local CLI helper `bdui` to daemonize the server and open your browser
+See `bdui --help` for options.
 
 ## Screenshots
 
-Issues
+**Issues**
 
 ![Issues view](https://github.com/mantoni/beads-ui/raw/main/media/bdui-issues.png)
 
-Epics
+**Epics**
 
 ![Epics view](https://github.com/mantoni/beads-ui/raw/main/media/bdui-epics.png)
 
-Board
+**Board**
 
 ![Board view](https://github.com/mantoni/beads-ui/raw/main/media/bdui-board.png)
 
-## Quickstart
-
-Prerequisites:
-
-- Node.js >= 22
-- `bd` CLI on your PATH (or set `BD_BIN=/path/to/bd`)
-
-Install and start:
-
-```sh
-npm install -g beads-ui
-bdui start
-```
-
-See `bdui --help` for options.
-
-Environment variables:
+## Environment variables
 
+- `BD_BIN`: path to the `bd` binary.
 - `BDUI_RUNTIME_DIR`: override runtime directory for PID/logs. Defaults to
   `$XDG_RUNTIME_DIR/beads-ui` or the system temp dir.
-- `BDUI_NO_OPEN=1`: disable opening the default browser on `start`.
+- `BDUI_NO_OPEN=1`: disable opening the default browser on `start`. Note:
+  Opening the browser is disabled by default; use `--open` to explicitly launch
+  the browser, which overrides this env var.
 - `PORT`: overrides the listen port (default `3000`). The server binds to
   `127.0.0.1`.
 
-Platform notes:
+## Platform notes
 
 - macOS/Linux are fully supported. On Windows, the CLI uses `cmd /c start` to
   open URLs and relies on Node’s `process.kill` semantics for stopping the
@@ -66,13 +65,8 @@ Platform notes:
 
 ## Developer Workflow
 
-- Type check: `npm run typecheck`
-- Tests: `npm test`
-- Lint: `npm run lint`
-- Format: `npm run format`
-
-See `docs/quickstart.md` for details and `docs/architecture.md` for the protocol
-and component overview.
+- 📦 Make sure you have `beads-mcp` installed.
+- 🤖 Ask your agent of choice. It will know.
 
 ## License
 

package/app/data/list-selectors.js

@@ -0,0 +1,98 @@
+/**
+ * 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,129 +1,19 @@
 /**
- * Data layer: typed wrappers around the ws transport for bd-backed queries.
- * @param {(type: import('../protocol.js').MessageType, payload?: unknown) => Promise<unknown>} transport - Request/response function.
- * @param {(type: import('../protocol.js').MessageType, handler: (payload: unknown) => void) => void} [on_event] - Optional event subscription (used to invalidate caches on push updates).
- * @returns {{ getEpicStatus: () => Promise<unknown[]>, getReady: () => 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, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }) => Promise<unknown> }}
+ * @import { MessageType } from '../protocol.js'
  */
-export function createDataLayer(transport, on_event) {
-  /** @type {{ list_ready?: 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 (on_event) {
-    try {
-      on_event('issues-changed', () => {
-        cache.list_ready = 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 /** @type {unknown[]} */ (cache.epic_status);
-    }
-    /** @type {unknown} */
-    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 /** @type {unknown[]} */ (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;
-  }
-
-  /**
-   * Open issues: `bd list -s open --json`.
-   * @returns {Promise<unknown[]>}
-   */
-  async function getOpen() {
-    if (Array.isArray(cache.list_open)) {
-      return /** @type {unknown[]} */ (cache.list_open);
-    }
-    /** @type {unknown} */
-    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 /** @type {unknown[]} */ (cache.list_in_progress);
-    }
-    /** @type {unknown} */
-    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 -s closed -l 10 --json`.
-   * @param {number} [limit] - Optional limit (defaults to 10).
-   * @returns {Promise<unknown[]>}
-   */
-  async function getClosed(limit = 10) {
-    if (limit === 10 && Array.isArray(cache.list_closed_10)) {
-      return /** @type {unknown[]} */ (cache.list_closed_10);
-    }
-    /** @type {unknown} */
-    const res = await transport('list-issues', {
-      filters: { status: 'closed', limit }
-    });
-    const arr = Array.isArray(res) ? res : [];
-    if (limit === 10) {
-      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;
-  }
-
+/**
+ * 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, status, priority, assignee.
+   * Supported fields: title, acceptance, notes, design, status, priority, assignee.
    * Returns the updated issue on success.
-   * @param {{ id: string, title?: string, acceptance?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }} input
+   * @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) {
@@ -144,6 +34,20 @@ export function createDataLayer(transport, on_event) {
         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,
@@ -167,12 +71,6 @@ export function createDataLayer(transport, on_event) {
   }
 
   return {
-    getEpicStatus,
-    getReady,
-    getOpen,
-    getInProgress,
-    getClosed,
-    getIssue,
     updateIssue
   };
 }

package/app/data/sort.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+
+// Sort comparator is centralized in app/data/sort.js
+
+/**
+ * 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;
+    }
+  };
+}