beads-ui 0.3.0 → 0.4.0

package/app/protocol.js

@@ -1,196 +0,0 @@
-/**
- * Protocol definitions for beads-ui WebSocket communication.
- *
- * Conventions
- * - All messages are JSON objects.
- * - Client → Server uses RequestEnvelope.
- * - Server → Client uses ReplyEnvelope.
- * - Every request is correlated by `id` in replies.
- * - Server can also send unsolicited events (e.g., subscription `snapshot`).
- */
-
-/** @typedef {'list-issues'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'|'subscribe-list'|'unsubscribe-list'|'snapshot'|'upsert'|'delete'} MessageType */
-
-/**
- * @typedef {Object} RequestEnvelope
- * @property {string} id - Unique id to correlate request/response.
- * @property {MessageType} type - Message type.
- * @property {unknown} [payload] - Message payload.
- */
-
-/**
- * @typedef {Object} ErrorObject
- * @property {string} code - Stable error code.
- * @property {string} message - Human-readable message.
- * @property {unknown} [details] - Optional extra info for debugging.
- */
-
-/**
- * @typedef {Object} ReplyEnvelope
- * @property {string} id - Correlates to the originating request.
- * @property {boolean} ok - True when request succeeded; false on error.
- * @property {MessageType} type - Echoes request type (or event type).
- * @property {unknown} [payload] - Response payload.
- * @property {ErrorObject} [error] - Present when ok=false.
- */
-
-/** @type {MessageType[]} */
-export const MESSAGE_TYPES = /** @type {const} */ ([
-  'list-issues',
-  'update-status',
-  'edit-text',
-  'update-priority',
-  'create-issue',
-  'list-ready',
-  'dep-add',
-  'dep-remove',
-  'epic-status',
-  'update-assignee',
-  'label-add',
-  'label-remove',
-  'subscribe-list',
-  'unsubscribe-list',
-  // vNext per-subscription full-issue push events
-  'snapshot',
-  'upsert',
-  'delete'
-]);
-
-/**
- * Generate a lexically sortable request id.
- * @returns {string}
- */
-export function nextId() {
-  const now = Date.now().toString(36);
-  const rand = Math.random().toString(36).slice(2, 8);
-  return `${now}-${rand}`;
-}
-
-/**
- * Create a request envelope.
- * @param {MessageType} type - Message type.
- * @param {unknown} [payload] - Message payload.
- * @param {string} [id] - Optional id; generated if omitted.
- * @returns {RequestEnvelope}
- */
-export function makeRequest(type, payload, id = nextId()) {
-  return { id, type, payload };
-}
-
-/**
- * Create a successful reply envelope for a given request.
- * @param {RequestEnvelope} req - Original request.
- * @param {unknown} [payload] - Reply payload.
- * @returns {ReplyEnvelope}
- */
-export function makeOk(req, payload) {
-  return { id: req.id, ok: true, type: req.type, payload };
-}
-
-/**
- * Create an error reply envelope for a given request.
- * @param {RequestEnvelope} req - Original request.
- * @param {string} code - Error code.
- * @param {string} message - Error message.
- * @param {unknown} [details] - Extra details.
- * @returns {ReplyEnvelope}
- */
-export function makeError(req, code, message, details) {
-  return {
-    id: req.id,
-    ok: false,
-    type: req.type,
-    error: { code, message, details }
-  };
-}
-
-/**
- * Check if a value is a plain object.
- * @param {unknown} value
- * @returns {value is Record<string, unknown>}
- */
-function isRecord(value) {
-  return !!value && typeof value === 'object' && !Array.isArray(value);
-}
-
-/**
- * Type guard for MessageType values.
- * @param {unknown} value
- * @returns {value is MessageType}
- */
-export function isMessageType(value) {
-  return (
-    typeof value === 'string' &&
-    MESSAGE_TYPES.includes(/** @type {MessageType} */ (value))
-  );
-}
-
-/**
- * Type guard for RequestEnvelope.
- * @param {unknown} value
- * @returns {value is RequestEnvelope}
- */
-export function isRequest(value) {
-  if (!isRecord(value)) {
-    return false;
-  }
-  return (
-    typeof value.id === 'string' &&
-    typeof value.type === 'string' &&
-    (value.payload === undefined || 'payload' in value)
-  );
-}
-
-/**
- * Type guard for ReplyEnvelope.
- * @param {unknown} value
- * @returns {value is ReplyEnvelope}
- */
-export function isReply(value) {
-  if (!isRecord(value)) {
-    return false;
-  }
-  if (
-    typeof value.id !== 'string' ||
-    typeof value.ok !== 'boolean' ||
-    !isMessageType(value.type)
-  ) {
-    return false;
-  }
-  if (value.ok === false) {
-    const err = value.error;
-    if (
-      !isRecord(err) ||
-      typeof err.code !== 'string' ||
-      typeof err.message !== 'string'
-    ) {
-      return false;
-    }
-  }
-  return true;
-}
-
-/**
- * Normalize and validate an incoming JSON value as a RequestEnvelope.
- * Throws a user-friendly error if invalid.
- * @param {unknown} json
- * @returns {RequestEnvelope}
- */
-export function decodeRequest(json) {
-  if (!isRequest(json)) {
-    throw new Error('Invalid request envelope');
-  }
-  return json;
-}
-
-/**
- * Normalize and validate an incoming JSON value as a ReplyEnvelope.
- * @param {unknown} json
- * @returns {ReplyEnvelope}
- */
-export function decodeReply(json) {
-  if (!isReply(json)) {
-    throw new Error('Invalid reply envelope');
-  }
-  return json;
-}

