beads-ui 0.3.0 → 0.4.0

package/docs/data-exchange-subscription-plan.md

@@ -1,198 +0,0 @@
-# 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,30 +0,0 @@
-# DB Watching and Resolution
-
-The server watches the active beads SQLite database file for changes and
-schedules a refresh of active list subscriptions. Clients receive
-`snapshot`/`upsert`/`delete` envelopes for their active subscriptions.
-
-## 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.

package/docs/migration-v2.md

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

package/docs/protocol/issues-push-v2.md

@@ -1,179 +0,0 @@
-# Subscription Push Protocol — per‑subscription full‑issue envelopes (Breaking)
-
-```
-Date: 2025-10-26
-Status: Implemented
-Owner: agent
-```
-
-This document specifies the push‑only protocol used by beads‑ui to deliver list
-updates from the local server to the client. It replaces the legacy
-notify‑then‑fetch model. There is no version negotiation or fallback.
-
-## Overview
-
-- Transport: single WebSocket connection per client
-- Encoding: JSON text frames
-- Subscriptions: one client‑chosen `id` per active list subscription
-- Delivery: per‑subscription envelopes with full issue payloads
-- Messages: `snapshot` | `upsert` | `delete`
-- Ordering: strictly increasing `revision` per subscription key and connection
-
-## Envelopes
-
-```ts
-export type SnapshotEnvelope = {
-  type: 'snapshot';
-  id: string; // client subscription id
-  revision: number; // starts at 1 and increments per envelope
-  issues: Issue[]; // full list for this subscription
-};
-
-export type UpsertEnvelope = {
-  type: 'upsert';
-  id: string;
-  revision: number;
-  issue: Issue; // full issue payload
-};
-
-export type DeleteEnvelope = {
-  type: 'delete';
-  id: string;
-  revision: number;
-  issue_id: string; // id only
-};
-```
-
-Notes
-
-- Server serializes refresh runs per subscription key and emits envelopes in
-  `revision` order. Clients MUST ignore any envelope with `revision <=` the last
-  applied for the same `id`.
-- Clients SHOULD treat `upsert` as idempotent and MAY additionally guard on an
-  `issue.updated_at` timestamp to ignore stale updates racing with local state.
-
-## Handshake (subscribe‑list)
-
-Client subscribes to a list with a chosen `id`, a `type`, and optional `params`.
-
-Client → Server
-
-```json
-{
-  "id": "req-1",
-  "type": "subscribe-list",
-  "payload": { "id": "ready", "type": "ready-issues" }
-}
-```
-
-Server → Client
-
-```json
-{
-  "id": "req-1",
-  "ok": true,
-  "type": "subscribe-list",
-  "payload": { "id": "ready", "key": "ready-issues:{}" }
-}
-```
-
-Immediately after the ack, the server sends a `snapshot` envelope containing the
-full list for that subscription `id` with `revision: 1`.
-
-```json
-{
-  "id": "evt-1730000000000",
-  "ok": true,
-  "type": "snapshot",
-  "payload": {
-    "type": "snapshot",
-    "id": "ready",
-    "revision": 1,
-    "issues": [{ "id": "UI-1", "title": "..." }]
-  }
-}
-```
-
-## Updates
-
-Subsequent refreshes emit `upsert` and `delete` envelopes as the list changes.
-
-```json
-{
-  "id": "evt-1730000000100",
-  "ok": true,
-  "type": "upsert",
-  "payload": {
-    "type": "upsert",
-    "id": "ready",
-    "revision": 2,
-    "issue": { "id": "UI-2", "status": "in_progress" }
-  }
-}
-```
-
-```json
-{
-  "id": "evt-1730000000200",
-  "ok": true,
-  "type": "delete",
-  "payload": {
-    "type": "delete",
-    "id": "ready",
-    "revision": 3,
-    "issue_id": "UI-9"
-  }
-}
-```
-
-## Reconnect Behavior
-
-- On reconnect, clients resubscribe using the same `id` values as needed. The
-  server treats this as a new connection and sends a fresh `snapshot` with
-  `revision: 1` for each active subscription.
-
-## Diagrams
-
-```mermaid
-sequenceDiagram
-  participant C as Client
-  participant S as Server
-  C->>S: subscribe-list { id, type, params }
-  S-->>C: ack { id, key }
-  S-->>C: snapshot { id, schema, revision:1, issues:[...] }
-  S-->>C: upsert/delete { id, schema, revision:n, ... }
-```
-
-```mermaid
-stateDiagram-v2
-  [*] --> Idle
-  Idle --> Subscribed: subscribe-list(id)
-  Subscribed --> Subscribed: snapshot(rev=1)
-  Subscribed --> Subscribed: upsert/delete(rev++)
-  Subscribed --> Idle: unsubscribe-list(id) / disconnect
-```
-
-## Client Responsibilities
-
-- Maintain one `SubscriptionIssueStore` per active subscription `id`.
-- Apply envelopes strictly in `revision` order; ignore stale revisions.
-- Render list components from `store.snapshot()` (deterministic order).
-- Dispose stores on route/tab changes.
-
-Detail view
-
-- Detail pages use the same mechanism with a single‑item subscription, e.g.
-  `{ type: 'issue-detail', params: { id: 'UI-1' } }` under a client id like
-  `detail:UI-1`. The server returns a one‑element list for `snapshot` and
-  `upsert` events.
-
-## Rollout and Compatibility
-
-- Breaking change: no flags and no compatibility layer with the legacy
-  notify‑then‑fetch flow. Update both client and server together.
-
-## See Also
-
-- ADR 002 — Per‑Subscription Stores and Full‑Issue Push
-- `docs/data-exchange-subscription-plan.md` (server refresh and publish model)
-- `docs/subscription-issue-store.md` (store API and usage examples)

