beads-ui 0.2.0 → 0.3.1

package/docs/data-exchange-subscription-plan.md

@@ -0,0 +1,198 @@
+# Data Exchange Model — Subscription‑Based Updates (Full‑Issue)
+
+```
+Date: 2025-10-25
+Status: Implemented
+Owner: agent
+```
+
+## Goals
+
+- Replace ad-hoc list fetching with subscription-based incremental updates.
+- Minimize complexity; send full‑issue payloads in envelopes targeted to a
+  specific subscription key.
+- Ensure consistent, race-free updates around user-triggered mutations.
+- Keep UI models per-subscription to simplify rendering and memory usage.
+
+## Scope
+
+- Server and client for `beads-ui`.
+- Uses `bd` CLI for data access; no DB schema changes.
+
+## Subscription Types
+
+- `all-issues`
+- `epics` // Removed: `issues-for-epic` (use `issue-detail` for the epic and
+  render its `dependents`)
+- `blocked-issues`
+- `ready-issues`
+- `in-progress-issues`
+- `closed-issues` (special filtering noted below)
+
+## Server Architecture
+
+### Subscription Registry (Issue List Subscriptions)
+
+- Keyed by `subscriptionKey = type + JSON.stringify(params)`.
+- Value:
+  `{ itemsById: Map<string, { updated_at: string, closed_at: string|null }>, subscribers: Set<SubscriberId>, lastRunAt?: number }`.
+- Each subscribe request either attaches to an existing registry entry or
+  creates a new one.
+- No TTL: subscriptions are evicted only on WebSocket disconnect. Unsubscribe
+  removes a subscriber from the set but keeps the registry entry until the
+  connection closes.
+
+### Mapping to `bd` Commands
+
+- `all-issues` → `bd list` (default/open)
+- `epics` → `bd list --type epic` (or equivalent)
+- `detail:{id}` → `bd show <id> --json` (use `dependents` from the epic detail
+  for children)
+- `blocked-issues` → `bd list --blocked`
+- `ready-issues` → `bd ready --limit 1000`
+- `in-progress-issues` → `bd list --status in_progress`
+- `closed-issues` → `bd list --status closed` (then filter first; see Special
+  Cases)
+
+Notes:
+
+- Exact flags depend on `bd`; create adapters that encapsulate CLI details and
+  normalize results.
+
+### Refresh Algorithm (per run)
+
+1. Execute mapped `bd` command to get the full list of `issues` for the spec.
+2. If subscription is `closed-issues` with a filter, apply it before step 3.
+3. Compare with the registry’s last known items for this subscription key.
+4. For new or changed items, emit `upsert` envelopes with the full issue payload
+   to all subscribers of the key on the current connection.
+5. For removed items, emit `delete` envelopes with `issue_id`.
+6. Update the registry’s state for the key.
+
+### Special Case: Closed Issues Filtering
+
+- Apply `since` filter (epoch milliseconds) before diffing to avoid spurious
+  updates when reloading older closed items. Only items with
+  `closed_at >= since` are included. Invalid or non-positive `since` values are
+  ignored.
+- Filters are part of subscription params to keep deterministic diffing.
+
+### Migration
+
+This change replaces request/response list reads and id‑only deltas with
+subscription‑based, full‑issue push envelopes.
+
+Client migration steps:
+
+- Replace list fetch calls with `subscribe-list`/`unsubscribe-list` messages.
+- Maintain a per‑subscription local store keyed by the client `id`.
+- Apply `snapshot`/`upsert`/`delete` envelopes in revision order; render from
+  `store.snapshot()`.
+- Remove any legacy polling timers; updates now arrive via server push.
+- For closed issue feeds, pass a `params.since` value (epoch ms) that reflects
+  the UI’s filter horizon if needed server‑side.
+
+### Watcher Integration (DB Updates)
+
+- A file/DB watcher signals any data change.
+- On signal, for each active subscription: re-run its mapped `bd` command → diff
+  → push deltas to all subscribers.
+- Backpressure: coalesce multiple watcher events into a single run per
+  subscription (leading-edge, with trailing-edge within 50–100ms).
+
+### User Mutations (Race Control)
+
+When client requests a change (e.g., update status):
+
+1. Execute the explicit protocol mutation (mapped to a concrete `bd` command
+   under the hood; no arbitrary commands allowed).
+2. In parallel, attach a once-listener to the watcher that resolves on the next
+   change event (no debounce) or a 500ms timeout, whichever occurs first.
+3. After the promise resolves, for each affected subscription, run the standard
+   refresh/diff/push routine exactly once.
+4. During the pending mutation window, suppress watcher-triggered refreshes for
+   affected subscriptions to avoid duplicate pushes.
+
+### Error Handling
+
+- Validate subscription params; return structured errors.
+- For `bd` failures, include stderr and exit code; do not crash subscriptions.
+- If a subscriber disconnects mid-push, drop silently and clean up.
+
+## Client Architecture
+
+### Local Store per Subscription
+
+- Keyed by `subscriptionKey`.
+- Value: `{ itemsById: Map<string, Issue>, lastAppliedAt: number }`.
+- On `{ added, updated, removed }`, update `itemsById` accordingly and request
+  view re-render.
+- Tabs and epic expansion toggle subscribe/unsubscribe appropriately.
+
+### UI Flow
+
+- Tab switch: unsubscribe previous, subscribe new.
+- Epic toggle: subscribe/unsubscribe `detail:{id}` with
+  `{ type: 'issue-detail', params: { id } }`.
+- Components derive view state from the local store snapshot.
+
+## Wire Protocol (vNext)
+
+### Messages: Client → Server
+
+- `subscribe-list` `{ id: string, type: string, params?: object }`
+- `unsubscribe-list` `{ id: string }`
+- Explicit mutation messages (enumerated in the protocol; no generic command
+  pipe). The set mirrors the main protocol (update-status, edit-text,
+  update-priority, update-assignee, create-issue, dep-add/remove,
+  label-add/remove).
+
+### Messages: Server → Client (Per‑Subscription)
+
+All envelopes include a per‑subscription `revision` (monotonic, starting at 1),
+and the client subscription `id`.
+
+- `snapshot` `{ id, schema, revision, issues: Issue[] }`
+- `upsert` `{ id, schema, revision, issue: Issue }`
+- `delete` `{ id, schema, revision, issue_id: string }`
+
+Notes
+
+- Initial subscribe triggers a single `snapshot` for the requesting `id` only.
+- Subsequent refresh runs emit `upsert`/`delete` events to all subscribers of
+  the same subscription key on that connection.
+- Clients MUST apply envelopes in `revision` order and ignore stale revisions.
+
+## Concurrency & Ordering Guarantees
+
+- Per-subscription ordering: server serializes diff runs per key.
+- Deltas are applied in order on the client; no interleaving for a given `id`.
+- Mutations provide “eventually up-to-date” guarantee via the once-listener +
+  timeout.
+
+## Observability
+
+- Basic development logging only; no telemetry collection for message rates.
+
+## Security
+
+- Only explicit mutation operations are implemented by the protocol; no
+  arbitrary commands from clients.
+- Reject unknown subscription types; enforce param schemas.
+
+## Testing Strategy
+
+- Unit: diffing, registry, adapter mapping, filter logic.
+- Integration: watcher → refresh → push flow; mutation window once-only
+  behavior.
+- E2E: tab switching, epic expansion, status changes while updates stream.
+
+## Release Notes
+
+- Breaking change: Clients must adopt `snapshot`/`upsert`/`delete` envelopes and
+  per‑subscription stores. Previous polling and id‑only list deltas are removed.
+
+## Open Questions
+
+- Exact `bd` flags for each list type; confirm and codify.
+- Closed-issue filter semantics (date range vs. other criteria).

