beads-ui 0.1.0

package/.prettierignore

@@ -0,0 +1,5 @@
+node_modules
+coverage
+dist
+.beads
+

package/AGENTS.md

@@ -0,0 +1,85 @@
+# Agents
+
+## Beads (bd) — Work Tracking
+
+Use MCP `beads` (bd) as our dependency‑aware issue tracker. Run
+`beads/quickstart` to learn how to use it.
+
+### Issue Types
+
+- `bug` - Something broken that needs fixing
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature composed of multiple issues
+- `chore` - Maintenance work (dependencies, tooling)
+
+### Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (nice-to-have features, minor bugs)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+### Dependency Types
+
+- `blocks` - Hard dependency (issue X blocks issue Y)
+- `related` - Soft relationship (issues are connected)
+- `parent-child` - Epic/subtask relationship
+- `discovered-from` - Track issues discovered during work
+
+Only `blocks` dependencies affect the ready work queue.
+
+### Structured Fields and Labels
+
+- Use issue `type` and `priority` fields.
+- Use issue type "epic" and `parent-child` dependencies.
+- Use `related` or `discovered-from` dependencies.
+- Area pointers are labels, e.g.: `frontend`, `backend`
+
+### Agent Workflow
+
+If no issue is specified, run `bd ready` and claim an unblocked issue.
+
+1. Open issue with `bd show <id>` and read all linked docs.
+2. Assign to `agent`, update status as you work (`in_progress` → `closed`);
+   maintain dependencies, and attach notes/links for traceability.
+3. Discover new work? Create linked issue with dependency
+   `discovered-from:<parent-id>`.
+4. Land the change; run tests/lint; update any referenced docs.
+5. Close the issue with `bd close <id>`.
+
+## Coding Standards
+
+- Use ECMAScript modules.
+- Classes, interfaces, and factory types use `PascalCase`.
+- Functions and methods use `camelCase`.
+- Variables and parameters use `lower_snake_case`, unless they refer to a
+  function or class.
+- Constants are `UPPER_SNAKE_CASE`.
+- File and directory names are `kebab-case`.
+- Use `.js` files with JSDoc type annotations (TypeScript mode).
+- Use `.ts` files only for interface definitions.
+- Type only imports: `@import { X, Y, Z } from './file.js` in top-of-file JSDoc.
+- Add JSDoc to all functions and methods with `@param` (and `@returns` for non
+  trivial return types).
+- Annotate local variables with `@type` blocks if their type is not obvious from
+  the initializer.
+- Use blocks for all control flow statements, even single-line bodies.
+- Avoid runtime type checks, undefined/null checks and optional chaining
+  operators (`?.`, `??`) unless strictly necessary.
+
+## Unit Testing Standards
+
+- Write short, focused test-case functions asserting one behavior each.
+- Do not use "should" in test names; use verbs like "returns", "throws",
+  "emits", or "calls"
+- Structure: setup → execution → assertion (separate with blank lines).
+- Never change implementation code to make tests pass.
+
+## Pre‑Handoff Validation
+
+- Run type checks: `npm run typecheck`
+- Run tests: `npm test`
+- Run eslint: `npm run lint`
+- Run prettier: `npm run format`

package/CHANGES.md

@@ -0,0 +1,5 @@
+# Changes
+
+## 0.1.0
+
+- 🥇 Initial release