package/app/protocol.md

@@ -1,66 +0,0 @@
-# beads-ui WebSocket Protocol (v2.0.0)
-
-Note (2025-10-26)
-
-- The server no longer implements legacy read RPCs `list-issues` and
-  `epic-status`. Clients must use the push-only protocol described in
-  `docs/protocol/issues-push-v2.md` (subscribe-list with per-subscription events
-  snapshot/upsert/delete). The shapes below are retained for historical
-  reference of v1.
-
-This document defines the JSON messages exchanged between the browser client and
-the local server.
-
-- Transport: single WebSocket connection
-- Encoding: JSON text frames
-- Correlation: all request/response pairs share the same `id`
-
-## Envelope Shapes
-
-- RequestEnvelope: `{ id: string, type: string, payload?: any }`
-- ReplyEnvelope:
-  `{ id: string, ok: boolean, type: string, payload?: any, error?: { code: string, message: string, details?: any } }`
-
-Server may send unsolicited events (e.g., subscription
-`snapshot`/`upsert`/`delete`) using the ReplyEnvelope shape with `ok: true` and
-a generated `id`.
-
-## Message Types
-
-- Removed in v2: `list-issues` (use subscriptions + push stores)
-- `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 }`
-- `create-issue` payload:
-  `{ title: string, type?: 'bug'|'feature'|'task'|'epic'|'chore', priority?: 0|1|2|3|4, description?: string }`
-- `list-ready` payload: `{}`
-- Removed in v2: `subscribe-updates` and the `issues-changed` event. All list
-  and detail updates flow via per-subscription push envelopes
-  (`snapshot`/`upsert`/`delete`).
-- `dep-add` payload: `{ a: string, b: string, view_id?: string }` where `a`
-  depends on `b` (i.e., `a` is blocked by `b`). Reply payload is the updated
-  issue for `view_id` (or `a` when omitted).
-- `dep-remove` payload: `{ a: string, b: string, view_id?: string }` removing
-  the `a` depends on `b` link. Reply payload is the updated issue for `view_id`
-  (or `a`).
-
-## Mapping to `bd` CLI
-
-- Removed in v2: `list-issues` → use subscriptions and push
-  (`docs/protocol/issues-push-v2.md`)
-- `update-status` → `bd update <id> --status <status>`
-- `edit-text` → `bd update <id> --title <t>` or `--description <d>` or
-  `--acceptance-criteria <a>` or `--notes <n>` or `--design <z>`
-- `update-priority` → `bd update <id> --priority <n>`
-- `create-issue` → `bd create "title" -t <type> -p <prio> -d "desc"`
-- `list-ready` → `bd ready --json`
-
-## Errors
-
-Errors follow the shape `{ code, message, details? }`. Common codes:
-
-- `bad_request` – malformed payload or unknown type
-- `not_found` – entity not found (e.g., issue id)
-- `bd_error` – underlying `bd` command failed

package/app/router.js