package/docs/db-watching.md

@@ -1,7 +1,8 @@
 # DB Watching and Resolution
 
 The server watches the active beads SQLite database file for changes and
-broadcasts an `issues-changed` event to connected clients.
+schedules a refresh of active list subscriptions. Clients receive
+`snapshot`/`upsert`/`delete` envelopes for their active subscriptions.
 
 ## Resolution Order
 

package/docs/migration-v2.md

@@ -0,0 +1,54 @@
+# Migration: Push‑Only Per‑Subscription Stores (Breaking)
+
+```
+Date: 2025-10-26
+Status: Final
+Owner: agent
+```
+
+This release replaces legacy list reads and id‑only list deltas with
+per‑subscription push envelopes that carry full issue payloads. There is no
+compatibility mode and no feature flags.
+
+## Required Versions
+
+- beads‑ui: 0.2.0 or later (includes the server)
+- Node.js: >= 22 (see `package.json` engines)
+
+Upgrade:
+
+```sh
+npm i -g beads-ui@latest
+```
+
+## What Changed
+
+- New protocol: `snapshot` / `upsert` / `delete` envelopes and a
+  per‑subscription `revision`.
+- One store per list: views render from a `SubscriptionIssueStore` created for
+  each active subscription id.
+- Removed: central issues store and delta fan‑out.
+- Removed: legacy read RPCs `list-issues` and `epic-status`.
+
+## Migration Checklist
+
+- Replace list reads with `subscribe-list`/`unsubscribe-list`.
+- Create a `SubscriptionIssueStore` at view mount and wire the WS client to call
+  `store.applyPush(payload)` for `snapshot`/`upsert`/`delete`.
+- Render from `store.snapshot()`; remove code paths that read from a central
+  issue cache.
+- Delete dead selectors/helpers that depended on the central cache.
+- Verify reconnect flows: a fresh `snapshot` (rev 1) replaces state cleanly.
+
+## Notes
+
+- No telemetry or phased rollout was implemented; ensure the UI and server are
+  updated together. Older clients will not function with the new server.
+- For closed‑issues feeds, prefer passing a `since` param where applicable to
+  keep snapshots small.
+
+## References
+
+- `docs/protocol/issues-push-v2.md`
+- `docs/subscription-issue-store.md`
+- ADR 002 — Per‑Subscription Stores and Full‑Issue Push