package/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Maximilian Antoni
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# beads-ui
+
+Local‑first UI for the `bd` CLI (beads) — a fast, dependency‑aware issue
+tracker.
+
+beads-ui complements the upstream beads project by providing a single‑page web
+app served from a local Node.js server. It talks to `bd` over a local WebSocket
+to list issues, show details, and apply edits. All changes happen by executing
+`bd` commands, and live updates flow in as the database changes on disk.
+
+Upstream beads (CLI and docs): https://github.com/steveyegge/beads
+
+## Features
+
+- Issues list with inline edits, quick filters, and keyboard navigation
+- Epics view grouped by epic (from `bd epic status --json`) with expandable rows
+- Board view with Ready / In progress / Closed columns
+- Deep links for navigation; state persists across reloads
+- Live updates via FS watch + WebSocket; optimistic UI with rollbacks on error
+- Dark theme toggle, saved per user
+- Local CLI helper `bdui` to daemonize the server and open your browser
+
+## Screenshots
+
+Issues
+
+![Issues view](media/bdui-issues.png)
+
+Epics
+
+![Epics view](media/bdui-epics.png)
+
+Board
+
+![Board view](media/bdui-board.png)
+
+## Quickstart
+
+Prerequisites:
+
+- Node.js >= 22
+- `bd` CLI on your PATH (or set `BD_BIN=/path/to/bd`)
+
+Install and start:
+
+```sh
+npm install -g beads-ui
+bdui start
+```
+
+See `bdui --help` for options.
+
+Environment variables:
+
+- `BDUI_RUNTIME_DIR`: override runtime directory for PID/logs. Defaults to
+  `$XDG_RUNTIME_DIR/beads-ui` or the system temp dir.
+- `BDUI_NO_OPEN=1`: disable opening the default browser on `start`.
+- `PORT`: overrides the listen port (default `3000`). The server binds to
+  `127.0.0.1`.
+
+Platform notes:
+
+- macOS/Linux are fully supported. On Windows, the CLI uses `cmd /c start` to
+  open URLs and relies on Node’s `process.kill` semantics for stopping the
+  daemon.
+
+## Developer Workflow
+
+- Type check: `npm run typecheck`
+- Tests: `npm test`
+- Lint: `npm run lint`
+- Format: `npm run format`
+
+See `docs/quickstart.md` for details and `docs/architecture.md` for the protocol
+and component overview.

package/app/data/providers.js

