beads-ui 0.3.0 → 0.4.0

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

@@ -1,134 +0,0 @@
-# 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

@@ -1,200 +0,0 @@
-# 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,194 +0,0 @@
-# beads-ui Architecture (v2)
-
-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
-
-- 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` (schedule list refresh)
-  - 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 schedules a refresh for active list
-   subscriptions; clients receive `snapshot`/`upsert`/`delete` envelopes.
-
-## Protocol (v2.0.0)
-
-Envelope shapes (see `app/protocol.md` and `docs/protocol/issues-push-v2.md`):
-
-- Request: `{ id: string, type: string, payload?: any }`
-- Reply:
-  `{ 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.
-
-Common message types (mutations only; list reads removed):
-
-- `update-status` payload:
-  `{ id: string, status: 'open'|'in_progress'|'closed' }`
-- `edit-text` payload:
-  `{ 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 }`
-- `create-issue` payload:
-  `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
-
-Removed in v2:
-
-- `list-issues`, `epic-status`, `subscribe-updates` and the legacy
-  `issues-changed` event.
-
-## UI → bd Command Mapping
-
-- 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: `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>`
-- Create issue: `bd create "title" -t <type> -p <prio> -d "desc"`
-
-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`
-
-## 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 schedules list refresh; the server publishes subscription
-  envelopes. UI re-renders from local per-subscription stores.
-
-## 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`.