beads-ui 0.1.0

package/app/ws.js

@@ -0,0 +1,252 @@
+/* global Console */
+/**
+ * @import { MessageType } from './protocol.js'
+ */
+/**
+ * Persistent WebSocket client with reconnect, request/response correlation,
+ * and simple event dispatching.
+ *
+ * Usage:
+ *   const ws = createWsClient();
+ *   const data = await ws.send('list-issues', { filters: {} });
+ *   const off = ws.on('issues-changed', (payload) => { ... });
+ */
+import { MESSAGE_TYPES, makeRequest, nextId } from './protocol.js';
+
+/**
+ * @typedef {'connecting'|'open'|'closed'|'reconnecting'} ConnectionState
+ */
+
+/**
+ * @typedef {{ initialMs?: number, maxMs?: number, factor?: number, jitterRatio?: number }} BackoffOptions
+ */
+
+/**
+ * @typedef {{ url?: string, backoff?: BackoffOptions, logger?: Console }} ClientOptions
+ */
+
+/**
+ * Create a WebSocket client with auto-reconnect and message correlation.
+ * @param {ClientOptions} [options]
+ */
+export function createWsClient(options = {}) {
+  /** @type {Console} */
+  const logger = options.logger || console;
+
+  /** @type {BackoffOptions} */
+  const backoff = {
+    initialMs: options.backoff?.initialMs ?? 1000,
+    maxMs: options.backoff?.maxMs ?? 30000,
+    factor: options.backoff?.factor ?? 2,
+    jitterRatio: options.backoff?.jitterRatio ?? 0.2
+  };
+
+  /** @type {() => string} */
+  const resolveUrl = () => {
+    if (options.url && options.url.length > 0) {
+      return options.url;
+    }
+    if (typeof location !== 'undefined') {
+      return (
+        (location.protocol === 'https:' ? 'wss://' : 'ws://') +
+        location.host +
+        '/ws'
+      );
+    }
+    return 'ws://localhost/ws';
+  };
+
+  /** @type {WebSocket | null} */
+  let ws = null;
+  /** @type {ConnectionState} */
+  let state = 'closed';
+  /** @type {number} */
+  let attempts = 0;
+  /** @type {ReturnType<typeof setTimeout> | null} */
+  let reconnect_timer = null;
+  /** @type {boolean} */
+  let should_reconnect = true;
+
+  /** @type {Map<string, { resolve: (v: any) => void, reject: (e: any) => void, type: string }>} */
+  const pending = new Map();
+  /** @type {Array<ReturnType<typeof makeRequest>>} */
+  const queue = [];
+  /** @type {Map<string, Set<(payload: any) => void>>} */
+  const handlers = new Map();
+
+  function scheduleReconnect() {
+    if (!should_reconnect || reconnect_timer) {
+      return;
+    }
+    state = 'reconnecting';
+    const base = Math.min(
+      backoff.maxMs || 0,
+      (backoff.initialMs || 0) * Math.pow(backoff.factor || 1, attempts)
+    );
+    const jitter = (backoff.jitterRatio || 0) * base;
+    const delay = Math.max(
+      0,
+      Math.round(base + (Math.random() * 2 - 1) * jitter)
+    );
+    reconnect_timer = setTimeout(() => {
+      reconnect_timer = null;
+      connect();
+    }, delay);
+  }
+
+  /** @param {ReturnType<typeof makeRequest>} req */
+  function sendRaw(req) {
+    try {
+      ws?.send(JSON.stringify(req));
+    } catch (err) {
+      logger.error('ws send failed', err);
+    }
+  }
+
+  function onOpen() {
+    state = 'open';
+    attempts = 0;
+    // subscribe first
+    sendRaw(makeRequest('subscribe-updates', {}));
+    // flush queue
+    while (queue.length) {
+      const req = queue.shift();
+      if (req) {
+        sendRaw(req);
+      }
+    }
+  }
+
+  /** @param {MessageEvent} ev */
+  function onMessage(ev) {
+    /** @type {any} */
+    let msg;
+    try {
+      msg = JSON.parse(String(ev.data));
+    } catch {
+      logger.warn('ws received non-JSON message');
+      return;
+    }
+    if (!msg || typeof msg.id !== 'string' || typeof msg.type !== 'string') {
+      logger.warn('ws received invalid envelope');
+      return;
+    }
+
+    if (pending.has(msg.id)) {
+      const entry = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.ok) {
+        entry?.resolve(msg.payload);
+      } else {
+        entry?.reject(msg.error || new Error('ws error'));
+      }
+      return;
+    }
+
+    // Treat as server-initiated event
+    const set = handlers.get(msg.type);
+    if (set && set.size > 0) {
+      for (const fn of Array.from(set)) {
+        try {
+          fn(msg.payload);
+        } catch (err) {
+          logger.error('ws event handler error', err);
+        }
+      }
+    } else {
+      logger.warn(`ws received unhandled message type: ${msg.type}`);
+    }
+  }
+
+  function onClose() {
+    state = 'closed';
+    // fail all pending
+    for (const [id, p] of pending.entries()) {
+      p.reject(new Error('ws disconnected'));
+      pending.delete(id);
+    }
+    attempts += 1;
+    scheduleReconnect();
+  }
+
+  function connect() {
+    if (!should_reconnect) {
+      return;
+    }
+    const url = resolveUrl();
+    try {
+      ws = /** @type {any} */ (new WebSocket(url));
+      state = 'connecting';
+      const s = /** @type {any} */ (ws);
+      s.addEventListener('open', onOpen);
+      s.addEventListener('message', onMessage);
+      s.addEventListener('error', () => {
+        // let close handler handle reconnect
+      });
+      s.addEventListener('close', onClose);
+    } catch (err) {
+      logger.error('ws connect failed', err);
+      scheduleReconnect();
+    }
+  }
+
+  connect();
+
+  return {
+    /**
+     * Send a request and await its correlated reply payload.
+     * @param {MessageType} type
+     * @param {unknown} [payload]
+     * @returns {Promise<any>}
+     */
+    send(type, payload) {
+      if (!MESSAGE_TYPES.includes(type)) {
+        return Promise.reject(new Error(`unknown message type: ${type}`));
+      }
+      const id = nextId();
+      const req = makeRequest(type, payload, id);
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject, type });
+        if (ws && ws.readyState === ws.OPEN) {
+          sendRaw(req);
+        } else {
+          queue.push(req);
+        }
+      });
+    },
+    /**
+     * Register a handler for a server-initiated event type.
+     * Returns an unsubscribe function.
+     * @param {MessageType} type
+     * @param {(payload: any) => void} handler
+     * @returns {() => void}
+     */
+    on(type, handler) {
+      if (!handlers.has(type)) {
+        handlers.set(type, new Set());
+      }
+      const set = handlers.get(type);
+      set?.add(handler);
+      return () => {
+        set?.delete(handler);
+      };
+    },
+    /** Close and stop reconnecting. */
+    close() {
+      should_reconnect = false;
+      if (reconnect_timer) {
+        clearTimeout(reconnect_timer);
+        reconnect_timer = null;
+      }
+      try {
+        ws?.close();
+      } catch {
+        /* ignore */
+      }
+    },
+    /** For diagnostics in tests or UI. */
+    getState() {
+      return state;
+    }
+  };
+}