@@ -0,0 +1,178 @@
+/**
+ * Data layer: typed wrappers around the ws transport for bd-backed queries.
+ * @param {(type: import('../protocol.js').MessageType, payload?: unknown) => Promise<unknown>} transport - Request/response function.
+ * @param {(type: import('../protocol.js').MessageType, handler: (payload: unknown) => void) => void} [on_event] - Optional event subscription (used to invalidate caches on push updates).
+ * @returns {{ getEpicStatus: () => Promise<unknown[]>, getReady: () => Promise<unknown[]>, getOpen: () => Promise<unknown[]>, getInProgress: () => Promise<unknown[]>, getClosed: (limit?: number) => Promise<unknown[]>, getIssue: (id: string) => Promise<unknown>, updateIssue: (input: { id: string, title?: string, acceptance?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }) => Promise<unknown> }}
+ */
+export function createDataLayer(transport, on_event) {
+  /** @type {{ list_ready?: unknown, list_open?: unknown, list_in_progress?: unknown, list_closed_10?: unknown, epic_status?: unknown }} */
+  const cache = {};
+
+  // Invalidate caches on server push updates when available
+  if (on_event) {
+    try {
+      on_event('issues-changed', () => {
+        cache.list_ready = undefined;
+        cache.list_open = undefined;
+        cache.list_in_progress = undefined;
+        cache.list_closed_10 = undefined;
+        cache.epic_status = undefined;
+      });
+    } catch {
+      // noop
+    }
+  }
+
+  /**
+   * Get epic status groups via `bd epic status --json`.
+   * @returns {Promise<unknown[]>}
+   */
+  async function getEpicStatus() {
+    if (Array.isArray(cache.epic_status)) {
+      return /** @type {unknown[]} */ (cache.epic_status);
+    }
+    /** @type {unknown} */
+    const res = await transport('epic-status');
+    const arr = Array.isArray(res) ? res : [];
+    cache.epic_status = arr;
+    return arr;
+  }
+
+  /**
+   * Ready issues: `bd ready --json`.
+   * Sort by priority then updated_at on the UI; transport returns raw list.
+   * @returns {Promise<unknown[]>}
+   */
+  async function getReady() {
+    if (Array.isArray(cache.list_ready)) {
+      return /** @type {unknown[]} */ (cache.list_ready);
+    }
+    /** @type {unknown} */
+    const res = await transport('list-issues', { filters: { ready: true } });
+    const arr = Array.isArray(res) ? res : [];
+    cache.list_ready = arr;
+    return arr;
+  }
+
+  /**
+   * Open issues: `bd list -s open --json`.
+   * @returns {Promise<unknown[]>}
+   */
+  async function getOpen() {
+    if (Array.isArray(cache.list_open)) {
+      return /** @type {unknown[]} */ (cache.list_open);
+    }
+    /** @type {unknown} */
+    const res = await transport('list-issues', {
+      filters: { status: 'open' }
+    });
+    const arr = Array.isArray(res) ? res : [];
+    cache.list_open = arr;
+    return arr;
+  }
+
+  /**
+   * In progress issues: `bd list -s in_progress --json`.
+   * @returns {Promise<unknown[]>}
+   */
+  async function getInProgress() {
+    if (Array.isArray(cache.list_in_progress)) {
+      return /** @type {unknown[]} */ (cache.list_in_progress);
+    }
+    /** @type {unknown} */
+    const res = await transport('list-issues', {
+      filters: { status: 'in_progress' }
+    });
+    const arr = Array.isArray(res) ? res : [];
+    cache.list_in_progress = arr;
+    return arr;
+  }
+
+  /**
+   * Closed issues: `bd list -s closed -l 10 --json`.
+   * @param {number} [limit] - Optional limit (defaults to 10).
+   * @returns {Promise<unknown[]>}
+   */
+  async function getClosed(limit = 10) {
+    if (limit === 10 && Array.isArray(cache.list_closed_10)) {
+      return /** @type {unknown[]} */ (cache.list_closed_10);
+    }
+    /** @type {unknown} */
+    const res = await transport('list-issues', {
+      filters: { status: 'closed', limit }
+    });
+    const arr = Array.isArray(res) ? res : [];
+    if (limit === 10) {
+      cache.list_closed_10 = arr;
+    }
+    return arr;
+  }
+
+  /**
+   * Show a single issue via `bd show <id> --json`.
+   * @param {string} id
+   * @returns {Promise<unknown>}
+   */
+  async function getIssue(id) {
+    /** @type {unknown} */
+    const res = await transport('show-issue', { id });
+    return res;
+  }
+
+  /**
+   * Update issue fields by dispatching specific mutations.
+   * Supported fields: title, acceptance, status, priority, assignee.
+   * Returns the updated issue on success.
+   * @param {{ id: string, title?: string, acceptance?: string, status?: 'open'|'in_progress'|'closed', priority?: number, assignee?: string }} input
+   * @returns {Promise<unknown>}
+   */
+  async function updateIssue(input) {
+    const { id } = input;
+    /** @type {unknown} */
+    let last = null;
+    if (typeof input.title === 'string') {
+      last = await transport('edit-text', {
+        id,
+        field: 'title',
+        value: input.title
+      });
+    }
+    if (typeof input.acceptance === 'string') {
+      last = await transport('edit-text', {
+        id,
+        field: 'acceptance',
+        value: input.acceptance
+      });
+    }
+    if (typeof input.status === 'string') {
+      last = await transport('update-status', {
+        id,
+        status: input.status
+      });
+    }
+    if (typeof input.priority === 'number') {
+      last = await transport('update-priority', {
+        id,
+        priority: input.priority
+      });
+    }
+    // type updates are not supported via UI
+    if (typeof input.assignee === 'string') {
+      last = await transport('update-assignee', {
+        id,
+        assignee: input.assignee
+      });
+    }
+    return last;
+  }
+
+  return {
+    getEpicStatus,
+    getReady,
+    getOpen,
+    getInProgress,
+    getClosed,
+    getIssue,
+    updateIssue
+  };
+}

package/app/data/providers.test.js