@@ -1,114 +0,0 @@
-import { issueHashFor } from './utils/issue-url.js';
-
-/**
- * Hash-based router for tabs (issues/epics/board) and deep-linked issue ids.
- */
-
-/**
- * Parse an application hash and extract the selected issue id.
- * Supports canonical form "#/(issues|epics|board)?issue=<id>" and legacy
- * "#/issue/<id>" which we will rewrite to the canonical form.
- * @param {string} hash
- * @returns {string | null}
- */
-export function parseHash(hash) {
-  const h = String(hash || '');
-  // Extract the fragment sans leading '#'
-  const frag = h.startsWith('#') ? h.slice(1) : h;
-  const qIndex = frag.indexOf('?');
-  const query = qIndex >= 0 ? frag.slice(qIndex + 1) : '';
-  if (query) {
-    const params = new URLSearchParams(query);
-    const id = params.get('issue');
-    if (id) {
-      return decodeURIComponent(id);
-    }
-  }
-  // Legacy pattern: #/issue/<id>
-  const m = /^\/issue\/([^\s?#]+)/.exec(frag);
-  return m && m[1] ? decodeURIComponent(m[1]) : null;
-}
-
-/**
- * Parse the current view from hash.
- * @param {string} hash
- * @returns {'issues'|'epics'|'board'}
- */
-export function parseView(hash) {
-  const h = String(hash || '');
-  if (/^#\/epics(\b|\/|$)/.test(h)) {
-    return 'epics';
-  }
-  if (/^#\/board(\b|\/|$)/.test(h)) {
-    return 'board';
-  }
-  // Default to issues (also covers #/issues and unknown/empty)
-  return 'issues';
-}
-
-/**
- * @param {{ getState: () => any, setState: (patch: any) => void }} store
- */
-export function createHashRouter(store) {
-  /** @type {(ev?: HashChangeEvent) => any} */
-  const onHashChange = () => {
-    const hash = window.location.hash || '';
-    // Rewrite legacy #/issue/<id> to canonical #/issues?issue=<id>
-    const legacyMatch = /^#\/issue\/([^\s?#]+)/.exec(hash);
-    if (legacyMatch && legacyMatch[1]) {
-      const id = decodeURIComponent(legacyMatch[1]);
-      // Update state immediately for consumers expecting sync selection
-      store.setState({ selected_id: id, view: 'issues' });
-      const next = `#/issues?issue=${encodeURIComponent(id)}`;
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-        return; // will trigger handler again
-      }
-    }
-    const id = parseHash(hash);
-    const view = parseView(hash);
-    store.setState({ selected_id: id, view });
-  };
-
-  return {
-    start() {
-      window.addEventListener('hashchange', onHashChange);
-      onHashChange();
-    },
-    stop() {
-      window.removeEventListener('hashchange', onHashChange);
-    },
-    /**
-     * @param {string} id
-     */
-    gotoIssue(id) {
-      // Keep current view in hash and append issue param via helper
-      const s = store.getState ? store.getState() : { view: 'issues' };
-      const view = s.view || 'issues';
-      const next = issueHashFor(view, id);
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-      } else {
-        // Force state update even if hash is the same
-        store.setState({ selected_id: id, view });
-      }
-    },
-    /**
-     * Navigate to a top-level view.
-     * @param {'issues'|'epics'|'board'} view
-     */
-    /**
-     * @param {'issues'|'epics'|'board'} view
-     */
-    gotoView(view) {
-      const s = store.getState ? store.getState() : { selected_id: null };
-      const id = s.selected_id;
-      const next = id ? issueHashFor(view, id) : `#/${view}`;
-      if (window.location.hash !== next) {
-        window.location.hash = next;
-      } else {
-        store.setState({ view, selected_id: null });
-      }
-    }
-  };
-}

package/app/state.js