package/app/ws.test.js

@@ -0,0 +1,168 @@
+import { describe, expect, test, vi } from 'vitest';
+import { createWsClient } from './ws.js';
+
+/**
+ * @returns {any[]}
+ */
+function setupFakeWebSocket() {
+  /** @type {any[]} */
+  const sockets = [];
+  class FakeWebSocket {
+    /** @param {string} url */
+    constructor(url) {
+      this.url = url;
+      this.readyState = 0; // CONNECTING
+      this.OPEN = 1;
+      this.CLOSING = 2;
+      this.CLOSED = 3;
+      /** @type {{ open: Array<(ev:any)=>void>, message: Array<(ev:any)=>void>, error: Array<(ev:any)=>void>, close: Array<(ev:any)=>void> }} */
+      this._listeners = { open: [], message: [], error: [], close: [] };
+      /** @type {string[]} */
+      this.sent = [];
+      sockets.push(this);
+    }
+    /**
+     * @param {'open'|'message'|'error'|'close'} type
+     * @param {(ev:any)=>void} fn
+     */
+    addEventListener(type, fn) {
+      this._listeners[type].push(fn);
+    }
+    /**
+     * @param {'open'|'message'|'error'|'close'} type
+     * @param {(ev:any)=>void} fn
+     */
+    removeEventListener(type, fn) {
+      const a = this._listeners[type];
+      const i = a.indexOf(fn);
+      if (i !== -1) {
+        a.splice(i, 1);
+      }
+    }
+    /**
+     * @param {'open'|'message'|'error'|'close'} type
+     * @param {any} ev
+     */
+    _dispatch(type, ev) {
+      for (const fn of this._listeners[type]) {
+        try {
+          fn(ev);
+        } catch {
+          // ignore
+        }
+      }
+    }
+    openNow() {
+      this.readyState = this.OPEN;
+      this._dispatch('open', {});
+    }
+    /** @param {string} data */
+    send(data) {
+      this.sent.push(String(data));
+    }
+    /** @param {any} obj */
+    emitMessage(obj) {
+      this._dispatch('message', { data: JSON.stringify(obj) });
+    }
+    close() {
+      this.readyState = this.CLOSED;
+      this._dispatch('close', {});
+    }
+  }
+  vi.stubGlobal('WebSocket', FakeWebSocket);
+  return sockets;
+}
+
+describe('app/ws client', () => {
+  test('correlates replies for concurrent sends', async () => {
+    const sockets = setupFakeWebSocket();
+    const client = createWsClient({
+      backoff: { initialMs: 5, maxMs: 5, jitterRatio: 0 }
+    });
+    // open connection
+    sockets[0].openNow();
+
+    const p1 = client.send('list-issues', { filters: {} });
+    const p2 = client.send('show-issue', { id: 'UI-1' });
+
+    // Parse the last two frames to extract ids
+    const frames = sockets[0].sent
+      .slice(-2)
+      .map((/** @type {string} */ s) => JSON.parse(s));
+    const id1 = frames[0].id;
+    const id2 = frames[1].id;
+
+    // Reply out of order
+    sockets[0].emitMessage({
+      id: id2,
+      ok: true,
+      type: 'show-issue',
+      payload: { id: 'UI-1' }
+    });
+    sockets[0].emitMessage({
+      id: id1,
+      ok: true,
+      type: 'list-issues',
+      payload: [{ id: 'UI-1' }]
+    });
+
+    await expect(p2).resolves.toEqual({ id: 'UI-1' });
+    await expect(p1).resolves.toEqual([{ id: 'UI-1' }]);
+  });
+
+  test('reconnects and resubscribes after close', async () => {
+    vi.useFakeTimers();
+    const sockets = setupFakeWebSocket();
+    const client = createWsClient({
+      backoff: { initialMs: 10, maxMs: 10, jitterRatio: 0 }
+    });
+
+    // First connection opens
+    sockets[0].openNow();
+    // subscribe-updates should be first frame
+    const firstFrame = JSON.parse(sockets[0].sent[0]);
+    expect(firstFrame.type).toBe('subscribe-updates');
+
+    // Close the socket to trigger reconnect
+    sockets[0].close();
+    // Advance timers for reconnect
+    await vi.advanceTimersByTimeAsync(10);
+
+    // Second socket should exist and open
+    expect(sockets.length).toBeGreaterThan(1);
+    sockets[1].openNow();
+    const sub = JSON.parse(sockets[1].sent[0]);
+    expect(sub.type).toBe('subscribe-updates');
+
+    vi.useRealTimers();
+    client.close();
+  });
+
+  test('dispatches server events and logs unknown types', async () => {
+    const sockets = setupFakeWebSocket();
+    const logger = { ...console, warn: vi.fn(), error: vi.fn() };
+    const client = createWsClient({ logger });
+    sockets[0].openNow();
+
+    /** @type {any[]} */
+    const events = [];
+    client.on('issues-changed', (p) => events.push(p));
+    sockets[0].emitMessage({
+      id: 'evt-1',
+      ok: true,
+      type: 'issues-changed',
+      payload: { ids: ['UI-1'] }
+    });
+    expect(events).toEqual([{ ids: ['UI-1'] }]);
+
+    // No handler registered for create-issue -> warn
+    sockets[0].emitMessage({
+      id: 'evt-2',
+      ok: true,
+      type: 'create-issue',
+      payload: {}
+    });
+    expect(logger.warn).toHaveBeenCalled();
+    client.close();
+  });
+});