@@ -0,0 +1,126 @@
+import { describe, expect, test } from 'vitest';
+import { createDataLayer } from './providers.js';
+
+// Using a minimal fixture shaped like epic-status-example.json
+const epicFixture = [
+  {
+    epic: {
+      id: 'WK-1',
+      title: 'Example Epic',
+      description: 'Example',
+      acceptance_criteria: 'Demo',
+      notes: '',
+      status: 'open',
+      priority: 1,
+      issue_type: 'epic',
+      created_at: '2025-10-21T00:00:00.000Z',
+      updated_at: '2025-10-21T00:00:00.000Z'
+    },
+    total_children: 2,
+    closed_children: 1,
+    eligible_for_close: false
+  }
+];
+
+/**
+ * @returns {{ calls: { type: string, payload: any }[], send: (type: string, payload?: any) => Promise<any> }}
+ */
+function makeTransportRecorder() {
+  /** @type {{ type: string, payload: any }[]} */
+  const calls = [];
+  return {
+    calls,
+    /**
+     * @param {string} type
+     * @param {any} [payload]
+     */
+    async send(type, payload) {
+      calls.push({ type, payload });
+      // default fake payloads
+      if (type === 'epic-status') {
+        return [];
+      }
+      if (type === 'list-issues') {
+        return [];
+      }
+      if (type === 'show-issue') {
+        return { id: payload?.id || 'X' };
+      }
+      if (
+        type === 'update-status' ||
+        type === 'update-priority' ||
+        type === 'edit-text' ||
+        type === 'update-assignee'
+      ) {
+        return { id: payload?.id || 'X' };
+      }
+      return null;
+    }
+  };
+}
+
+describe('data/providers', () => {
+  test('getClosed requests list-issues with status and limit=10 by default', async () => {
+    const rec = makeTransportRecorder();
+    const data = createDataLayer((t, p) => rec.send(t, p));
+    await data.getClosed();
+    const last = rec.calls[rec.calls.length - 1];
+    expect(last.type).toBe('list-issues');
+    expect(last.payload.filters.status).toBe('closed');
+    expect(last.payload.filters.limit).toBe(10);
+  });
+
+  test('getInProgress requests list-issues with status=in_progress', async () => {
+    const rec = makeTransportRecorder();
+    const data = createDataLayer((t, p) => rec.send(t, p));
+    await data.getInProgress();
+    const last = rec.calls[rec.calls.length - 1];
+    expect(last.type).toBe('list-issues');
+    expect(last.payload.filters.status).toBe('in_progress');
+  });
+
+  test('getReady uses list-issues with ready:true', async () => {
+    const rec = makeTransportRecorder();
+    const data = createDataLayer((t, p) => rec.send(t, p));
+    await data.getReady();
+    const last = rec.calls[rec.calls.length - 1];
+    expect(last.type).toBe('list-issues');
+    expect(last.payload.filters.ready).toBe(true);
+  });
+
+  test('getEpicStatus calls epic-status and returns fixture-shaped data', async () => {
+    const rec = makeTransportRecorder();
+    const data = createDataLayer(async (t, p) => {
+      if (t === 'epic-status') {
+        rec.calls.push({ type: t, payload: p });
+        return epicFixture;
+      }
+      return rec.send(t, p);
+    });
+    const res = await data.getEpicStatus();
+    const last = rec.calls[rec.calls.length - 1];
+    expect(last.type).toBe('epic-status');
+    expect(Array.isArray(res)).toBe(true);
+    // basic shape check from fixture
+    // @ts-ignore
+    expect(res[0].epic?.id).toBeDefined();
+  });
+
+  test('updateIssue dispatches field-specific mutations', async () => {
+    const rec = makeTransportRecorder();
+    const data = createDataLayer((t, p) => rec.send(t, p));
+    await data.updateIssue({
+      id: 'UI-1',
+      title: 'X',
+      acceptance: 'Y',
+      status: 'in_progress',
+      priority: 2,
+      assignee: 'max'
+    });
+    const types = rec.calls.map((c) => c.type);
+    expect(types).toContain('edit-text');
+    expect(types).toContain('update-status');
+    expect(types).toContain('update-priority');
+    expect(types).toContain('update-assignee');
+  });
+});

package/app/index.html

@@ -0,0 +1,29 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Beads</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <header class="app-header">
+      <div class="header-left">
+        <h1 class="app-title">Beads</h1>
+        <nav id="top-nav" class="header-nav" aria-label="Primary"></nav>
+      </div>
+      <div class="header-actions">
+        <label class="theme-toggle" title="Toggle dark mode">
+          <span>Dark</span>
+          <input
+            id="theme-switch"
+            type="checkbox"
+            aria-label="Toggle dark mode"
+          />
+        </label>
+      </div>
+    </header>
+    <main id="app" class="app-shell" aria-live="polite"></main>
+    <script type="module" src="/main.bundle.js"></script>
+  </body>
+</html>