package/docs/subscription-issue-store.md

@@ -1,112 +0,0 @@
-# SubscriptionIssueStore — API and Usage Examples
-
-```
-Date: 2025-10-26
-Status: Implemented
-Owner: agent
-```
-
-The `SubscriptionIssueStore` is a per‑subscription in‑memory store that owns the
-issues for a single list subscription. It applies server push envelopes
-(`snapshot`/`upsert`/`delete`) in revision order and exposes a deterministic,
-read‑only snapshot for rendering.
-
-See also: `docs/protocol/issues-push-v2.md` for the wire protocol.
-
-## API
-
-Factory: `app/data/subscription-issue-store.js`
-
-```js
-import { createSubscriptionIssueStore } from '../app/data/subscription-issue-store.js';
-
-// Create at view mount (id is client-chosen)
-const store = createSubscriptionIssueStore('ready');
-
-// Listen for changes
-const unsubscribe = store.subscribe(() => {
-  render(store.snapshot());
-});
-
-// Apply push envelopes from the WebSocket client
-ws.on('message', (evt) => {
-  const msg = JSON.parse(evt.data);
-  if (msg && msg.ok === true && msg.payload && msg.payload.id === 'ready') {
-    // payload has { type, id, schema, revision, ... }
-    store.applyPush(msg.payload);
-  }
-});
-
-// Read helpers
-store.size(); // number of issues
-store.getById('UI-1'); // lookup by id
-
-// Dispose on unmount
-unsubscribe();
-store.dispose();
-```
-
-Options: deterministic sort can be customized per list via the optional
-`{ sort(a,b) }` parameter when constructing the store.
-
-## Subscribing to a List
-
-Pair store creation with the subscribe‑list handshake. The server will send a
-`snapshot` immediately after the ack, followed by `upsert`/`delete`.
-
-```js
-// Request a subscription
-socket.send(
-  JSON.stringify({
-    id: 'req-1',
-    type: 'subscribe-list',
-    payload: { id: 'ready', type: 'ready-issues' }
-  })
-);
-
-socket.addEventListener('message', (ev) => {
-  const frame = JSON.parse(ev.data);
-  if (frame.ok && frame.type === 'snapshot' && frame.payload.id === 'ready') {
-    store.applyPush(frame.payload);
-  }
-  if (frame.ok && frame.type === 'upsert' && frame.payload.id === 'ready') {
-    store.applyPush(frame.payload);
-  }
-  if (frame.ok && frame.type === 'delete' && frame.payload.id === 'ready') {
-    store.applyPush(frame.payload);
-  }
-});
-```
-
-## Rendering Pattern (List component)
-
-```js
-/** @param {{ store: ReturnType<typeof createSubscriptionIssueStore> }} props */
-export function ListView({ store }) {
-  let items = store.snapshot();
-
-  const un = store.subscribe(() => {
-    items = store.snapshot();
-    requestRender();
-  });
-
-  // framework-specific teardown
-  onUnmount(() => un());
-
-  return html`<ul>
-    ${items.map((it) => html`<li data-id=${it.id}>${it.title}</li>`)}
-  </ul>`;
-}
-```
-
-## Ordering and Identity
-
-- Default sort: priority asc, then `created_at` desc, then id asc.
-- When upserting, the store preserves object identity for existing ids by
-  mutating fields in place. This reduces unnecessary re‑renders.
-
-## Reconnects
-
-- On reconnect, repeat the subscribe‑list call. The server sends a fresh
-  `snapshot` with `revision: 1`. The store ignores stale envelopes using the
-  `revision` guard.