package/bin/bdui.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Thin CLI entry for `bdui`.
+ * Delegates to `server/cli/index.js` and sets the process exit code.
+ */
+import { main } from '../server/cli/index.js';
+
+const argv = process.argv.slice(2);
+
+try {
+  const code = await main(argv);
+  if (Number.isFinite(code)) {
+    process.exitCode = /** @type {number} */ (code);
+  }
+} catch (err) {
+  console.error(String(/** @type {any} */ (err)?.message || err));
+  process.exitCode = 1;
+}

package/docs/architecture.md

@@ -0,0 +1,244 @@
+# beads-ui Architecture and Protocol (v1)
+
+This document describes the high‑level architecture of beads‑ui and the v1
+WebSocket protocol used between the browser SPA and the local Node.js server.
+
+## Overview
+
+- Local‑first single‑page app served by a localhost HTTP server
+- WebSocket for data (request/response + server push events)
+- Server bridges UI intents to the `bd` CLI and watches the active beads
+  database for changes
+
+```
++--------------+          ws://127.0.0.1:PORT/ws          +--------------------+
+|  Browser SPA | <--------------------------------------> | HTTP + WS Server   |
+|  (ESM, DOM)  |   requests (JSON) / replies + events     |  (Node.js, ESM)    |
++--------------+                                          +---------+----------+
+        ^                                                            |
+        |                                                            v
+        |                                                       +----+-----+
+        |                                                       |   bd     |
+        |                                                       |  (CLI)   |
+        |                                                       +----+-----+
+        |                                                            |
+        |                                     watches                v
+        |------------------------------------ changes --------> [ SQLite DB ]
+```
+
+## Components and Responsibilities
+
+- UI (app/)
+  - `app/main.js`: bootstraps shell, creates store/router, wires WS client,
+    refreshes on push
+  - Views: `app/views/list.js`, `app/views/detail.js` render issues and allow
+    edits
+  - Transport: `app/ws.js` persistent client with reconnect, correlation, and
+    event dispatcher
+  - Protocol: `app/protocol.js` shared message shapes, version, helpers, and
+    type guards
+
+- Server (server/)
+  - Web: `server/app.js` (Express app), `server/index.js` (startup and wiring)
+  - WebSocket: `server/ws.js` (attach server, parse, validate, dispatch
+    handlers, broadcast events)
+  - bd bridge: `server/bd.js` (spawn `bd`, inject `--db` consistently, JSON
+    helpers)
+  - DB resolution/watch: `server/db.js` (resolve active DB path),
+    `server/watcher.js` (emit `issues-changed`)
+  - Config: `server/config.js` (bind to `127.0.0.1`, default port 3000)
+
+## Data Flow
+
+1. User action in the UI creates a request `{ id, type, payload }` via
+   `app/ws.js`.
+2. Server validates and maps the request to a `bd` command (no shell; args array
+   only).
+3. Server replies with `{ id, ok, type, payload }` or `{ id, ok:false, error }`.
+4. Independent of requests, the DB watcher sends `issues-changed` events to all
+   clients.
+
+## Protocol (v1.0.0)
+
+Envelope shapes (see `app/protocol.js` for the source of truth):
+
+- Request: `{ id: string, type: MessageType, payload?: any }`
+- Reply:
+  `{ id: string, ok: boolean, type: MessageType, payload?: any, error?: { code, message, details? } }`
+
+Message types implemented by the server today:
+
+- `list-issues` payload: `{ filters?: { status?: string, priority?: number } }`
+- `show-issue` payload: `{ id: string }`
+- `update-status` payload:
+  `{ id: string, status: 'open'|'in_progress'|'closed' }`
+- `edit-text` payload:
+  `{ id: string, field: 'title'|'description'|'acceptance', value: string }`
+- `update-priority` payload: `{ id: string, priority: 0|1|2|3|4 }`
+- `dep-add` payload: `{ a: string, b: string, view_id?: string }`
+- `dep-remove` payload: `{ a: string, b: string, view_id?: string }`
+- `issues-changed` (server push) payload:
+  `{ ts: number, hint?: { ids?: string[] } }`
+
+Defined in the spec but not yet handled on the server:
+
+- `create-issue`, `list-ready`, `subscribe-updates` (client sends on connect;
+  ignored safely)
+
+### Examples
+
+List issues
+
+```json
+{
+  "id": "r1",
+  "type": "list-issues",
+  "payload": { "filters": { "status": "open" } }
+}
+```
+
+Reply
+
+```json
+{
+  "id": "r1",
+  "ok": true,
+  "type": "list-issues",
+  "payload": [{ "id": "UI-1", "title": "..." }]
+}
+```
+
+Update status
+
+```json
+{
+  "id": "r2",
+  "type": "update-status",
+  "payload": { "id": "UI-1", "status": "in_progress" }
+}
+```
+
+Server push (watcher)
+
+```json
+{
+  "id": "evt-1732212345000",
+  "ok": true,
+  "type": "issues-changed",
+  "payload": { "ts": 1732212345000 }
+}
+```
+
+Error reply
+
+```json
+{
+  "id": "r3",
+  "ok": false,
+  "type": "show-issue",
+  "error": { "code": "not_found", "message": "Issue UI-99" }
+}
+```
+
+## UI → bd Command Mapping
+
+- List: `bd list --json [--status <s>] [--priority <n>]`
+- Show: `bd show <id> --json`
+- Update status: `bd update <id> --status <open|in_progress|closed>`
+- Update priority: `bd update <id> --priority <0..4>`
+- Edit title: `bd update <id> --title <text>`
+- Edit description: not supported (immutable after create)
+- Edit acceptance: `bd update <id> --acceptance-criteria <text>`
+- Link dependency: `bd dep add <a> <b>` (a depends on b)
+- Unlink dependency: `bd dep remove <a> <b>`
+- Planned (UI not wired yet): Create:
+  `bd create "title" -t <type> -p <prio> -d "desc"`; Ready list:
+  `bd ready --json`
+
+Rationale
+
+- Use `--json` for read commands to ensure typed payloads.
+- Avoid shell invocation; pass args array to `spawn` to prevent injection.
+- Always inject a resolved `--db <path>` so watcher and CLI operate on the same
+  database.
+
+## Issue Data Model (wire)
+
+```ts
+interface Issue {
+  id: string;
+  title?: string;
+  description?: string;
+  acceptance?: string;
+  status?: 'open' | 'in_progress' | 'closed';
+  priority?: 0 | 1 | 2 | 3 | 4;
+  dependencies?: Array<{
+    id: string;
+    title?: string;
+    status?: string;
+    priority?: number;
+    issue_type?: string;
+  }>;
+  dependents?: Array<{
+    id: string;
+    title?: string;
+    status?: string;
+    priority?: number;
+    issue_type?: string;
+  }>;
+}
+```
+
+Notes
+
+- Fields are optional to allow partial views and forward compatibility.
+- Additional properties may appear; clients should ignore unknown keys.
+
+## Error Model and Versioning
+
+- Error object: `{ code: string, message: string, details?: any }`
+- Common codes: `bad_request`, `not_found`, `bd_error`, `unknown_type`,
+  `bad_json`
+- Versioning: `PROTOCOL_VERSION` in `app/protocol.js` (currently `1.0.0`).
+  Breaking changes increment this value; additive message types are backwards
+  compatible.
+
+## Security and Local Boundaries
+
+- Server binds to `127.0.0.1` by default to keep traffic local.
+- Basic input validation at the WS boundary; unknown or malformed messages
+  produce structured errors.
+- No shell usage; `spawn` with args only; environment opt‑in via `BD_BIN`.
+
+## Watcher Design
+
+- The server resolves the active beads SQLite DB path (see
+  `docs/db-watching.md`).
+- File watcher emits `issues-changed` events with a timestamp; UI refreshes
+  list/detail as needed.
+
+## Risks & Open Questions
+
+- Create flow not implemented in server handlers
+  - Owner: Server
+  - Next: Add `create-issue` handler and tests; wire minimal UI affordance
+- Ready list support missing end‑to‑end
+  - Owner: Server + UI
+  - Next: Add `list-ready` handler and a list filter in UI
+- Backpressure when many updates arrive
+  - Owner: Server
+  - Next: Coalesce broadcast events; consider debounce window
+- Large databases and payload size
+  - Owner: UI
+  - Next: Add incremental refresh (fetch issue by id on hints)
+- Cross‑platform DB path resolution nuances
+  - Owner: Server
+  - Next: Expand tests for Windows/macOS/Linux; document overrides
+- Acceptance text editing
+  - Owner: UI + Server
+  - Status: Implemented via `edit-text` + `--acceptance-criteria`
+
+---
+
+For the normative protocol reference and unit tests, see `app/protocol.md` and
+`app/protocol.test.js`.

package/docs/db-watching.md

@@ -0,0 +1,29 @@
+# DB Watching and Resolution
+
+The server watches the active beads SQLite database file for changes and
+broadcasts an `issues-changed` event to connected clients.
+
+## Resolution Order
+
+The DB path is resolved to match beads CLI precedence:
+
+1. `--db <path>` flag (when forced by the server configuration)
+2. `BEADS_DB` environment variable
+3. Nearest `.beads/*.db` by walking up from the server `root_dir`
+4. `~/.beads/default.db` fallback
+
+The resolved path is injected into all `bd` CLI invocations via `--db` to ensure
+the watcher and CLI operate on the same database.
+
+## Behavior When Missing
+
+If no database exists at the resolved path (e.g., before `bd init`), the server
+will still attempt to bind a watcher on the containing directory and log a clear
+warning. Initialize a database with one of:
+
+- `bd --db /path/to/file.db init`
+- `export BEADS_DB=/path/to/file.db && bd init`
+- `bd init` in a workspace with a `.beads/` directory
+
+After initialization, changes will be detected without restarting the server.
+The watcher can rebind when the workspace or configuration changes at runtime.