beads-ui 0.1.2 → 0.3.0

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,105 +61,52 @@ 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>`
-- Edit description: not supported (immutable after create)
+- Edit description: `bd update <id> --description <text>`
 - 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
 

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