@@ -1,103 +0,0 @@
-/**
- * Minimal app state store with subscription.
- */
-
-/**
- * @typedef {'all'|'open'|'in_progress'|'closed'|'ready'} StatusFilter
- */
-
-/**
- * @typedef {{ status: StatusFilter, search: string, type: string }} Filters
- */
-
-/**
- * @typedef {'issues'|'epics'|'board'} ViewName
- */
-
-/**
- * @typedef {'today'|'3'|'7'} ClosedFilter
- */
-
-/**
- * @typedef {{ closed_filter: ClosedFilter }} BoardState
- */
-
-/**
- * @typedef {{ selected_id: string | null, view: ViewName, filters: Filters, board: BoardState }} AppState
- */
-
-/**
- * Create a simple store for application state.
- * @param {Partial<AppState>} [initial]
- * @returns {{ getState: () => AppState, setState: (patch: { selected_id?: string | null, filters?: Partial<Filters> }) => void, subscribe: (fn: (s: AppState) => void) => () => void }}
- */
-export function createStore(initial = {}) {
-  /** @type {AppState} */
-  let state = {
-    selected_id: initial.selected_id ?? null,
-    view: initial.view ?? 'issues',
-    filters: {
-      status: initial.filters?.status ?? 'all',
-      search: initial.filters?.search ?? '',
-      type:
-        typeof initial.filters?.type === 'string' ? initial.filters?.type : ''
-    },
-    board: {
-      closed_filter:
-        initial.board?.closed_filter === '3' ||
-        initial.board?.closed_filter === '7' ||
-        initial.board?.closed_filter === 'today'
-          ? initial.board?.closed_filter
-          : 'today'
-    }
-  };
-
-  /** @type {Set<(s: AppState) => void>} */
-  const subs = new Set();
-
-  function emit() {
-    for (const fn of Array.from(subs)) {
-      try {
-        fn(state);
-      } catch {
-        // ignore
-      }
-    }
-  }
-
-  return {
-    getState() {
-      return state;
-    },
-    /**
-     * Update state. Nested filters can be partial.
-     * @param {{ selected_id?: string | null, filters?: Partial<Filters>, board?: Partial<BoardState> }} patch
-     */
-    setState(patch) {
-      /** @type {AppState} */
-      const next = {
-        ...state,
-        ...patch,
-        filters: { ...state.filters, ...(patch.filters || {}) },
-        board: { ...state.board, ...(patch.board || {}) }
-      };
-      // Avoid emitting if nothing changed (shallow compare)
-      if (
-        next.selected_id === state.selected_id &&
-        next.view === state.view &&
-        next.filters.status === state.filters.status &&
-        next.filters.search === state.filters.search &&
-        next.filters.type === state.filters.type &&
-        next.board.closed_filter === state.board.closed_filter
-      ) {
-        return;
-      }
-      state = next;
-      emit();
-    },
-    subscribe(fn) {
-      subs.add(fn);
-      return () => subs.delete(fn);
-    }
-  };
-}

package/app/utils/issue-id-renderer.js

@@ -1,71 +0,0 @@
-import { issueDisplayId } from './issue-id.js';
-
-/**
- * Create a reusable, copy-to-clipboard issue ID renderer.
- * Looks like the current inline ID (monospace `#123`) but acts as a button
- * that copies the full, prefixed ID (e.g., `UI-123`) when activated.
- * Shows transient "Copied" feedback and then restores the ID.
- * @param {string} id - Full issue id including the prefix (e.g., "UI-123").
- * @param {{ class_name?: string, duration_ms?: number }} [opts]
- * @returns {HTMLButtonElement}
- */
-export function createIssueIdRenderer(id, opts) {
-  /** @type {number} */
-  const duration =
-    typeof opts?.duration_ms === 'number' ? opts.duration_ms : 1200;
-  /** @type {HTMLButtonElement} */
-  const btn = document.createElement('button');
-  // Visual: match inline ID look; keep it neutral and text-like
-  btn.className =
-    (opts?.class_name ? opts.class_name + ' ' : '') + 'mono id-copy';
-  btn.type = 'button';
-  btn.setAttribute('aria-live', 'polite');
-  btn.setAttribute('title', 'Copy issue ID');
-  btn.setAttribute('aria-label', `Copy issue ID ${id}`);
-  const label = issueDisplayId(id);
-  btn.textContent = label;
-
-  /** Copy handler with feedback */
-  async function doCopy() {
-    // Prevent accidental row navigation and parent handlers
-    // (click/key handlers call this inside an event context)
-    try {
-      if (
-        navigator.clipboard &&
-        typeof navigator.clipboard.writeText === 'function'
-      ) {
-        await navigator.clipboard.writeText(String(id));
-      }
-      const prev = btn.textContent || label;
-      btn.textContent = 'Copied';
-      // Keep accessible label consistent with feedback
-      const oldAria = btn.getAttribute('aria-label') || '';
-      btn.setAttribute('aria-label', 'Copied');
-      setTimeout(
-        () => {
-          btn.textContent = prev;
-          btn.setAttribute('aria-label', oldAria);
-        },
-        Math.max(80, duration)
-      );
-    } catch {
-      // On failure, leave text as-is; no throw to avoid disruptive UX
-    }
-  }
-
-  btn.addEventListener('click', (ev) => {
-    ev.preventDefault();
-    ev.stopPropagation();
-    void doCopy();
-  });
-  btn.addEventListener('keydown', (ev) => {
-    // Ensure keyboard activation works even in non-interactive test envs
-    if (ev.key === 'Enter' || ev.key === ' ') {
-      ev.preventDefault();
-      ev.stopPropagation();
-      void doCopy();
-    }
-  });
-
-  return btn;
-}

