@rsktash/beads-ui 0.1.0

package/server/ws.js

@@ -0,0 +1,1309 @@
+/**
+ * @import { Server } from 'node:http'
+ * @import { RawData, WebSocket } from 'ws'
+ * @import { MessageType } from '../app/protocol.js'
+ */
+import path from 'node:path';
+import { WebSocketServer } from 'ws';
+import { isRequest, makeError, makeOk } from '../app/protocol.js';
+import { getGitUserName, runBd, runBdJson } from './bd.js';
+import { resolveWorkspaceDatabase } from './db.js';
+import {
+  addComment,
+  addDependency,
+  addLabel,
+  deleteIssue,
+  isDoltPoolReady,
+  queryComments,
+  queryIssueDetail,
+  removeDependency,
+  removeLabel,
+  updateIssueField
+} from './dolt-queries.js';
+import {
+  enrichIssueDetailParentContext,
+  fetchListForSubscription
+} from './list-adapters.js';
+import { debug } from './logging.js';
+import { getAvailableWorkspaces } from './registry-watcher.js';
+import { keyOf, registry } from './subscriptions.js';
+import { validateSubscribeListPayload } from './validators.js';
+
+const log = debug('ws');
+
+/**
+ * Run a mutation via SQL (with detail refetch) or bd CLI fallback, send the
+ * result to the client, and trigger a subscription refresh.
+ *
+ * Covers the common pattern: mutate → fetch updated issue → respond → refresh.
+ *
+ * @param {WebSocket} ws
+ * @param {any} req
+ * @param {string} detailId - Issue ID to fetch after mutation
+ * @param {() => Promise<{ ok: boolean, error?: { code: string, message: string } }>} sqlMutateFn
+ * @param {string[]} bdArgs - Arguments for the bd CLI fallback
+ */
+async function mutateAndRespond(ws, req, detailId, sqlMutateFn, bdArgs) {
+  if (isDoltPoolReady()) {
+    const upd = await sqlMutateFn();
+    if (!upd.ok) {
+      ws.send(JSON.stringify(makeError(req, upd.error.code, upd.error.message)));
+      return;
+    }
+    const detail = await queryIssueDetail(detailId);
+    if (!detail.ok) {
+      ws.send(JSON.stringify(makeError(req, detail.error.code, detail.error.message)));
+      return;
+    }
+    ws.send(JSON.stringify(makeOk(req, detail.item)));
+  } else {
+    const res = await runBd(bdArgs);
+    if (res.code !== 0) {
+      ws.send(JSON.stringify(makeError(req, 'bd_error', res.stderr || 'bd failed')));
+      return;
+    }
+    const shown = await runBdJson(['show', detailId, '--json']);
+    if (shown.code !== 0) {
+      ws.send(JSON.stringify(makeError(req, 'bd_error', shown.stderr || 'bd failed')));
+      return;
+    }
+    const detail =
+      shown.stdoutJson && typeof shown.stdoutJson === 'object' && !Array.isArray(shown.stdoutJson)
+        ? await enrichIssueDetailParentContext(
+          /** @type {Record<string, unknown>} */ (shown.stdoutJson),
+          { cwd: CURRENT_WORKSPACE?.root_dir }
+        )
+        : shown.stdoutJson;
+    ws.send(JSON.stringify(makeOk(req, detail)));
+  }
+  try { triggerMutationRefreshOnce(); } catch { /* ignore */ }
+}
+
+/**
+ * Debounced refresh scheduling for active list subscriptions.
+ * A trailing window coalesces rapid change bursts into a single refresh run.
+ */
+/** @type {ReturnType<typeof setTimeout> | null} */
+let REFRESH_TIMER = null;
+let REFRESH_DEBOUNCE_MS = 75;
+
+/**
+ * Mutation refresh window gate. When active, watcher-driven list refresh
+ * scheduling is suppressed. The gate resolves either when a watcher event
+ * arrives (via scheduleListRefresh) or when a timeout elapses, at which
+ * point a single refresh pass over all active list subscriptions is run.
+ */
+/**
+ * @typedef {Object} MutationGate
+ * @property {boolean} resolved
+ * @property {(reason: 'watcher'|'timeout') => void} resolve
+ * @property {ReturnType<typeof setTimeout>} timer
+ */
+/** @type {MutationGate | null} */
+let MUTATION_GATE = null;
+
+/**
+ * Start a mutation window gate if not already active. The gate resolves on the
+ * next watcher event or after `timeout_ms`, then triggers a single refresh run
+ * across all active list subscriptions. Watcher-driven refresh scheduling is
+ * suppressed during the window.
+ *
+ * Fire-and-forget; callers should not await this.
+ *
+ * @param {number} [timeout_ms]
+ */
+function triggerMutationRefreshOnce(timeout_ms = 500) {
+  if (MUTATION_GATE) {
+    return;
+  }
+  /** @type {(r: 'watcher'|'timeout') => void} */
+  let doResolve = () => {};
+  const p = new Promise((resolve) => {
+    doResolve = resolve;
+  });
+  MUTATION_GATE = {
+    resolved: false,
+    resolve: (reason) => {
+      if (!MUTATION_GATE || MUTATION_GATE.resolved) {
+        return;
+      }
+      MUTATION_GATE.resolved = true;
+      try {
+        doResolve(reason);
+      } catch {
+        // ignore resolve errors
+      }
+    },
+    timer: setTimeout(() => {
+      try {
+        MUTATION_GATE?.resolve('timeout');
+      } catch {
+        // ignore
+      }
+    }, timeout_ms)
+  };
+  MUTATION_GATE.timer.unref?.();
+
+  // After resolution, run a single refresh across active subs and clear gate
+  void p.then(async () => {
+    log('mutation window resolved → refresh active subs');
+    try {
+      await refreshAllActiveListSubscriptions();
+    } catch {
+      // ignore refresh errors
+    } finally {
+      try {
+        if (MUTATION_GATE?.timer) {
+          clearTimeout(MUTATION_GATE.timer);
+        }
+      } catch {
+        // ignore
+      }
+      MUTATION_GATE = null;
+    }
+  });
+}
+
+/**
+ * Collect unique active list subscription specs across all connected clients.
+ *
+ * @returns {Array<{ type: string, params?: Record<string,string|number|boolean> }>}
+ */
+function collectActiveListSpecs() {
+  /** @type {Array<{ type: string, params?: Record<string,string|number|boolean> }>} */
+  const specs = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  const wss = CURRENT_WSS;
+  if (!wss) {
+    return specs;
+  }
+  for (const ws of wss.clients) {
+    if (ws.readyState !== ws.OPEN) {
+      continue;
+    }
+    const s = ensureSubs(/** @type {any} */ (ws));
+    if (!s.list_subs) {
+      continue;
+    }
+    for (const { key, spec } of s.list_subs.values()) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        specs.push(spec);
+      }
+    }
+  }
+  return specs;
+}
+
+/**
+ * Run refresh for all active list subscription specs and publish deltas.
+ */
+async function refreshAllActiveListSubscriptions() {
+  const specs = collectActiveListSpecs();
+  // Run refreshes concurrently; locking is handled per key in the registry
+  await Promise.all(
+    specs.map(async (spec) => {
+      try {
+        await refreshAndPublish(spec);
+      } catch {
+        // ignore refresh errors per spec
+      }
+    })
+  );
+}
+
+/**
+ * Schedule a coalesced refresh of all active list subscriptions.
+ */
+export function scheduleListRefresh() {
+  // Suppress watcher-driven refreshes during an active mutation gate; resolve gate once
+  if (MUTATION_GATE) {
+    try {
+      MUTATION_GATE.resolve('watcher');
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  if (REFRESH_TIMER) {
+    clearTimeout(REFRESH_TIMER);
+  }
+  REFRESH_TIMER = setTimeout(() => {
+    REFRESH_TIMER = null;
+    // Fire and forget; callers don't await scheduling
+    void refreshAllActiveListSubscriptions();
+  }, REFRESH_DEBOUNCE_MS);
+  REFRESH_TIMER.unref?.();
+}
+
+/**
+ * @typedef {{
+ *   show_id?: string | null,
+ *   list_subs?: Map<string, { key: string, spec: { type: string, params?: Record<string, string | number | boolean> } }>,
+ *   list_revisions?: Map<string, number>
+ * }} ConnectionSubs
+ */
+
+/** @type {WeakMap<WebSocket, any>} */
+const SUBS = new WeakMap();
+
+/** @type {WebSocketServer | null} */
+let CURRENT_WSS = null;
+
+/**
+ * Current workspace configuration.
+ *
+ * @type {{ root_dir: string, db_path: string } | null}
+ */
+let CURRENT_WORKSPACE = null;
+
+/**
+ * Reference to the database watcher for rebinding on workspace change.
+ *
+ * @type {{ rebind: (opts?: { root_dir?: string }) => void, path: string } | null}
+ */
+let DB_WATCHER = null;
+
+/**
+ * Get or initialize the subscription state for a socket.
+ *
+ * @param {WebSocket} ws
+ * @returns {any}
+ */
+function ensureSubs(ws) {
+  let s = SUBS.get(ws);
+  if (!s) {
+    s = {
+      show_id: null,
+      list_subs: new Map(),
+      list_revisions: new Map()
+    };
+    SUBS.set(ws, s);
+  }
+  return s;
+}
+
+/**
+ * Get next monotonically increasing revision for a subscription key on this connection.
+ *
+ * @param {WebSocket} ws
+ * @param {string} key
+ */
+/**
+ * @param {WebSocket} ws
+ * @param {string} key
+ */
+function nextListRevision(ws, key) {
+  const s = ensureSubs(ws);
+  const m = s.list_revisions || new Map();
+  s.list_revisions = m;
+  const prev = m.get(key) || 0;
+  const next = prev + 1;
+  m.set(key, next);
+  return next;
+}
+
+/**
+ * Emit per-subscription envelopes to a specific client id on a socket.
+ * Helpers for snapshot / upsert / delete.
+ */
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {Array<Record<string, unknown>>} issues
+ * @param {number} [total] - Total count for paginated queries
+ */
+function emitSubscriptionSnapshot(ws, client_id, key, issues, total) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: /** @type {const} */ ('snapshot'),
+    id: client_id,
+    revision,
+    issues,
+    ...(typeof total === 'number' ? { total } : {})
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('snapshot'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch (err) {
+    log('emit snapshot send failed key=%s id=%s: %o', key, client_id, err);
+  }
+}
+
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {Record<string, unknown>} issue
+ */
+function emitSubscriptionUpsert(ws, client_id, key, issue) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: 'upsert',
+    id: client_id,
+    revision,
+    issue
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('upsert'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch (err) {
+    log('emit upsert send failed key=%s id=%s: %o', key, client_id, err);
+  }
+}
+
+/**
+ * @param {WebSocket} ws
+ * @param {string} client_id
+ * @param {string} key
+ * @param {string} issue_id
+ */
+function emitSubscriptionDelete(ws, client_id, key, issue_id) {
+  const revision = nextListRevision(ws, key);
+  const payload = {
+    type: 'delete',
+    id: client_id,
+    revision,
+    issue_id
+  };
+  const msg = JSON.stringify({
+    id: `evt-${Date.now()}`,
+    ok: true,
+    type: /** @type {MessageType} */ ('delete'),
+    payload
+  });
+  try {
+    ws.send(msg);
+  } catch (err) {
+    log('emit delete send failed key=%s id=%s: %o', key, client_id, err);
+  }
+}
+
+// issues-changed removed in v2: detail and lists are pushed via subscriptions
+
+/**
+ * Refresh a subscription spec: fetch via adapter, apply to registry and emit
+ * per-subscription full-issue envelopes to subscribers. Serialized per key.
+ *
+ * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
+ */
+async function refreshAndPublish(spec) {
+  const key = keyOf(spec);
+  await registry.withKeyLock(key, async () => {
+    const res = await fetchListForSubscription(spec, {
+      cwd: CURRENT_WORKSPACE?.root_dir
+    });
+    if (!res.ok) {
+      log('refresh failed for %s: %s %o', key, res.error.message, res.error);
+      return;
+    }
+    const items = applyClosedIssuesFilter(spec, res.items);
+    const prev_size = registry.get(key)?.itemsById.size || 0;
+    const delta = registry.applyItems(key, items);
+    const entry = registry.get(key);
+    if (!entry || entry.subscribers.size === 0) {
+      return;
+    }
+    /** @type {Map<string, any>} */
+    const by_id = new Map();
+    for (const it of items) {
+      if (it && typeof it.id === 'string') {
+        by_id.set(it.id, it);
+      }
+    }
+    for (const ws of entry.subscribers) {
+      if (ws.readyState !== ws.OPEN) continue;
+      const s = ensureSubs(ws);
+      const subs = s.list_subs || new Map();
+      /** @type {string[]} */
+      const client_ids = [];
+      for (const [cid, v] of subs.entries()) {
+        if (v.key === key) client_ids.push(cid);
+      }
+      if (client_ids.length === 0) continue;
+      if (prev_size === 0) {
+        for (const cid of client_ids) {
+          emitSubscriptionSnapshot(ws, cid, key, items);
+        }
+        continue;
+      }
+      for (const cid of client_ids) {
+        for (const id of [...delta.added, ...delta.updated]) {
+          const issue = by_id.get(id);
+          if (issue) {
+            emitSubscriptionUpsert(ws, cid, key, issue);
+          }
+        }
+        for (const id of delta.removed) {
+          emitSubscriptionDelete(ws, cid, key, id);
+        }
+      }
+    }
+  });
+}
+
+/**
+ * Apply pre-diff filtering for closed-issues lists based on spec.params.since (epoch ms).
+ *
+ * @param {{ type: string, params?: Record<string, string|number|boolean> }} spec
+ * @param {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
+ */
+function applyClosedIssuesFilter(spec, items) {
+  if (String(spec.type) !== 'closed-issues') {
+    return items;
+  }
+  const p = spec.params || {};
+  const since = typeof p.since === 'number' ? p.since : 0;
+  if (!Number.isFinite(since) || since <= 0) {
+    return items;
+  }
+  /** @type {typeof items} */
+  const out = [];
+  for (const it of items) {
+    const ca = it.closed_at;
+    if (typeof ca === 'number' && Number.isFinite(ca) && ca >= since) {
+      out.push(it);
+    }
+  }
+  return out;
+}
+
+/**
+ * Attach a WebSocket server to an existing HTTP server.
+ *
+ * @param {Server} http_server
+ * @param {{ path?: string, heartbeat_ms?: number, refresh_debounce_ms?: number, root_dir?: string, watcher?: { rebind: (opts?: { root_dir?: string }) => void, path: string } }} [options]
+ * @returns {{ wss: WebSocketServer, broadcast: (type: MessageType, payload?: unknown) => void, scheduleListRefresh: () => void, setWorkspace: (root_dir: string) => { changed: boolean, workspace: { root_dir: string, db_path: string } } }}
+ */
+export function attachWsServer(http_server, options = {}) {
+  const ws_path = options.path || '/ws';
+
+  // Initialize workspace state
+  const initial_root = options.root_dir || process.cwd();
+  const initial_db = resolveWorkspaceDatabase({ cwd: initial_root });
+  CURRENT_WORKSPACE = {
+    root_dir: initial_root,
+    db_path: initial_db.path
+  };
+
+  if (options.watcher) {
+    DB_WATCHER = options.watcher;
+  }
+  const heartbeat_ms = options.heartbeat_ms ?? 30000;
+  if (typeof options.refresh_debounce_ms === 'number') {
+    const n = options.refresh_debounce_ms;
+    if (Number.isFinite(n) && n >= 0) {
+      REFRESH_DEBOUNCE_MS = n;
+    }
+  }
+
+  const wss = new WebSocketServer({ server: http_server, path: ws_path });
+  CURRENT_WSS = wss;
+
+  // Heartbeat: track if client answered the last ping
+  wss.on('connection', (ws) => {
+    log('client connected');
+    // @ts-expect-error add marker property
+    ws.isAlive = true;
+
+    // Initialize subscription state for this connection
+    ensureSubs(ws);
+
+    ws.on('pong', () => {
+      // @ts-expect-error marker
+      ws.isAlive = true;
+    });
+
+    ws.on('message', (data) => {
+      handleMessage(ws, data);
+    });
+
+    ws.on('close', () => {
+      try {
+        registry.onDisconnect(ws);
+      } catch {
+        // ignore cleanup errors
+      }
+    });
+  });
+
+  const interval = setInterval(() => {
+    for (const ws of wss.clients) {
+      // @ts-expect-error marker
+      if (ws.isAlive === false) {
+        ws.terminate();
+        continue;
+      }
+      // @ts-expect-error marker
+      ws.isAlive = false;
+      ws.ping();
+    }
+  }, heartbeat_ms);
+
+  interval.unref?.();
+
+  wss.on('close', () => {
+    clearInterval(interval);
+  });
+
+  /**
+   * Broadcast a server-initiated event to all open clients.
+   *
+   * @param {MessageType} type
+   * @param {unknown} [payload]
+   */
+  function broadcast(type, payload) {
+    const msg = JSON.stringify({
+      id: `evt-${Date.now()}`,
+      ok: true,
+      type,
+      payload
+    });
+    for (const ws of wss.clients) {
+      if (ws.readyState === ws.OPEN) {
+        ws.send(msg);
+      }
+    }
+  }
+
+  /**
+   * Change the current workspace and rebind the database watcher.
+   *
+   * @param {string} new_root_dir - Absolute path to the new workspace root.
+   * @returns {{ changed: boolean, workspace: { root_dir: string, db_path: string } }}
+   */
+  function setWorkspace(new_root_dir) {
+    const resolved_root = path.resolve(new_root_dir);
+    const new_db = resolveWorkspaceDatabase({ cwd: resolved_root });
+    const old_path = CURRENT_WORKSPACE?.db_path || '';
+
+    CURRENT_WORKSPACE = {
+      root_dir: resolved_root,
+      db_path: new_db.path
+    };
+
+    const changed = new_db.path !== old_path;
+
+    if (changed) {
+      log('workspace changed: %s → %s', old_path, new_db.path);
+
+      // Rebind the database watcher to the new workspace
+      if (DB_WATCHER) {
+        DB_WATCHER.rebind({ root_dir: resolved_root });
+      }
+
+      // Clear existing registry entries and refresh all subscriptions
+      registry.clear();
+
+      // Broadcast workspace-changed event to all clients
+      broadcast('workspace-changed', CURRENT_WORKSPACE);
+
+      // Schedule refresh of all active list subscriptions
+      scheduleListRefresh();
+    }
+
+    return { changed, workspace: CURRENT_WORKSPACE };
+  }
+
+  return {
+    wss,
+    broadcast,
+    scheduleListRefresh,
+    setWorkspace
+    // v2: list subscription refresh handles updates
+  };
+}
+
+/**
+ * Handle an incoming message frame and respond to the same socket.
+ *
+ * @param {WebSocket} ws
+ * @param {RawData} data
+ */
+export async function handleMessage(ws, data) {
+  /** @type {unknown} */
+  let json;
+  try {
+    json = JSON.parse(data.toString());
+  } catch {
+    const reply = {
+      id: 'unknown',
+      ok: false,
+      type: 'bad-json',
+      error: { code: 'bad_json', message: 'Invalid JSON' }
+    };
+    ws.send(JSON.stringify(reply));
+    return;
+  }
+
+  if (!isRequest(json)) {
+    log('invalid request');
+    const reply = {
+      id: 'unknown',
+      ok: false,
+      type: 'bad-request',
+      error: { code: 'bad_request', message: 'Invalid request envelope' }
+    };
+    ws.send(JSON.stringify(reply));
+    return;
+  }
+
+  const req = json;
+
+  // Dispatch known types here as we implement them. For now, only a ping utility.
+  if (req.type === /** @type {MessageType} */ ('ping')) {
+    ws.send(JSON.stringify(makeOk(req, { ts: Date.now() })));
+    return;
+  }
+
+  // subscribe-list: payload { id: string, type: string, params?: object }
+  if (req.type === 'subscribe-list') {
+    const payload_id = /** @type {any} */ (req.payload)?.id || '';
+    log('subscribe-list %s', payload_id);
+    const validation = validateSubscribeListPayload(
+      /** @type {any} */ (req.payload || {})
+    );
+    if (!validation.ok) {
+      ws.send(
+        JSON.stringify(makeError(req, validation.code, validation.message))
+      );
+      return;
+    }
+    const client_id = validation.id;
+    const spec = validation.spec;
+    const key = keyOf(spec);
+
+    /**
+     * Reply with an error and avoid attaching the subscription when
+     * initialization fails.
+     *
+     * @param {string} code
+     * @param {string} message
+     * @param {Record<string, unknown>|undefined} details
+     */
+    const replyWithError = (code, message, details = undefined) => {
+      ws.send(JSON.stringify(makeError(req, code, message, details)));
+    };
+
+    /** @type {Awaited<ReturnType<typeof fetchListForSubscription>> | null} */
+    let initial = null;
+    try {
+      initial = await fetchListForSubscription(spec, {
+        cwd: CURRENT_WORKSPACE?.root_dir
+      });
+    } catch (err) {
+      log('subscribe-list snapshot error for %s: %o', key, err);
+      const message =
+        (err && /** @type {any} */ (err).message) || 'Failed to load list';
+      replyWithError('bd_error', String(message), { key });
+      return;
+    }
+
+    if (!initial.ok) {
+      log(
+        'initial snapshot failed for %s: %s %o',
+        key,
+        initial.error.message,
+        initial.error
+      );
+      const details = { ...(initial.error.details || {}), key };
+      replyWithError(initial.error.code, initial.error.message, details);
+      return;
+    }
+
+    const s = ensureSubs(ws);
+    const { key: attached_key } = registry.attach(spec, ws);
+    s.list_subs?.set(client_id, { key: attached_key, spec });
+
+    try {
+      await registry.withKeyLock(attached_key, async () => {
+        const items = applyClosedIssuesFilter(
+          spec,
+          initial ? initial.items : []
+        );
+        void registry.applyItems(attached_key, items);
+        emitSubscriptionSnapshot(ws, client_id, attached_key, items, initial?.total);
+      });
+    } catch (err) {
+      log('subscribe-list snapshot error for %s: %o', attached_key, err);
+      s.list_subs?.delete(client_id);
+      try {
+        registry.detach(spec, ws);
+      } catch {
+        // ignore detach errors
+      }
+      replyWithError('bd_error', 'Failed to publish snapshot', { key });
+      return;
+    }
+
+    ws.send(JSON.stringify(makeOk(req, { id: client_id, key: attached_key })));
+    return;
+  }
+
+  // unsubscribe-list: payload { id: string }
+  if (req.type === 'unsubscribe-list') {
+    log('unsubscribe-list %s', /** @type {any} */ (req.payload)?.id || '');
+    const { id: client_id } = /** @type {any} */ (req.payload || {});
+    if (typeof client_id !== 'string' || client_id.length === 0) {
+      ws.send(
+        JSON.stringify(
+          makeError(req, 'bad_request', 'payload.id must be a non-empty string')
+        )
+      );
+      return;
+    }
+    const s = ensureSubs(ws);
+    const sub = s.list_subs?.get(client_id) || null;
+    let removed = false;
+    if (sub) {
+      try {
+        removed = registry.detach(sub.spec, ws);
+      } catch {
+        removed = false;
+      }
+      s.list_subs?.delete(client_id);
+    }
+    ws.send(
+      JSON.stringify(
+        makeOk(req, {
+          id: client_id,
+          unsubscribed: removed
+        })
+      )
+    );
+    return;
+  }
+
+  // Removed: subscribe-updates and subscribe-issues. No-ops in v2.
+
+  // list-issues and epic-status were removed in favor of push-only subscriptions
+
+  // Removed: show-issue. Details flow is push-only via `subscribe-list { type: 'issue-detail' }`.
+
+  // type updates are not exposed via UI; no handler
+
+  // update-assignee
+  if (req.type === 'update-assignee') {
+    const { id, assignee } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof assignee !== 'string'
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { id: string, assignee: string }'
+          )
+        )
+      );
+      return;
+    }
+    await mutateAndRespond(
+      ws, req, id,
+      () => updateIssueField(id, 'assignee', assignee || null),
+      ['update', id, '--assignee', assignee]
+    );
+    return;
+  }
+
+  // update-status
+  if (req.type === 'update-status') {
+    log('update-status');
+    const { id, status } = /** @type {any} */ (req.payload);
+    const allowed = new Set(['open', 'in_progress', 'closed']);
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof status !== 'string' ||
+      !allowed.has(status)
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            "payload requires { id: string, status: 'open'|'in_progress'|'closed' }"
+          )
+        )
+      );
+      return;
+    }
+    await mutateAndRespond(
+      ws, req, id,
+      () => updateIssueField(id, 'status', status),
+      ['update', id, '--status', status]
+    );
+    return;
+  }
+
+  // update-priority
+  if (req.type === 'update-priority') {
+    log('update-priority');
+    const { id, priority } = /** @type {any} */ (req.payload);
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof priority !== 'number' ||
+      priority < 0 ||
+      priority > 4
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { id: string, priority: 0..4 }'
+          )
+        )
+      );
+      return;
+    }
+    await mutateAndRespond(
+      ws, req, id,
+      () => updateIssueField(id, 'priority', priority),
+      ['update', id, '--priority', String(priority)]
+    );
+    return;
+  }
+
+  // edit-text
+  if (req.type === 'edit-text') {
+    log('edit-text');
+    const { id, field, value } = /** @type {any} */ (req.payload);
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      (field !== 'title' &&
+        field !== 'description' &&
+        field !== 'acceptance' &&
+        field !== 'notes' &&
+        field !== 'design') ||
+      typeof value !== 'string'
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            "payload requires { id: string, field: 'title'|'description'|'acceptance'|'notes'|'design', value: string }"
+          )
+        )
+      );
+      return;
+    }
+    const SQL_FIELD_MAP = /** @type {Record<string, string>} */ ({
+      title: 'title',
+      description: 'description',
+      acceptance: 'acceptance_criteria',
+      notes: 'notes',
+      design: 'design'
+    });
+    const BD_FLAG_MAP = /** @type {Record<string, string>} */ ({
+      title: '--title',
+      description: '--description',
+      acceptance: '--acceptance-criteria',
+      notes: '--notes',
+      design: '--design'
+    });
+
+    await mutateAndRespond(
+      ws, req, id,
+      () => updateIssueField(id, SQL_FIELD_MAP[field], value),
+      ['update', id, BD_FLAG_MAP[field], value]
+    );
+    return;
+  }
+
+  // create-issue
+  if (req.type === 'create-issue') {
+    log('create-issue');
+    const { title, type, priority, description } = /** @type {any} */ (
+      req.payload || {}
+    );
+    if (typeof title !== 'string' || title.length === 0) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { title: string, ... }'
+          )
+        )
+      );
+      return;
+    }
+    const args = ['create', title];
+    if (
+      typeof type === 'string' &&
+      (type === 'bug' ||
+        type === 'feature' ||
+        type === 'task' ||
+        type === 'epic' ||
+        type === 'chore')
+    ) {
+      args.push('-t', type);
+    }
+    if (typeof priority === 'number' && priority >= 0 && priority <= 4) {
+      args.push('-p', String(priority));
+    }
+    if (typeof description === 'string' && description.length > 0) {
+      args.push('-d', description);
+    }
+    const res = await runBd(args);
+    if (res.code !== 0) {
+      ws.send(
+        JSON.stringify(makeError(req, 'bd_error', res.stderr || 'bd failed'))
+      );
+      return;
+    }
+    // Reply with a minimal ack
+    ws.send(JSON.stringify(makeOk(req, { created: true })));
+    // Refresh active subscriptions once (watcher or timeout)
+    try {
+      triggerMutationRefreshOnce();
+    } catch {
+      // ignore
+    }
+    return;
+  }
+
+  // dep-add: payload { a: string, b: string, view_id?: string }
+  if (req.type === 'dep-add') {
+    const { a, b, view_id } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof a !== 'string' ||
+      a.length === 0 ||
+      typeof b !== 'string' ||
+      b.length === 0
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { a: string, b: string }'
+          )
+        )
+      );
+      return;
+    }
+    const id = typeof view_id === 'string' && view_id.length > 0 ? view_id : a;
+    await mutateAndRespond(
+      ws, req, id,
+      () => addDependency(a, b),
+      ['dep', 'add', a, b]
+    );
+    return;
+  }
+
+  // dep-remove: payload { a: string, b: string, view_id?: string }
+  if (req.type === 'dep-remove') {
+    const { a, b, view_id } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof a !== 'string' ||
+      a.length === 0 ||
+      typeof b !== 'string' ||
+      b.length === 0
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { a: string, b: string }'
+          )
+        )
+      );
+      return;
+    }
+    const id = typeof view_id === 'string' && view_id.length > 0 ? view_id : a;
+    await mutateAndRespond(
+      ws, req, id,
+      () => removeDependency(a, b),
+      ['dep', 'remove', a, b]
+    );
+    return;
+  }
+
+  // label-add: payload { id: string, label: string }
+  if (req.type === 'label-add') {
+    const { id, label } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof label !== 'string' ||
+      label.trim().length === 0
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { id: string, label: non-empty string }'
+          )
+        )
+      );
+      return;
+    }
+    await mutateAndRespond(
+      ws, req, id,
+      () => addLabel(id, label.trim()),
+      ['label', 'add', id, label.trim()]
+    );
+    return;
+  }
+
+  // label-remove: payload { id: string, label: string }
+  if (req.type === 'label-remove') {
+    const { id, label } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof label !== 'string' ||
+      label.trim().length === 0
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { id: string, label: non-empty string }'
+          )
+        )
+      );
+      return;
+    }
+    await mutateAndRespond(
+      ws, req, id,
+      () => removeLabel(id, label.trim()),
+      ['label', 'remove', id, label.trim()]
+    );
+    return;
+  }
+
+  // get-comments: payload { id: string }
+  if (req.type === 'get-comments') {
+    const { id } = /** @type {any} */ (req.payload || {});
+    if (typeof id !== 'string' || id.length === 0) {
+      ws.send(
+        JSON.stringify(
+          makeError(req, 'bad_request', 'payload requires { id: string }')
+        )
+      );
+      return;
+    }
+    if (isDoltPoolReady()) {
+      const res = await queryComments(id);
+      if (!res.ok) {
+        ws.send(JSON.stringify(makeError(req, res.error.code, res.error.message)));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, res.items)));
+    } else {
+      const res = await runBdJson(['comments', id, '--json']);
+      if (res.code !== 0) {
+        ws.send(JSON.stringify(makeError(req, 'bd_error', res.stderr || 'bd failed')));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, res.stdoutJson || [])));
+    }
+    return;
+  }
+
+  // add-comment: payload { id: string, text: string }
+  if (req.type === 'add-comment') {
+    const { id, text } = /** @type {any} */ (req.payload || {});
+    if (
+      typeof id !== 'string' ||
+      id.length === 0 ||
+      typeof text !== 'string' ||
+      text.trim().length === 0
+    ) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { id: string, text: non-empty string }'
+          )
+        )
+      );
+      return;
+    }
+
+    const author = await getGitUserName();
+
+    if (isDoltPoolReady()) {
+      const upd = await addComment(id, text.trim(), author || 'anonymous');
+      if (!upd.ok) {
+        ws.send(JSON.stringify(makeError(req, upd.error.code, upd.error.message)));
+        return;
+      }
+      const res = await queryComments(id);
+      if (!res.ok) {
+        ws.send(JSON.stringify(makeError(req, res.error.code, res.error.message)));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, res.items)));
+    } else {
+      const args = ['comment', id, text.trim()];
+      if (author) {
+        args.push('--author', author);
+      }
+
+      const res = await runBd(args);
+      if (res.code !== 0) {
+        ws.send(JSON.stringify(makeError(req, 'bd_error', res.stderr || 'bd failed')));
+        return;
+      }
+
+      const comments = await runBdJson(['comments', id, '--json']);
+      if (comments.code !== 0) {
+        ws.send(JSON.stringify(makeError(req, 'bd_error', comments.stderr || 'bd failed')));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, comments.stdoutJson || [])));
+    }
+    return;
+  }
+
+  // delete-issue: payload { id: string }
+  if (req.type === 'delete-issue') {
+    const { id } = /** @type {any} */ (req.payload || {});
+    if (typeof id !== 'string' || id.length === 0) {
+      ws.send(
+        JSON.stringify(
+          makeError(req, 'bad_request', 'payload requires { id: string }')
+        )
+      );
+      return;
+    }
+    if (isDoltPoolReady()) {
+      const upd = await deleteIssue(id);
+      if (!upd.ok) {
+        ws.send(JSON.stringify(makeError(req, upd.error.code, upd.error.message)));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, { deleted: true, id })));
+    } else {
+      const res = await runBd(['delete', id, '--force']);
+      if (res.code !== 0) {
+        ws.send(JSON.stringify(makeError(req, 'bd_error', res.stderr || 'bd delete failed')));
+        return;
+      }
+      ws.send(JSON.stringify(makeOk(req, { deleted: true, id })));
+    }
+    try {
+      triggerMutationRefreshOnce();
+    } catch {
+      // ignore
+    }
+    return;
+  }
+
+  // list-workspaces: returns all available workspaces from the registry
+  if (req.type === 'list-workspaces') {
+    log('list-workspaces');
+    const workspaces = getAvailableWorkspaces();
+    ws.send(
+      JSON.stringify(
+        makeOk(req, {
+          workspaces,
+          current: CURRENT_WORKSPACE
+        })
+      )
+    );
+    return;
+  }
+
+  // get-workspace: returns the current workspace
+  if (req.type === 'get-workspace') {
+    log('get-workspace');
+    ws.send(JSON.stringify(makeOk(req, CURRENT_WORKSPACE)));
+    return;
+  }
+
+  // set-workspace: payload { path: string }
+  if (req.type === 'set-workspace') {
+    log('set-workspace');
+    const { path: workspace_path } = /** @type {any} */ (req.payload || {});
+    if (typeof workspace_path !== 'string' || workspace_path.length === 0) {
+      ws.send(
+        JSON.stringify(
+          makeError(
+            req,
+            'bad_request',
+            'payload requires { path: string } (absolute workspace path)'
+          )
+        )
+      );
+      return;
+    }
+
+    // Resolve and validate the path
+    const resolved = path.resolve(workspace_path);
+
+    // Update workspace (this will rebind watcher, clear registry, broadcast change)
+    const new_db = resolveWorkspaceDatabase({ cwd: resolved });
+    const old_path = CURRENT_WORKSPACE?.db_path || '';
+
+    CURRENT_WORKSPACE = {
+      root_dir: resolved,
+      db_path: new_db.path
+    };
+
+    const changed = new_db.path !== old_path;
+
+    if (changed) {
+      log(
+        'workspace changed via set-workspace: %s → %s',
+        old_path,
+        new_db.path
+      );
+
+      // Rebind the database watcher
+      if (DB_WATCHER) {
+        DB_WATCHER.rebind({ root_dir: resolved });
+      }
+
+      // Clear existing registry entries
+      registry.clear();
+
+      // Schedule refresh of all active list subscriptions
+      scheduleListRefresh();
+    }
+
+    ws.send(
+      JSON.stringify(
+        makeOk(req, {
+          changed,
+          workspace: CURRENT_WORKSPACE
+        })
+      )
+    );
+    return;
+  }
+
+  // Unknown type
+  const err = makeError(
+    req,
+    'unknown_type',
+    `Unknown message type: ${req.type}`
+  );
+  ws.send(JSON.stringify(err));
+}