beads-ui 0.1.2 → 0.3.0

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,8 @@
 {
   "name": "beads-ui",
-  "version": "0.1.2",
+  "version": "0.3.0",
+  "description": "Local‑first UI for Beads — a fast issue tracker for your coding agent.",
+  "homepage": "https://github.com/mantoni/beads-ui",
   "type": "module",
   "bin": {
     "bdui": "bin/bdui.js"
@@ -18,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": {
@@ -40,9 +42,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": [
@@ -54,5 +58,9 @@
     "LICENSE",
     "README.md",
     "!**/*.test.js"
-  ]
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mantoni/beads-ui.git"
+  }
 }

package/server/bd.js

@@ -42,14 +42,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));
       });

package/server/cli/commands.js

@@ -19,7 +19,8 @@ import { openUrl, waitForServer } from './open.js';
  * @param {{ no_open?: boolean }} [options]
  */
 export async function handleStart(options) {
-  const no_open = options?.no_open === true;
+  // Default behavior: do not open a browser unless explicitly requested.
+  const no_open = options?.no_open !== false;
   const existing_pid = readPidFile();
   if (existing_pid && isProcessRunning(existing_pid)) {
     printServerUrl();
@@ -35,8 +36,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
@@ -80,12 +80,19 @@ export async function handleStop() {
  * Handle `restart` command: stop (ignore not-running) then start.
  * @returns {Promise<number>} Exit code (0 on success)
  */
-export async function handleRestart() {
+/**
+ * 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>}
+ */
+export async function handleRestart(options) {
   const stop_code = await handleStop();
   // 0 = stopped, 2 = not running; both are acceptable to proceed
   if (stop_code !== 0 && stop_code !== 2) {
     return 1;
   }
-  const start_code = await handleStart();
+  const start_code = await handleStart(options);
   return start_code === 0 ? 0 : 1;
 }

package/server/cli/daemon.js

@@ -1,9 +1,13 @@
+/**
+ * @import { SpawnOptions } from 'node:child_process'
+ */
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getConfig } from '../config.js';
+import { resolveDbPath } from '../db.js';
 
 /**
  * Resolve the runtime directory used for PID and log files.
@@ -12,13 +16,11 @@ import { getConfig } from '../config.js';
  * @returns {string}
  */
 export function getRuntimeDir() {
-  /** @type {string | undefined} */
   const override_dir = process.env.BDUI_RUNTIME_DIR;
   if (override_dir && override_dir.length > 0) {
     return ensureDir(override_dir);
   }
 
-  /** @type {string | undefined} */
   const xdg_dir = process.env.XDG_RUNTIME_DIR;
   if (xdg_dir && xdg_dir.length > 0) {
     return ensureDir(path.join(xdg_dir, 'beads-ui'));
@@ -148,7 +150,7 @@ export function startDaemon() {
     log_fd = -1;
   }
 
-  /** @type {import('node:child_process').SpawnOptions} */
+  /** @type {SpawnOptions} */
   const opts = {
     detached: true,
     env: { ...process.env },
@@ -233,7 +235,12 @@ function sleep(ms) {
  * Print the server URL derived from current config.
  */
 export function printServerUrl() {
-  const cfg = getConfig();
-  const url = 'http://' + cfg.host + ':' + String(cfg.port);
+  const { url } = getConfig();
   console.log(url);
+
+  // Resolve from the caller's working directory by default
+  const resolved_db = resolveDbPath();
+  console.log(
+    `db: ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
+  );
 }

package/server/cli/index.js

@@ -17,6 +17,10 @@ export function parseArgs(args) {
       flags.push('help');
       continue;
     }
+    if (token === '--open') {
+      flags.push('open');
+      continue;
+    }
     if (token === '--no-open') {
       flags.push('no-open');
       continue;
@@ -53,19 +57,44 @@ export async function main(args) {
   }
 
   if (command === 'start') {
-    /** @type {{ no_open: boolean }} */
+    /**
+     * Default behavior: do NOT open a browser.
+     * `--open` explicitly opens, overriding env/config; `--no-open` forces closed.
+     */
     const options = {
-      no_open:
-        flags.includes('no-open') ||
-        String(process.env.BDUI_NO_OPEN || '') === '1'
+      no_open: true
     };
+
+    const has_open = flags.includes('open');
+    const has_no_open = flags.includes('no-open');
+    const env_no_open = String(process.env.BDUI_NO_OPEN || '') === '1';
+
+    if (has_open) {
+      options.no_open = false;
+    } else if (has_no_open) {
+      options.no_open = true;
+    } else if (env_no_open) {
+      options.no_open = true;
+    }
     return await handleStart(options);
   }
   if (command === 'stop') {
     return await handleStop();
   }
   if (command === 'restart') {
-    return await handleRestart();
+    const options = { no_open: true };
+    const has_open = flags.includes('open');
+    const has_no_open = flags.includes('no-open');
+    const env_no_open = String(process.env.BDUI_NO_OPEN || '') === '1';
+
+    if (has_open) {
+      options.no_open = false;
+    } else if (has_no_open) {
+      options.no_open = true;
+    } else if (env_no_open) {
+      options.no_open = true;
+    }
+    return await handleRestart(options);
   }
 
   // Unknown command path (should not happen due to parseArgs guard)

package/server/cli/usage.js

@@ -7,13 +7,13 @@ export function printUsage(out_stream) {
     'Usage: bdui <command> [options]',
     '',
     'Commands:',
-    '  start       Start the UI server (daemonized in later steps)',
+    '  start       Start the UI server',
     '  stop        Stop the UI server',
     '  restart     Restart the UI server',
     '',
     'Options:',
     '  -h, --help   Show this help message',
-    '      --no-open  Do not open the browser on start',
+    '      --open   Open the browser after start/restart',
     ''
   ];
   for (const line of lines) {

package/server/config.js

@@ -3,27 +3,33 @@ import { fileURLToPath } from 'node:url';
 
 /**
  * Resolve runtime configuration for the server.
- * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string }}
+ * Notes:
+ * - `app_dir` is resolved relative to the installed package location.
+ * - `root_dir` represents the directory where the process was invoked
+ *   (i.e., the current working directory) so DB resolution follows the
+ *   caller's context rather than the install location.
+ * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string, url: string }}
  */
 export function getConfig() {
   const this_file = fileURLToPath(new URL(import.meta.url));
   const server_dir = path.dirname(this_file);
-  const root_dir = path.resolve(server_dir, '..');
+  const package_root = path.resolve(server_dir, '..');
+  // Always reflect the directory from which the process was started
+  const root_dir = process.cwd();
 
-  /** @type {number} */
   let port_value = Number.parseInt(process.env.PORT || '', 10);
   if (!Number.isFinite(port_value)) {
     port_value = 3000;
   }
 
-  /** @type {string} */
   const host_value = '127.0.0.1';
 
   return {
     host: host_value,
     port: port_value,
     env: process.env.NODE_ENV ? String(process.env.NODE_ENV) : 'development',
-    app_dir: path.resolve(root_dir, 'app'),
-    root_dir
+    app_dir: path.resolve(package_root, 'app'),
+    root_dir,
+    url: `http://${host_value}:${port_value}`
   };
 }

package/server/db.js

@@ -58,7 +58,6 @@ export function findNearestBeadsDb(start) {
     const beadsDir = path.join(dir, '.beads');
     try {
       const entries = fs.readdirSync(beadsDir, { withFileTypes: true });
-      /** @type {string[]} */
       const dbs = entries
         .filter((e) => e.isFile() && e.name.endsWith('.db'))
         .map((e) => e.name)

package/server/index.js

@@ -7,14 +7,18 @@ import { attachWsServer } from './ws.js';
 const config = getConfig();
 const app = createApp(config);
 const server = createServer(app);
-const { notifyIssuesChanged } = attachWsServer(server, {
+const { scheduleListRefresh } = attachWsServer(server, {
   path: '/ws',
-  heartbeat_ms: 30000
+  heartbeat_ms: 30000,
+  // Coalesce DB change bursts into one refresh run
+  refresh_debounce_ms: 75
 });
 
-// Watch the active beads DB and push invalidation (targeted when possible)
-watchDb(config.root_dir, (payload) => {
-  notifyIssuesChanged(payload);
+// Watch the active beads DB and schedule subscription refresh for active lists
+watchDb(config.root_dir, () => {
+  // Schedule subscription list refresh run for active subscriptions
+  scheduleListRefresh();
+  // v2: all updates flow via subscription push envelopes only
 });
 
 server.listen(config.port, config.host, () => {