beads-ui 0.1.0

package/app/protocol.js

@@ -0,0 +1,200 @@
+/**
+ * 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., `issues-changed`).
+ *
+ * Versioning
+ * - Increment `PROTOCOL_VERSION` on breaking changes.
+ * - Add new message types without breaking existing ones when possible.
+ */
+
+/** @constant {string} */
+export const PROTOCOL_VERSION = '1.0.0';
+
+/** @typedef {'list-issues'|'show-issue'|'update-status'|'edit-text'|'update-priority'|'create-issue'|'list-ready'|'subscribe-updates'|'issues-changed'|'dep-add'|'dep-remove'|'epic-status'|'update-assignee'|'label-add'|'label-remove'} 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',
+  'show-issue',
+  'update-status',
+  'edit-text',
+  'update-priority',
+  'create-issue',
+  'list-ready',
+  'subscribe-updates',
+  'issues-changed',
+  'dep-add',
+  'dep-remove',
+  'epic-status',
+  'update-assignee',
+  'label-add',
+  'label-remove'
+]);
+
+/**
+ * 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 = /** @type {any} */ (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

@@ -0,0 +1,64 @@
+# beads-ui WebSocket Protocol (v1.0.0)
+
+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., `issues-changed`) using the
+ReplyEnvelope shape with `ok: true` and a generated `id`.
+
+## Message Types
+
+- `list-issues` payload: `{ filters?: { status?: string, priority?: number } }`
+- `show-issue` payload: `{ id: string }`
+- `update-status` payload:
+  `{ id: string, status: 'open'|'in_progress'|'closed' }`
+- `edit-text` payload:
+  `{ id: string, field: 'title'|'description'|'acceptance', value: string }`
+  - Note: `description` edits are rejected by the server (unsupported by `bd`).
+- `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: `{}`
+- `subscribe-updates` payload: `{}` (server responds with `ok` and begins
+  emitting events)
+- `issues-changed` payload: `{ ts: number, hint?: { ids?: string[] } }`
+- `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
+
+- `list-issues` → `bd list --json [--status <s>] [--priority <n>]`
+- `show-issue` → `bd show <id> --json`
+- `update-status` → `bd update <id> --status <status>`
+- `edit-text` → `bd update <id> --title <t>` or `--acceptance-criteria <a>`
+  - `description` has no CLI flag; server responds with an error
+- `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
+
+## Versioning
+
+Breaking changes to shapes or semantics increment `PROTOCOL_VERSION` in
+`app/protocol.js`.

package/app/protocol.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'vitest';
+import {
+  MESSAGE_TYPES,
+  PROTOCOL_VERSION,
+  decodeReply,
+  decodeRequest,
+  isMessageType,
+  isReply,
+  isRequest,
+  makeError,
+  makeOk,
+  makeRequest
+} from './protocol.js';
+
+describe('protocol', () => {
+  test('version and message types', () => {
+    expect(typeof PROTOCOL_VERSION).toBe('string');
+    expect(Array.isArray(MESSAGE_TYPES)).toBe(true);
+    expect(MESSAGE_TYPES.length).toBeGreaterThan(3);
+    expect(isMessageType('list-issues')).toBe(true);
+    expect(isMessageType('unknown-type')).toBe(false);
+  });
+
+  test('makeRequest / isRequest / decodeRequest', () => {
+    const req = makeRequest(
+      'list-issues',
+      { filters: { status: 'open' } },
+      'r-1'
+    );
+    expect(isRequest(req)).toBe(true);
+    const round = decodeRequest(JSON.parse(JSON.stringify(req)));
+    expect(round.id).toBe('r-1');
+    expect(round.type).toBe('list-issues');
+  });
+
+  test('makeOk / makeError / isReply / decodeReply', () => {
+    const req = makeRequest('show-issue', { id: 'UI-1' }, 'r-2');
+    const ok = makeOk(req, { id: 'UI-1', title: 'T' });
+    expect(isReply(ok)).toBe(true);
+    const ok2 = decodeReply(JSON.parse(JSON.stringify(ok)));
+    expect(ok2.ok).toBe(true);
+
+    const err = makeError(req, 'not_found', 'Issue not found');
+    expect(isReply(err)).toBe(true);
+    const err2 = decodeReply(JSON.parse(JSON.stringify(err)));
+    expect(err2.ok).toBe(false);
+    if (!('error' in err2) || !err2.error) {
+      throw new Error('Expected error to be present when ok=false');
+    }
+    expect(err2.error.code).toBe('not_found');
+  });
+
+  test('invalid envelopes are rejected', () => {
+    expect(() => decodeRequest({})).toThrow();
+    expect(() => decodeReply({ ok: true })).toThrow();
+  });
+});

package/app/router.js

@@ -0,0 +1,78 @@
+/**
+ * Hash-based router for tabs (issues/epics/board) and deep-linked issue ids.
+ */
+
+/**
+ * Parse an application hash and extract the selected issue id.
+ * @param {string} hash
+ * @returns {string | null}
+ */
+export function parseHash(hash) {
+  const m = /^#\/issue\/([^\s?#]+)/.exec(hash || '');
+  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';
+}
+
+/**
+ * Create and start the hash router.
+ * @param {{ getState: () => any, setState: (patch: any) => void }} store
+ * @returns {{ start: () => void, stop: () => void, gotoIssue: (id: string) => void, gotoView: (v: 'issues'|'epics'|'board') => void }}
+ */
+export function createHashRouter(store) {
+  /** @type {(ev?: HashChangeEvent) => any} */
+  const onHashChange = () => {
+    const hash = window.location.hash || '';
+    const id = parseHash(hash);
+    // Preserve current view when navigating to a detail route so tabs remain stable
+    const current = store.getState ? store.getState() : { view: 'issues' };
+    const view = id ? current.view || 'issues' : parseView(hash);
+    store.setState({ selected_id: id, view });
+  };
+
+  return {
+    start() {
+      window.addEventListener('hashchange', onHashChange);
+      onHashChange();
+    },
+    stop() {
+      window.removeEventListener('hashchange', onHashChange);
+    },
+    gotoIssue(id) {
+      const next = `#/issue/${encodeURIComponent(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: 'issues' });
+      }
+    },
+    /**
+     * Navigate to a top-level view.
+     * @param {'issues'|'epics'|'board'} view
+     */
+    gotoView(view) {
+      const next = `#/${view}`;
+      if (window.location.hash !== next) {
+        window.location.hash = next;
+      } else {
+        store.setState({ view, selected_id: null });
+      }
+    }
+  };
+}

