beads-ui 0.1.2 → 0.3.0

package/app/protocol.js

@@ -6,17 +6,10 @@
  * - Client → Server uses RequestEnvelope.
  * - Server → Client uses ReplyEnvelope.
  * - Every request is correlated by `id` in replies.
- * - Server can also send unsolicited events (e.g., `issues-changed`).
- *
- * Versioning
- * - Increment `PROTOCOL_VERSION` on breaking changes.
- * - Add new message types without breaking existing ones when possible.
+ * - Server can also send unsolicited events (e.g., subscription `snapshot`).
  */
 
-/** @constant {string} */
-export const PROTOCOL_VERSION = '1.0.0';
-
-/** @typedef {'list-issues'|'show-issue'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'subscribe-updates'|'issues-changed'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'} MessageType */
+/** @typedef {'list-issues'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'|'subscribe-list'|'unsubscribe-list'|'snapshot'|'upsert'|'delete'} MessageType */
 
 /**
  * @typedef {Object} RequestEnvelope
@@ -44,20 +37,23 @@ export const PROTOCOL_VERSION = '1.0.0';
 /** @type {MessageType[]} */
 export const MESSAGE_TYPES = /** @type {const} */ ([
   'list-issues',
-  'show-issue',
   'update-status',
   'edit-text',
   'update-priority',
   'create-issue',
   'list-ready',
-  'subscribe-updates',
-  'issues-changed',
   'dep-add',
   'dep-remove',
   'epic-status',
   'update-assignee',
   'label-add',
-  'label-remove'
+  'label-remove',
+  'subscribe-list',
+  'unsubscribe-list',
+  // vNext per-subscription full-issue push events
+  'snapshot',
+  'upsert',
+  'delete'
 ]);
 
 /**
@@ -162,7 +158,7 @@ export function isReply(value) {
     return false;
   }
   if (value.ok === false) {
-    const err = /** @type {any} */ (value).error;
+    const err = value.error;
     if (
       !isRecord(err) ||
       typeof err.code !== 'string' ||

package/app/protocol.md

@@ -1,4 +1,12 @@
-# beads-ui WebSocket Protocol (v1.0.0)
+# beads-ui WebSocket Protocol (v2.0.0)
+
+Note (2025-10-26)
+
+- The server no longer implements legacy read RPCs `list-issues` and
+  `epic-status`. Clients must use the push-only protocol described in
+  `docs/protocol/issues-push-v2.md` (subscribe-list with per-subscription events
+  snapshot/upsert/delete). The shapes below are retained for historical
+  reference of v1.
 
 This document defines the JSON messages exchanged between the browser client and
 the local server.
@@ -13,25 +21,24 @@ the local server.
 - ReplyEnvelope:
   `{ id: string, ok: boolean, type: string, payload?: any, error?: { code: string, message: string, details?: any } }`
 
-Server may send unsolicited events (e.g., `issues-changed`) using the
-ReplyEnvelope shape with `ok: true` and a generated `id`.
+Server may send unsolicited events (e.g., subscription
+`snapshot`/`upsert`/`delete`) using the ReplyEnvelope shape with `ok: true` and
+a generated `id`.
 
 ## Message Types
 
-- `list-issues` payload: `{ filters?: { status?: string, priority?: number } }`
-- `show-issue` payload: `{ id: string }`
+- Removed in v2: `list-issues` (use subscriptions + push stores)
 - `update-status` payload:
   `{ id: string, status: 'open'|'in_progress'|'closed' }`
 - `edit-text` payload:
-  `{ id: string, field: 'title'|'description'|'acceptance', value: string }`
-  - Note: `description` edits are rejected by the server (unsupported by `bd`).
+  `{ id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', value: string }`
 - `update-priority` payload: `{ id: string, priority: 0|1|2|3|4 }`
 - `create-issue` payload:
   `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
 - `list-ready` payload: `{}`
-- `subscribe-updates` payload: `{}` (server responds with `ok` and begins
-  emitting events)
-- `issues-changed` payload: `{ ts: number, hint?: { ids?: string[] } }`
+- Removed in v2: `subscribe-updates` and the `issues-changed` event. All list
+  and detail updates flow via per-subscription push envelopes
+  (`snapshot`/`upsert`/`delete`).
 - `dep-add` payload: `{ a: string, b: string, view_id?: string }` where `a`
   depends on `b` (i.e., `a` is blocked by `b`). Reply payload is the updated
   issue for `view_id` (or `a` when omitted).
@@ -41,11 +48,11 @@ ReplyEnvelope shape with `ok: true` and a generated `id`.
 
 ## Mapping to `bd` CLI
 
-- `list-issues` → `bd list --json [--status <s>] [--priority <n>]`
-- `show-issue` → `bd show <id> --json`
+- Removed in v2: `list-issues` → use subscriptions and push
+  (`docs/protocol/issues-push-v2.md`)
 - `update-status` → `bd update <id> --status <status>`
-- `edit-text` → `bd update <id> --title <t>` or `--acceptance-criteria <a>`
-  - `description` has no CLI flag; server responds with an error
+- `edit-text` → `bd update <id> --title <t>` or `--description <d>` or
+  `--acceptance-criteria <a>` or `--notes <n>` or `--design <z>`
 - `update-priority` → `bd update <id> --priority <n>`
 - `create-issue` → `bd create "title" -t <type> -p <prio> -d "desc"`
 - `list-ready` → `bd ready --json`
@@ -57,8 +64,3 @@ Errors follow the shape `{ code, message, details? }`. Common codes:
 - `bad_request` – malformed payload or unknown type
 - `not_found` – entity not found (e.g., issue id)
 - `bd_error` – underlying `bd` command failed
-
-## Versioning
-
-Breaking changes to shapes or semantics increment `PROTOCOL_VERSION` in
-`app/protocol.js`.

package/app/router.js

@@ -1,14 +1,31 @@
+import { issueHashFor } from './utils/issue-url.js';
+
 /**
  * Hash-based router for tabs (issues/epics/board) and deep-linked issue ids.
  */
 
 /**
  * Parse an application hash and extract the selected issue id.
+ * Supports canonical form "#/(issues|epics|board)?issue=<id>" and legacy
+ * "#/issue/<id>" which we will rewrite to the canonical form.
  * @param {string} hash
  * @returns {string | null}
  */
 export function parseHash(hash) {
-  const m = /^#\/issue\/([^\s?#]+)/.exec(hash || '');
+  const h = String(hash || '');
+  // Extract the fragment sans leading '#'
+  const frag = h.startsWith('#') ? h.slice(1) : h;
+  const qIndex = frag.indexOf('?');
+  const query = qIndex >= 0 ? frag.slice(qIndex + 1) : '';
+  if (query) {
+    const params = new URLSearchParams(query);
+    const id = params.get('issue');
+    if (id) {
+      return decodeURIComponent(id);
+    }
+  }
+  // Legacy pattern: #/issue/<id>
+  const m = /^\/issue\/([^\s?#]+)/.exec(frag);
   return m && m[1] ? decodeURIComponent(m[1]) : null;
 }
 
@@ -30,18 +47,26 @@ export function parseView(hash) {
 }
 
 /**
- * Create and start the hash router.
  * @param {{ getState: () => any, setState: (patch: any) => void }} store
- * @returns {{ start: () => void, stop: () => void, gotoIssue: (id: string) => void, gotoView: (v: 'issues'|'epics'|'board') => void }}
  */
 export function createHashRouter(store) {
   /** @type {(ev?: HashChangeEvent) => any} */
   const onHashChange = () => {
     const hash = window.location.hash || '';
+    // Rewrite legacy #/issue/<id> to canonical #/issues?issue=<id>
+    const legacyMatch = /^#\/issue\/([^\s?#]+)/.exec(hash);
+    if (legacyMatch && legacyMatch[1]) {
+      const id = decodeURIComponent(legacyMatch[1]);
+      // Update state immediately for consumers expecting sync selection
+      store.setState({ selected_id: id, view: 'issues' });
+      const next = `#/issues?issue=${encodeURIComponent(id)}`;
+      if (window.location.hash !== next) {
+        window.location.hash = next;
+        return; // will trigger handler again
+      }
+    }
     const id = parseHash(hash);
