beads-ui 0.2.0 → 0.3.1

package/docs/adr/001-push-only-lists.md

@@ -0,0 +1,134 @@
+# ADR 001 — Push‑Only Lists (v2)
+
+```
+Date: 2025-10-26
+Status: Accepted (data‑flow details superseded by ADR 002)
+Owner: agent
+```
+
+## Context
+
+The UI currently mixes push updates with read RPCs like `list-issues` and
+`epic-status`. This ADR establishes the push‑only direction for list data and
+removing read RPCs in list views. It predated ADR 002 which later simplified the
+data flow further (per‑subscription stores + full‑issue payloads).
+
+- Push streams provide everything lists need to render. See
+  `docs/protocol/issues-push-v2.md` and ADR 002. Earlier iterations used a
+  central `issues` entity cache plus `list-delta` membership; this has been
+  replaced by per‑subscription stores receiving full issue payloads.
+
+We want every list‑shaped view (Issues, Board, Epics → children) to render
+exclusively from local push data. Reads remain only for mutations that return a
+single updated entity (e.g. detail view refresh).
+
+Related docs:
+
+- Protocol: `docs/protocol/issues-push-v2.md`
+- Server plan: `docs/data-exchange-subscription-plan.md`
+
+## Decision
+
+- One active subscription per visible list. Examples (client ids):
+  - Issues tab: `tab:issues` with spec from filters via `computeIssuesSpec()`
+  - Board: `tab:board:ready|in-progress|closed|blocked`
+  - Epics list: `tab:epics` (for epic entities); children subscribe on expand as
+    `detail:{id}` with `{ type: 'issue-detail', params: { id } }`
+- Rendering reads from two local stores only:
+  - `per‑subscription stores`: one store per active client subscription id.
+    Stores receive versioned `snapshot`/`upsert`/`delete` push envelopes with
+    full issue payloads and expose deterministic, sorted snapshots for the
+    owning view.
+  - `subscriptions`: manages subscription lifecycle and keys. Rendering reads
+    from per‑subscription stores, not from membership ids.
+- Introduce a small selectors utility to apply view‑specific sort rules on store
+  snapshots (no composition from a central cache).
+- Remove read RPCs used for lists: `list-issues`, `epic-status`. Keep mutation
+  RPCs and `show-issue` until detail view also reads from push cache.
+- Tests drive views with push envelopes and `list-delta`; no RPC stubs for
+  reads.
+
+## API Shape (Client)
+
+Subscriptions store (already implemented):
+
+```js
+// app/data/subscriptions-store.js
+createSubscriptionStore(send) -> {
+  wireEvents(on), subscribeList(client_id, spec) -> unsubscribe,
+  selectors: { getIds(client_id), has(client_id), count(client_id) }
+}
+```
+
+Selectors utility (implemented):
+
+```js
+// app/data/list-selectors.js
+/** Compose from per‑subscription store snapshots and apply stable sort. */
+export function createListSelectors(issueStores) {
+  return {
+    selectIssuesFor(client_id) {},
+    selectBoardColumn(client_id, mode) {},
+    selectEpicChildren(epic_id) {},
+    subscribe(fn) {}
+  };
+}
+```
+
+Sorting rules:
+
+- Issues list: priority asc (0..4), then `created_at` desc, then id asc.
+- Board columns: preserve existing view rules (ready → priority asc, then
+  `updated_at` desc; in‑progress → `updated_at` desc; closed → `closed_at`
+  desc).
+- Epics children: same as Issues list unless view specifies otherwise.
+
+## Consequences
+
+Pros:
+
+- Consistent, snappy UI with minimal fetch logic; views are pure derives.
+- Server can batch and coalesce; client renders at most once per envelope.
+- Clear separation: mutations via RPC, reads via push caches.
+
+Cons / Risks:
+
+- Initial implementation work in views and tests.
+- Need disciplined subscription lifecycle on route/tab changes.
+- Requires follow‑up to migrate detail view fully to the push cache.
+
+## Migration Checklist
+
+Views
+
+- [x] Issues view renders from per‑subscription stores; no `list-issues`.
+- [x] Board renders from per‑subscription stores; no `get*` list reads.
+- [x] Epics list/children render from per‑subscription stores; children use
+      `issue-detail` for the epic id; children come from `dependents`.
+
+Client Data Layer
+
+- [x] Add `app/data/list-selectors.js` with helpers listed above (UI-156).
+- [x] Remove list read functions from `app/data/providers.js` (UI-159).
+- [ ] Keep `getIssue` and all mutation helpers until detail view push migration
+      happens (follow‑up).
+
+Tests
+
+- [x] Update list/board/epics tests to use per‑subscription push envelopes
+      (UI-158).
+- [x] Remove RPC read stubs from tests.
+
+Docs
+
+- [x] This ADR committed (UI-152).
+- [x] Update protocol and architecture docs for push‑only model (UI-160).
+
+## Notes
+
+- Client ids used in this repo today:
+  - `tab:issues` for the Issues view
+  - `tab:board:ready|in-progress|closed|blocked` for Board columns
+  - `tab:epics` for the Epics tab; `epic:${id}` for expanded children
+- See `app/main.js` for current subscription wiring, filter → spec mapping, and
+  per‑subscription push routing.