package/app/main.board-switch.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, test, vi } from 'vitest';
+import { bootstrap } from './main.js';
+
+// Mock the Board view to manipulate DOM content deterministically
+vi.mock('./views/board.js', () => ({
+  /**
+   * @param {HTMLElement} mount
+   */
+  createBoardView: (mount) => ({
+    async load() {
+      // Simulate a rendered board shell
+      mount.innerHTML = '<div class="panel__body board-root"></div>';
+    },
+    clear() {
+      // No-op in this test; we no longer depend on clearing when switching views
+    }
+  })
+}));
+
+// Mock WS client to avoid network and provide minimal data
+vi.mock('./ws.js', () => ({
+  createWsClient: () => ({
+    /**
+     * @param {string} type
+     */
+    async send(type) {
+      if (type === 'list-issues') {
+        return [];
+      }
+      if (type === 'show-issue') {
+        return null;
+      }
+      if (type === 'epic-status') {
+        return [];
+      }
+      return null;
+    },
+    on() {
+      return () => {};
+    },
+    close() {},
+    getState() {
+      return 'open';
+    }
+  })
+}));
+
+describe('board visibility on view change', () => {
+  test('hides board when leaving and shows again when returning', async () => {
+    // Start on issues, then go to board so subscribers are active
+    window.location.hash = '#/issues';
+    document.body.innerHTML = '<main id="app"></main>';
+    const root = /** @type {HTMLElement} */ (document.getElementById('app'));
+
+    bootstrap(root);
+
+    // Allow initial render to flush
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const boardRoot = /** @type {HTMLElement} */ (
+      document.getElementById('board-root')
+    );
+
+    // Navigate to board
+    window.location.hash = '#/board';
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Board is visible and rendered with its internal shell
+    expect(boardRoot.hidden).toBe(false);
+    expect(boardRoot.querySelector('.board-root')).not.toBeNull();
+
+    // Navigate away to issues
+    window.location.hash = '#/issues';
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+
+    await Promise.resolve();
+    await Promise.resolve();
+
+    // Board route gets hidden but DOM may remain; CSS [hidden] must hide it
+    expect(boardRoot.hidden).toBe(true);
+    expect(boardRoot.querySelector('.board-root')).not.toBeNull();
+
+    // Go back to Board, content is still there (or re-rendered by load)
+    window.location.hash = '#/board';
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(boardRoot.hidden).toBe(false);
+    expect(boardRoot.querySelector('.board-root')).not.toBeNull();
+  });
+});

package/app/main.deep-link.test.js

@@ -0,0 +1,64 @@
+import { describe, expect, test, vi } from 'vitest';
+// Import after mocking
+import { bootstrap } from './main.js';
+
+// Mock WS client before importing the app
+const calls = [];
+const issues = [
+  { id: 'UI-1', title: 'One', status: 'open', priority: 1 },
+  { id: 'UI-2', title: 'Two', status: 'open', priority: 2 }
+];
+vi.mock('./ws.js', () => ({
+  createWsClient: () => ({
+    /**
+     * @param {string} type
+     * @param {any} payload
+     */
+    async send(type, payload) {
+      calls.push({ type, payload });
+      if (type === 'list-issues') {
+        return issues;
+      }
+      if (type === 'show-issue') {
+        const id = /** @type {any} */ (payload).id;
+        const it = issues.find((i) => i.id === id);
+        return it || null;
+      }
+      return null;
+    },
+    on() {
+      return () => {};
+    },
+    close() {},
+    getState() {
+      return 'open';
+    }
+  })
+}));
+
+describe('deep link on initial load (UI-44)', () => {
+  test('loads detail and highlights list item when hash includes issue id', async () => {
+    window.location.hash = '#/issue/UI-2';
+    document.body.innerHTML = '<main id="app"></main>';
+    const root = /** @type {HTMLElement} */ (document.getElementById('app'));
+
+    bootstrap(root);
+
+    // Allow async loads to complete
+    await Promise.resolve();
+    await Promise.resolve();
+
+    const detailId = /** @type {HTMLElement} */ (
+      document.querySelector('#detail-panel .detail-title .detail-id')
+    );
+    expect(detailId && detailId.textContent).toBe('#2');
+
+    const list = /** @type {HTMLElement} */ (
+      document.getElementById('list-root')
+    );
+    const selected = /** @type {HTMLElement|null} */ (
+      list.querySelector('tr.issue-row.selected')
+    );
+    expect(selected && selected.getAttribute('data-issue-id')).toBe('UI-2');
+  });
+});