-    // Preserve current view when navigating to a detail route so tabs remain stable
-    const current = store.getState ? store.getState() : { view: 'issues' };
-    const view = id ? current.view || 'issues' : parseView(hash);
+    const view = parseView(hash);
     store.setState({ selected_id: id, view });
   };
 
@@ -53,21 +78,32 @@ export function createHashRouter(store) {
     stop() {
       window.removeEventListener('hashchange', onHashChange);
     },
+    /**
+     * @param {string} id
+     */
     gotoIssue(id) {
-      const next = `#/issue/${encodeURIComponent(id)}`;
+      // Keep current view in hash and append issue param via helper
+      const s = store.getState ? store.getState() : { view: 'issues' };
+      const view = s.view || 'issues';
+      const next = issueHashFor(view, id);
       if (window.location.hash !== next) {
         window.location.hash = next;
       } else {
         // Force state update even if hash is the same
-        store.setState({ selected_id: id, view: 'issues' });
+        store.setState({ selected_id: id, view });
       }
     },
     /**
      * Navigate to a top-level view.
      * @param {'issues'|'epics'|'board'} view
      */
+    /**
+     * @param {'issues'|'epics'|'board'} view
+     */
     gotoView(view) {
-      const next = `#/${view}`;
+      const s = store.getState ? store.getState() : { selected_id: null };
+      const id = s.selected_id;
+      const next = id ? issueHashFor(view, id) : `#/${view}`;
       if (window.location.hash !== next) {
         window.location.hash = next;
       } else {

package/app/state.js

@@ -15,7 +15,15 @@
  */
 
 /**
- * @typedef {{ selected_id: string | null, view: ViewName, filters: Filters }} AppState
+ * @typedef {'today'|'3'|'7'} ClosedFilter
+ */
+
+/**
+ * @typedef {{ closed_filter: ClosedFilter }} BoardState
+ */
+
+/**
+ * @typedef {{ selected_id: string | null, view: ViewName, filters: Filters, board: BoardState }} AppState
  */
 
 /**
@@ -26,15 +34,21 @@
 export function createStore(initial = {}) {
   /** @type {AppState} */
   let state = {
-    selected_id: /** @type {any} */ (initial).selected_id ?? null,
-    view: /** @type {any} */ (initial).view ?? 'issues',
+    selected_id: initial.selected_id ?? null,
+    view: initial.view ?? 'issues',
     filters: {
-      status: /** @type {any} */ (initial).filters?.status ?? 'all',
-      search: /** @type {any} */ (initial).filters?.search ?? '',
+      status: initial.filters?.status ?? 'all',
+      search: initial.filters?.search ?? '',
       type:
-        typeof (/** @type {any} */ (initial).filters?.type) === 'string'
-          ? /** @type {any} */ (initial).filters?.type
-          : ''
+        typeof initial.filters?.type === 'string' ? initial.filters?.type : ''
+    },
+    board: {
+      closed_filter:
+        initial.board?.closed_filter === '3' ||
+        initial.board?.closed_filter === '7' ||
+        initial.board?.closed_filter === 'today'
+          ? initial.board?.closed_filter
+          : 'today'
     }
   };
 
@@ -57,14 +71,15 @@ export function createStore(initial = {}) {
     },
     /**
      * Update state. Nested filters can be partial.
-     * @param {{ selected_id?: string | null, filters?: Partial<Filters> }} patch
+     * @param {{ selected_id?: string | null, filters?: Partial<Filters>, board?: Partial<BoardState> }} patch
      */
     setState(patch) {
       /** @type {AppState} */
       const next = {
         ...state,
         ...patch,
-        filters: { ...state.filters, ...(patch.filters || {}) }
+        filters: { ...state.filters, ...(patch.filters || {}) },
+        board: { ...state.board, ...(patch.board || {}) }
       };
       // Avoid emitting if nothing changed (shallow compare)
       if (
@@ -72,7 +87,8 @@ export function createStore(initial = {}) {
         next.view === state.view &&
         next.filters.status === state.filters.status &&
         next.filters.search === state.filters.search &&
-        next.filters.type === state.filters.type
+        next.filters.type === state.filters.type &&
+        next.board.closed_filter === state.board.closed_filter
       ) {
         return;
       }