package/docs/adr/002-per-subscription-stores-and-full-issue-push.md

@@ -0,0 +1,200 @@
+# ADR 002 — Per‑Subscription Stores and Full‑Issue Push (Breaking)
+
+```
+Date: 2025-10-26
+Status: Proposed (ready for owner approval)
+Owner: agent
+```
+
+## Context
+
+The UI currently maintains a central `issues` cache and a separate list
+membership model. Push events update the central cache and lists fan out from
+it. This split increases cognitive load (two caches, two sets of selectors),
+creates subtle ordering/dedup bugs, and complicates tests and routing.
+
+We want a simpler, local model per visible list: one subscription → one store →
+one push update stream → one rendered list. Push events must contain complete
+issue objects for correctness and to avoid fan‑out to a central cache.
+
+## Decision
+
+- Adopt a per‑subscription issue store (`SubscriptionIssueStore`) keyed by the
+  client’s subscription id.
+- Server sends per‑subscription full‑issue payloads only; no id‑only deltas.
+  Messages are serialized per subscription and revisioned.
+- Lists render exclusively from their own store snapshots; the central issue
+  cache is removed from the list render path.
+- Breaking change: remove legacy id‑only list deltas and any compatibility
+  paths/flags. No phased rollout and no telemetry collection.
+
+## Protocol (Server → Client)
+
+Message shapes are defined in `types/subscriptions.ts` and documented in
+`docs/data-exchange-subscription-plan.md`.
+
+All envelopes include a version tag and a per‑subscription, strictly monotonic
+`revision` used for ordering and replay protection (see UI‑144).
+
+- `subscribed` `{ id: string }`
+- `snapshot` `{ id: string, revision: number, issues: Issue[] }`
+- `upsert` `{ id: string, revision: number, issue: Issue }`
+- `delete` `{ id: string, revision: number, issue_id: string }`
+- `error` `{ id?: string, code: string, message: string, details?: object }`
+
+Notes
+
+- Per‑subscription ordering is guaranteed by the server and signaled via
+  `revision`. Clients MUST apply envelopes in `revision` order and ignore any
+  envelope whose `revision` is ≤ the last applied.
+- Clients MUST treat updates as idempotent and MAY additionally guard on an
+  `issue.updated_at` timestamp to ignore stale `upsert`s that race with local
+  state. Timestamps are advisory; `revision` is canonical for ordering.
+- Initial state arrives as a `snapshot` with a complete list of issues for the
+  subscription key.
+
+## Client Store API
+
+The UI manages one store per active subscription. Minimal API surface:
+
+```ts
+// types only — see types/subscription-issue-store.ts
+export interface SubscriptionIssueStore {
+  /** Client subscription id this store belongs to. */
+  readonly id: string;
+
+  /** Attach a listener that is called after each applied message. */
+  subscribe(listener: () => void): () => void;
+
+  /** Apply a push message: snapshot, upsert, or delete. */
+  applyPush(msg: SnapshotMsg | UpsertMsg | DeleteMsg): void;
+
+  /** Read-only, stable snapshot for rendering (deterministic sort). */
+  snapshot(): readonly Issue[];
+
+  /** Lookup helpers used by views/tests. */
+  size(): number;
+  getById(id: string): Issue | undefined;
+
+  /** Release references and listeners when the view unmounts. */
+  dispose(): void;
+}
+
+export type SnapshotMsg = {
+  type: 'snapshot';
+  id: string;
+  revision: number;
+  issues: Issue[];
+};
+
+export type UpsertMsg = {
+  type: 'upsert';
+  id: string;
+  revision: number;
+  issue: Issue;
+};
+
+export type DeleteMsg = {
+  type: 'delete';
+  id: string;
+  revision: number;
+  issue_id: string;
+};
+```
+
+### Sorting and identity
+
+- Stores maintain stable item identity across updates (same object ref for the
+  same `id` when only fields change) and expose a deterministic sort order
+  suitable for the owning view (e.g., Issues: priority asc, then `created_at`
+  desc, then id asc).
+
+### Error handling and reconnect
+
+- On disconnect/reconnect, the client creates a fresh store and re‑subscribes.
+  The server sends a fresh snapshot; no attempt is made to diff across sessions.
+
+### Reconcile algorithm (pseudo‑code)
+
+```
+state: Map<string, Issue> = new Map()
+lastRevision: number = 0
+
+function applyPush(msg) {
+  if (msg.revision <= lastRevision) return // stale or duplicate
+  lastRevision = msg.revision
+
+  switch (msg.type) {
+    case 'snapshot':
+      state.clear()
+      for (const it of deterministicallySort(msg.issues)) {
+        state.set(it.id, it)
+      }
+      break
+    case 'upsert':
+      const existing = state.get(msg.issue.id)
+      if (!existing || existing.updated_at <= msg.issue.updated_at) {
+        state.set(msg.issue.id, msg.issue)
+      }
+      break
+    case 'delete':
+      state.delete(msg.issue_id)
+      break
+  }
+  notifyListeners()
+}
+```
+
+The sort function must be deterministic and view‑specific (e.g., priority asc,
+then `created_at` desc, then `id` asc). Stores keep object identity stable for
+the same `id` whenever fields change.
+
+## Migration
+
+- Delete list render paths that read via the central issues cache.
+- Introduce a factory `createSubscriptionIssueStore(id)` at view mount; wire the
+  push client to route `snapshot`/`upsert`/`delete` messages by `id` to the
+  corresponding store via `applyPush`.
+- Update list components to render from `store.snapshot()` and subscribe to
+  re‑render on changes.
+- Remove legacy central‑store fan‑out and dead selectors.
+
+## Consequences
+
+Pros
+
+- One‑to‑one mapping of subscription → store → view simplifies reasoning and
+  testing.
+- No cache fan‑out; updates apply once per subscription and render once.
+- Clearer ownership boundaries; easier disposal on route/tab changes.
+
+Cons / Risks
+
+- Larger `updated` payloads vs id‑only membership deltas. Mitigated by
+  per‑subscription scoping and batching.
+- Requires coordinated server/client cutover due to the breaking change.
+
+## Alternatives Considered
+
+- Keep the central cache and fan‑out membership to lists. Rejected: duplicates
+  ownership, increases complexity and test surface, caused known ordering bugs.
+- Maintain id‑only list deltas with separate issue fetches. Rejected: adds
+  round‑trips and cross‑store coordination; does not meet simplicity goal.
+- Dual protocol/feature flag with gradual cutover. Rejected per epic scope: no
+  flags, no compatibility layer, and no telemetry collection.
+
+## Related
+
+- ADR 001 — Push‑Only Lists (v2): establishes push‑only direction and server
+  batching; this ADR replaces the central‑store + list‑membership split with a
+  per‑subscription store model.
+- `docs/protocol/issues-push-v2.md` and
+  `docs/data-exchange-subscription-plan.md` for normative protocol and server
+  behavior.
+
+## Status & Follow‑ups
+
+- This ADR is a breaking change with no flags/compat/telemetry. It becomes
+  Accepted once UI‑166 is approved by frontend and backend owners and the
+  server/client work (UI‑167, UI‑168, UI‑169) lands.
+- Cleanup (UI-174) removes the central store and delta fan‑out code.