package/docs/protocol/issues-push-v2.md

@@ -0,0 +1,179 @@
+# Subscription Push Protocol — per‑subscription full‑issue envelopes (Breaking)
+
+```
+Date: 2025-10-26
+Status: Implemented
+Owner: agent
+```
+
+This document specifies the push‑only protocol used by beads‑ui to deliver list
+updates from the local server to the client. It replaces the legacy
+notify‑then‑fetch model. There is no version negotiation or fallback.
+
+## Overview
+
+- Transport: single WebSocket connection per client
+- Encoding: JSON text frames
+- Subscriptions: one client‑chosen `id` per active list subscription
+- Delivery: per‑subscription envelopes with full issue payloads
+- Messages: `snapshot` | `upsert` | `delete`
+- Ordering: strictly increasing `revision` per subscription key and connection
+
+## Envelopes
+
+```ts
+export type SnapshotEnvelope = {
+  type: 'snapshot';
+  id: string; // client subscription id
+  revision: number; // starts at 1 and increments per envelope
+  issues: Issue[]; // full list for this subscription
+};
+
+export type UpsertEnvelope = {
+  type: 'upsert';
+  id: string;
+  revision: number;
+  issue: Issue; // full issue payload
+};
+
+export type DeleteEnvelope = {
+  type: 'delete';
+  id: string;
+  revision: number;
+  issue_id: string; // id only
+};
+```
+
+Notes
+
+- Server serializes refresh runs per subscription key and emits envelopes in
+  `revision` order. Clients MUST ignore any envelope with `revision <=` the last
+  applied for the same `id`.
+- Clients SHOULD treat `upsert` as idempotent and MAY additionally guard on an
+  `issue.updated_at` timestamp to ignore stale updates racing with local state.
+
+## Handshake (subscribe‑list)
+
+Client subscribes to a list with a chosen `id`, a `type`, and optional `params`.
+
+Client → Server
+
+```json
+{
+  "id": "req-1",
+  "type": "subscribe-list",
+  "payload": { "id": "ready", "type": "ready-issues" }
+}
+```
+
+Server → Client
+
+```json
+{
+  "id": "req-1",
+  "ok": true,
+  "type": "subscribe-list",
+  "payload": { "id": "ready", "key": "ready-issues:{}" }
+}
+```
+
+Immediately after the ack, the server sends a `snapshot` envelope containing the
+full list for that subscription `id` with `revision: 1`.
+
+```json
+{
+  "id": "evt-1730000000000",
+  "ok": true,
+  "type": "snapshot",
+  "payload": {
+    "type": "snapshot",
+    "id": "ready",
+    "revision": 1,
+    "issues": [{ "id": "UI-1", "title": "..." }]
+  }
+}
+```
+
+## Updates
+
+Subsequent refreshes emit `upsert` and `delete` envelopes as the list changes.
+
+```json
+{
+  "id": "evt-1730000000100",
+  "ok": true,
+  "type": "upsert",
+  "payload": {
+    "type": "upsert",
+    "id": "ready",
+    "revision": 2,
+    "issue": { "id": "UI-2", "status": "in_progress" }
+  }
+}
+```
+
+```json
+{
+  "id": "evt-1730000000200",
+  "ok": true,
+  "type": "delete",
+  "payload": {
+    "type": "delete",
+    "id": "ready",
+    "revision": 3,
+    "issue_id": "UI-9"
+  }
+}
+```
+
+## Reconnect Behavior
+
+- On reconnect, clients resubscribe using the same `id` values as needed. The
+  server treats this as a new connection and sends a fresh `snapshot` with
+  `revision: 1` for each active subscription.
+
+## Diagrams
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant S as Server
+  C->>S: subscribe-list { id, type, params }
+  S-->>C: ack { id, key }
+  S-->>C: snapshot { id, schema, revision:1, issues:[...] }
+  S-->>C: upsert/delete { id, schema, revision:n, ... }
+```
+
+```mermaid
+stateDiagram-v2
+  [*] --> Idle
+  Idle --> Subscribed: subscribe-list(id)
+  Subscribed --> Subscribed: snapshot(rev=1)
+  Subscribed --> Subscribed: upsert/delete(rev++)
+  Subscribed --> Idle: unsubscribe-list(id) / disconnect
+```
+
+## Client Responsibilities
+
+- Maintain one `SubscriptionIssueStore` per active subscription `id`.
+- Apply envelopes strictly in `revision` order; ignore stale revisions.
+- Render list components from `store.snapshot()` (deterministic order).
+- Dispose stores on route/tab changes.
+
+Detail view
+
+- Detail pages use the same mechanism with a single‑item subscription, e.g.
+  `{ type: 'issue-detail', params: { id: 'UI-1' } }` under a client id like
+  `detail:UI-1`. The server returns a one‑element list for `snapshot` and
+  `upsert` events.
+
+## Rollout and Compatibility
+
+- Breaking change: no flags and no compatibility layer with the legacy
+  notify‑then‑fetch flow. Update both client and server together.
+
+## See Also
+
+- ADR 002 — Per‑Subscription Stores and Full‑Issue Push
+- `docs/data-exchange-subscription-plan.md` (server refresh and publish model)
+- `docs/subscription-issue-store.md` (store API and usage examples)

package/docs/subscription-issue-store.md

@@ -0,0 +1,112 @@
+# SubscriptionIssueStore — API and Usage Examples
+
+```
+Date: 2025-10-26
+Status: Implemented
+Owner: agent
+```
+
+The `SubscriptionIssueStore` is a per‑subscription in‑memory store that owns the
+issues for a single list subscription. It applies server push envelopes
+(`snapshot`/`upsert`/`delete`) in revision order and exposes a deterministic,
+read‑only snapshot for rendering.
+
+See also: `docs/protocol/issues-push-v2.md` for the wire protocol.
+
+## API
+
+Factory: `app/data/subscription-issue-store.js`
+
+```js
+import { createSubscriptionIssueStore } from '../app/data/subscription-issue-store.js';
+
+// Create at view mount (id is client-chosen)
+const store = createSubscriptionIssueStore('ready');
+
+// Listen for changes
+const unsubscribe = store.subscribe(() => {
+  render(store.snapshot());
+});
+
+// Apply push envelopes from the WebSocket client
+ws.on('message', (evt) => {
+  const msg = JSON.parse(evt.data);
+  if (msg && msg.ok === true && msg.payload && msg.payload.id === 'ready') {
+    // payload has { type, id, schema, revision, ... }
+    store.applyPush(msg.payload);
+  }
+});
+
+// Read helpers
+store.size(); // number of issues
+store.getById('UI-1'); // lookup by id
+
+// Dispose on unmount
+unsubscribe();
+store.dispose();
+```
+
+Options: deterministic sort can be customized per list via the optional
+`{ sort(a,b) }` parameter when constructing the store.
+
+## Subscribing to a List
+
+Pair store creation with the subscribe‑list handshake. The server will send a
+`snapshot` immediately after the ack, followed by `upsert`/`delete`.
+
+```js
+// Request a subscription
+socket.send(
+  JSON.stringify({
+    id: 'req-1',
+    type: 'subscribe-list',
+    payload: { id: 'ready', type: 'ready-issues' }
+  })
+);
+
+socket.addEventListener('message', (ev) => {
+  const frame = JSON.parse(ev.data);
+  if (frame.ok && frame.type === 'snapshot' && frame.payload.id === 'ready') {
+    store.applyPush(frame.payload);
+  }
+  if (frame.ok && frame.type === 'upsert' && frame.payload.id === 'ready') {
+    store.applyPush(frame.payload);
+  }
+  if (frame.ok && frame.type === 'delete' && frame.payload.id === 'ready') {
+    store.applyPush(frame.payload);
+  }
+});
+```
+
+## Rendering Pattern (List component)
+
+```js
+/** @param {{ store: ReturnType<typeof createSubscriptionIssueStore> }} props */
+export function ListView({ store }) {
+  let items = store.snapshot();
+
+  const un = store.subscribe(() => {
+    items = store.snapshot();
+    requestRender();
+  });
+
+  // framework-specific teardown
+  onUnmount(() => un());
+
+  return html`<ul>
+    ${items.map((it) => html`<li data-id=${it.id}>${it.title}</li>`)}
+  </ul>`;
+}
+```
+
+## Ordering and Identity
+
+- Default sort: priority asc, then `created_at` desc, then id asc.
+- When upserting, the store preserves object identity for existing ids by
+  mutating fields in place. This reduces unnecessary re‑renders.
+
+## Reconnects
+
+- On reconnect, repeat the subscribe‑list call. The server sends a fresh
+  `snapshot` with `revision: 1`. The store ignores stale envelopes using the
+  `revision` guard.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beads-ui",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
   "homepage": "https://github.com/mantoni/beads-ui",
   "type": "module",
@@ -20,7 +20,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "preversion": "npm run all",
-    "version": "changes",
+    "version": "changes --commits --footer",
     "postversion": "git push --follow-tags && npm publish"
   },
   "devDependencies": {
@@ -32,9 +32,8 @@
     "@types/ws": "^8.18.1",
     "eslint": "^9.11.0",
     "eslint-plugin-import": "^2.29.1",
-    "eslint-plugin-jsdoc": "^48.10.2",
+    "eslint-plugin-jsdoc": "^61.1.9",
     "eslint-plugin-n": "^17.9.0",
-    "eslint-plugin-promise": "^6.1.1",
     "globals": "^16.4.0",
     "jsdom": "^27.0.1",
     "prettier": "^3.3.3",
@@ -42,9 +41,11 @@
     "vitest": "^2.1.3"
   },
   "dependencies": {
+    "dompurify": "^3.3.0",
     "esbuild": "^0.25.11",
     "express": "^5.1.0",
     "lit-html": "^3.3.1",
+    "marked": "^16.4.1",
     "ws": "^8.18.3"
   },
   "files": [

package/server/app.js

@@ -6,6 +6,7 @@ import path from 'node:path';
 
 /**
  * Create and configure the Express application.
+ *
  * @param {{ host: string, port: number, env: string, app_dir: string, root_dir: string }} config - Server configuration.
  * @returns {Express} Configured Express app instance.
  */
@@ -28,6 +29,7 @@ export function createApp(config) {
   /**
    * On-demand bundle for the browser using esbuild.
    * Note: esbuild is loaded lazily so tests don't require it to be installed.
+   *
    * @param {Request} _req
    * @param {Response} res
    */

package/server/bd.js

@@ -3,6 +3,7 @@ import { resolveDbPath } from './db.js';
 
 /**
  * Resolve the bd executable path.
+ *
  * @returns {string}
  */
 export function getBdBin() {
@@ -16,6 +17,7 @@ export function getBdBin() {
 /**
  * Run the `bd` CLI with provided arguments.
  * Shell is not used to avoid injection; args must be pre-split.
+ *
  * @param {string[]} args - Arguments to pass (e.g., ["list", "--json"]).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
@@ -42,14 +44,12 @@ export function runBd(args, options = {}) {
 
     if (child.stdout) {
       child.stdout.setEncoding('utf8');
-      /** @param {string} chunk */
       child.stdout.on('data', (chunk) => {
         out_chunks.push(String(chunk));
       });
     }
     if (child.stderr) {
       child.stderr.setEncoding('utf8');
-      /** @param {string} chunk */
       child.stderr.on('data', (chunk) => {
         err_chunks.push(String(chunk));
       });
@@ -90,6 +90,7 @@ export function runBd(args, options = {}) {
 
 /**
  * Run `bd` and parse JSON from stdout if exit code is 0.
+ *
  * @param {string[]} args - Must include flags that cause JSON to be printed (e.g., `--json`).
  * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
  * @returns {Promise<{ code: number, stdoutJson?: unknown, stderr?: string }>}
@@ -111,6 +112,7 @@ export async function runBdJson(args, options = {}) {
 
 /**
  * Add a resolved "--db <path>" pair to args when none present.
+ *
  * @param {string[]} args
  * @param {string} cwd
  * @param {Record<string, string | undefined>} env

package/server/cli/commands.js

@@ -13,6 +13,7 @@ import { openUrl, waitForServer } from './open.js';
  * Handle `start` command. Idempotent when already running.
  * - Spawns a detached server process, writes PID file, returns 0.
  * - If already running (PID file present and process alive), prints URL and returns 0.
+ *
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
@@ -36,8 +37,7 @@ export async function handleStart(options) {
     printServerUrl();
     // Auto-open the browser once for a fresh daemon start
     if (!no_open) {
-      const cfg = getConfig();
-      const url = 'http://' + cfg.host + ':' + String(cfg.port);
+      const { url } = getConfig();
       // Wait briefly for the server to accept connections (single retry window)
       await waitForServer(url, 600);
       // Best-effort open; ignore result
@@ -53,6 +53,7 @@ export async function handleStart(options) {
  * Handle `stop` command.
  * - Sends SIGTERM and waits for exit (with SIGKILL fallback), removes PID file.
  * - Returns 2 if not running.
+ *
  * @returns {Promise<number>} Exit code
  */
 export async function handleStop() {
@@ -79,12 +80,14 @@ export async function handleStop() {
 
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
+ *
  * @returns {Promise<number>} Exit code (0 on success)
  */
 /**
  * Handle `restart` command: stop (ignore not-running) then start.
  * Accepts the same options as `handleStart` and passes them through,
  * so restart only opens a browser when `no_open` is explicitly false.
+ *
  * @param {{ no_open?: boolean }} [options]
  * @returns {Promise<number>}
  */