package/app/utils/issue-id.js

@@ -1,10 +0,0 @@
-/**
- * Format a beads issue id as a user-facing display string `#${n}`.
- * Extracts the trailing numeric portion of the id and prefixes with '#'.
- * @param {string | null | undefined} id
- * @returns {string}
- */
-export function issueDisplayId(id) {
-  const m = String(id || '').match(/(\d+)$/);
-  return m ? `#${m[1]}` : '#';
-}

package/app/utils/issue-type.js

@@ -1,27 +0,0 @@
-/**
- * Known issue types in canonical order for dropdowns.
- * @type {Array<'bug'|'feature'|'task'|'epic'|'chore'>}
- */
-export const ISSUE_TYPES = ['bug', 'feature', 'task', 'epic', 'chore'];
-
-/**
- * Return a human-friendly label for an issue type.
- * @param {string | null | undefined} type
- * @returns {string}
- */
-export function typeLabel(type) {
-  switch ((type || '').toString().toLowerCase()) {
-    case 'bug':
-      return 'Bug';
-    case 'feature':
-      return 'Feature';
-    case 'task':
-      return 'Task';
-    case 'epic':
-      return 'Epic';
-    case 'chore':
-      return 'Chore';
-    default:
-      return '';
-  }
-}

package/app/utils/issue-url.js

@@ -1,9 +0,0 @@
-/**
- * Build a canonical issue hash that retains the view.
- * @param {'issues'|'epics'|'board'} view
- * @param {string} id
- */
-export function issueHashFor(view, id) {
-  const v = view === 'epics' || view === 'board' ? view : 'issues';
-  return `#/${v}?issue=${encodeURIComponent(id)}`;
-}

package/app/utils/markdown.js

@@ -1,22 +0,0 @@
-import DOMPurify from 'dompurify';
-import { html } from 'lit-html';
-import { unsafeHTML } from 'lit-html/directives/unsafe-html.js';
-import { marked } from 'marked';
-
-/**
- * Render Markdown safely as HTML using marked and DOMPurify.
- * Returns a lit-html TemplateResult via the unsafeHTML directive so it can be
- * embedded directly in templates.
- * @function renderMarkdown
- * @param {string} src Markdown source text
- * @returns {import('lit-html').TemplateResult}
- */
-export function renderMarkdown(src) {
-  /** @type {string} */
-  const markdown = String(src || '');
-  /** @type {string} */
-  const parsed = /** @type {string} */ (marked.parse(markdown));
-  /** @type {string} */
-  const html_string = DOMPurify.sanitize(parsed);
-  return html`${unsafeHTML(html_string)}`;
-}

package/app/utils/priority-badge.js

@@ -1,47 +0,0 @@
-import { priority_levels } from './priority.js';
-
-/**
- * Create a colored badge for a priority value (0..4).
- * @param {number | null | undefined} priority
- * @returns {HTMLSpanElement}
- */
-export function createPriorityBadge(priority) {
-  const p = typeof priority === 'number' ? priority : 2;
-  const el = document.createElement('span');
-  el.className = 'priority-badge';
-  el.classList.add(`is-p${Math.max(0, Math.min(4, p))}`);
-  el.setAttribute('role', 'img');
-  const label = labelForPriority(p);
-  el.setAttribute('title', label);
-  el.setAttribute('aria-label', `Priority: ${label}`);
-  el.textContent = emojiForPriority(p) + ' ' + label;
-  return el;
-}
-
-/**
- * @param {number} p
- */
-function labelForPriority(p) {
-  const i = Math.max(0, Math.min(4, p));
-  return priority_levels[i] || 'Medium';
-}
-
-/**
- * @param {number} p
- */
-export function emojiForPriority(p) {
-  switch (p) {
-    case 0:
-      return '🔥';
-    case 1:
-      return '⚡️';
-    case 2:
-      return '🔧';
-    case 3:
-      return '🪶';
-    case 4:
-      return '💤';
-    default:
-      return '🔧';
-  }
-}

package/app/utils/priority.js

@@ -1 +0,0 @@
-export const priority_levels = ['Critical', 'High', 'Medium', 'Low', 'Backlog'];