package/app/router.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, test } from 'vitest';
+import { createHashRouter, parseHash, parseView } from './router.js';
+import { createStore } from './state.js';
+
+describe('router', () => {
+  test('parseHash extracts id', () => {
+    expect(parseHash('#/issue/UI-5')).toBe('UI-5');
+    expect(parseHash('#/anything')).toBeNull();
+  });
+
+  test('router updates store and gotoIssue updates hash', () => {
+    document.body.innerHTML = '<div></div>';
+    const store = createStore();
+    const router = createHashRouter(store);
+    router.start();
+
+    window.location.hash = '#/issue/UI-10';
+    // Trigger handler synchronously
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+    expect(store.getState().selected_id).toBe('UI-10');
+
+    router.gotoIssue('UI-11');
+    expect(window.location.hash).toBe('#/issue/UI-11');
+    router.stop();
+  });
+
+  test('parseView resolves from hash and defaults to issues', () => {
+    expect(parseView('#/issues')).toBe('issues');
+    expect(parseView('#/epics')).toBe('epics');
+    expect(parseView('#/board')).toBe('board');
+    expect(parseView('')).toBe('issues');
+    expect(parseView('#/unknown')).toBe('issues');
+  });
+});

package/app/state.js

@@ -0,0 +1,87 @@
+/**
+ * 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 {{ selected_id: string | null, view: ViewName, filters: Filters }} 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: /** @type {any} */ (initial).selected_id ?? null,
+    view: /** @type {any} */ (initial).view ?? 'issues',
+    filters: {
+      status: /** @type {any} */ (initial).filters?.status ?? 'all',
+      search: /** @type {any} */ (initial).filters?.search ?? '',
+      type:
+        typeof (/** @type {any} */ (initial).filters?.type) === 'string'
+          ? /** @type {any} */ (initial).filters?.type
+          : ''
+    }
+  };
+
+  /** @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> }} patch
+     */
+    setState(patch) {
+      /** @type {AppState} */
+      const next = {
+        ...state,
+        ...patch,
+        filters: { ...state.filters, ...(patch.filters || {}) }
+      };
+      // 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
+      ) {
+        return;
+      }
+      state = next;
+      emit();
+    },
+    subscribe(fn) {
+      subs.add(fn);
+      return () => subs.delete(fn);
+    }
+  };
+}

package/app/state.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, test } from 'vitest';
+import { createStore } from './state.js';
+
+describe('state store', () => {
+  test('get/set/subscribe works and dedupes unchanged', () => {
+    const store = createStore();
+    const seen = [];
+    const off = store.subscribe((s) => seen.push(s));
+
+    store.setState({ selected_id: 'UI-1' });
+    store.setState({ filters: { status: 'open' } });
+    // no-op (unchanged)
+    store.setState({ filters: { status: 'open' } });
+    off();
+
+    expect(seen.length).toBe(2);
+    const state = store.getState();
+    expect(state.selected_id).toBe('UI-1');
+    expect(state.filters.status).toBe('open');
+  });
+});