package/docs/architecture.md

@@ -1,7 +1,13 @@
-# beads-ui Architecture and Protocol (v1)
+# beads-ui Architecture (v2)
 
-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.
+Note (2025-10-26)
+
+- beads-ui has migrated to a push‑only protocol for lists and details. The
+  server no longer implements legacy read RPCs `list-issues` and `epic-status`.
+  For the normative protocol reference, see `docs/protocol/issues-push-v2.md`.
+
+This document describes the high‑level architecture of beads‑ui and the v2
+push‑only data flow used between the browser SPA and the local Node.js server.
 
 ## Overview
 
@@ -45,7 +51,7 @@ WebSocket protocol used between the browser SPA and the local Node.js server.
   - 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`)
+    `server/watcher.js` (schedule list refresh)
   - Config: `server/config.js` (bind to `127.0.0.1`, default port 3000)
 
 ## Data Flow
@@ -55,95 +61,44 @@ WebSocket protocol used between the browser SPA and the local Node.js server.
 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.
+4. Independent of requests, the DB watcher schedules a refresh for active list
+   subscriptions; clients receive `snapshot`/`upsert`/`delete` envelopes.
 
-## Protocol (v1.0.0)
+## Protocol (v2.0.0)
 
-Envelope shapes (see `app/protocol.js` for the source of truth):
+Envelope shapes (see `app/protocol.md` and `docs/protocol/issues-push-v2.md`):
 
-- Request: `{ id: string, type: MessageType, payload?: any }`
+- Request: `{ id: string, type: string, payload?: any }`
 - Reply:
-  `{ id: string, ok: boolean, type: MessageType, payload?: any, error?: { code, message, details? } }`
+  `{ id: string, ok: boolean, type: string, payload?: any, error?: { code: string, message: string, details?: any } }`
+
+Push‑only subscriptions for lists and details:
+
+- Client subscribes via `subscribe-list` with `{ id, type, params? }`.
+- Server acks the subscription and immediately publishes a `snapshot` envelope
+  with the full list for that subscription id followed by `upsert`/`delete`
+  envelopes as data changes. Clients render from local per‑subscription stores.
 
-Message types implemented by the server today:
+Common message types (mutations only; list reads removed):
 
-- `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 }`
+  `{ id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', 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
+- `create-issue` payload:
+  `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
 
-List issues
+Removed in v2:
 
-```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" }
-}
-```
+- `list-issues`, `epic-status`, `subscribe-updates` and the legacy
+  `issues-changed` event.
 
 ## UI → bd Command Mapping
 
-- List: `bd list --json [--status <s>] [--priority <n>]`
-- Show: `bd show <id> --json`
+- Lists and details: push‑only via `subscribe-list` (no list reads)
 - 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>`
@@ -151,9 +106,7 @@ Error reply
 - 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`
+- Create issue: `bd create "title" -t <type> -p <prio> -d "desc"`
 
 Rationale
 
@@ -199,9 +152,6 @@ Notes
 - 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
 
@@ -214,8 +164,8 @@ Notes
 
 - 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.
+- File watcher schedules list refresh; the server publishes subscription
+  envelopes. UI re-renders from local per-subscription stores.
 
 ## Risks & Open Questions