beads-ui 0.1.1 → 0.2.0

package/docs/quickstart.md

@@ -1,142 +0,0 @@
-# beads-ui Quickstart
-
-This project provides a local-first SPA for the `bd` (beads) CLI. It runs a
-local HTTP + WebSocket server that serves the UI and proxies edits to the `bd`
-CLI. Changes to the active beads database are pushed live to the browser.
-
-## Prerequisites
-
-- Node.js >= 22
-- The `bd` CLI on your PATH (or set `BD_BIN=/path/to/bd`)
-- An initialized beads database (see below)
-
-## Install
-
-```sh
-npm install
-```
-
-## Run
-
-Use the CLI to daemonize the server and open your browser:
-
-```sh
-bdui start
-```
-
-Or run in the foreground for quick debugging:
-
-```sh
-npm start
-```
-
-- Server binds to `127.0.0.1:3000` by default.
-- Open http://127.0.0.1:3000 in your browser.
-
-Environment knobs:
-
-- `PORT` to change the listen port (default: `3000`). The server always binds to
-  `127.0.0.1` for local‑only access.
-- `BD_BIN` to point at a non-default `bd` binary.
-
-## Database Resolution and Watching
-
-The server and watcher resolve the active beads database in this order:
-
-1. `--db <path>` injected by the server when invoking `bd` (derived from
-   resolution below)
-2. `BEADS_DB` environment variable, if set
-3. Nearest `.beads/*.db` by walking up from the server `root_dir`
-4. `~/.beads/default.db`
-
-The watcher listens for changes to the resolved SQLite DB and broadcasts an
-`issues-changed` event to all connected clients. See `docs/db-watching.md` for
-details.
-
-## Initialize a Workspace (if needed)
-
-From your project root:
-
-```sh
-# create a workspace DB
-bd init
-
-# create a few issues
-bd create "First issue" -t task -p 2 -d "Initial work"
-bd create "Bug: wrong color" -t bug -p 1
-```
-
-The UI should list these after startup. Edits in the UI map to `bd update`
-commands executed by the server.
-
-## Development Workflow
-
-- Type check: `npm run typecheck`
-- Tests: `npm test`
-- Lint: `npm run lint`
-- Format: `npm run format`
-
-Tests cover protocol handlers, WebSocket client/server behavior, and core UI
-flows (list and detail views, edits, and dependency management).
-
-## CLI (`bdui`) Local Link
-
-The `bdui` CLI is exposed via npm’s `bin` field for local development. To make
-it available on your PATH:
-
-```sh
-npm link
-```
-
-Common commands:
-
-```sh
-bdui start           # daemonize the server and open the browser
-bdui start --no-open # start without opening a browser (or set BDUI_NO_OPEN=1)
-bdui stop            # stop the daemon (exit code 2 if not running)
-bdui restart         # stop then start
-bdui --help          # usage
-```
-
-Runtime directory and logs:
-
-- PID and log files live under `$XDG_RUNTIME_DIR/beads-ui` or the system temp
-  directory. Override with `BDUI_RUNTIME_DIR=/path`.
-
-Environment knobs also used by `bdui`:
-
-- `PORT` to change the listen port (default: `3000`)
-- `BDUI_NO_OPEN=1` to disable auto-opening the browser on `start`
-- `BDUI_RUNTIME_DIR` to set a custom runtime directory
-
-## Protocol
-
-The WebSocket protocol is documented in `app/protocol.md` and shared by server
-and client via `server/protocol.js` re-exports.
-
-## Troubleshooting
-
-- If the UI shows no issues, verify a beads DB exists or run `bd init` in your
-  workspace.
-- To target a specific DB, set `BEADS_DB=/path/to/file.db` before `npm start`.
-- If `bd` isn’t on your PATH, set `BD_BIN` to the full path.
-
-### `bdui` specific
-
-- Logs and PID: check the runtime dir for `daemon.log` and `server.pid`.
-  - Default: `$XDG_RUNTIME_DIR/beads-ui` (Linux), otherwise your system temp
-    directory (see `os.tmpdir()`).
-  - Override: set `BDUI_RUNTIME_DIR=/path`.
-- Stale process: if `bdui stop` reports exit code `2` but `server.pid` exists,
-  remove the PID file and try again:
-
-  ```sh
-  rm "$(bdui --help >/dev/null 2>&1; echo ${BDUI_RUNTIME_DIR:-$(echo ${XDG_RUNTIME_DIR:-/tmp})/beads-ui})/server.pid" 2>/dev/null || true
-  bdui stop
-  ```
-
-- Port in use: set a different port and restart:
-
-  ```sh
-  PORT=4000 bdui restart
-  ```

package/eslint.config.js

@@ -1,59 +0,0 @@
-import js from '@eslint/js';
-import plugin_jsdoc from 'eslint-plugin-jsdoc';
-import plugin_n from 'eslint-plugin-n';
-import { defineConfig } from 'eslint/config';
-import globals from 'globals';
-
-export default defineConfig([
-  {
-    ignores: ['node_modules', 'coverage', 'dist', '.beads']
-  },
-  js.configs.recommended,
-  plugin_jsdoc.configs['flat/recommended'],
-  {
-    settings: {
-      jsdoc: {
-        mode: 'typescript',
-        preferredTypes: {
-          object: 'Object'
-        }
-      }
-    },
-    rules: {
-      'jsdoc/require-jsdoc': 'off',
-      'jsdoc/require-param-description': 'off',
-      'jsdoc/require-returns-description': 'off',
-      'jsdoc/require-property-description': 'off',
-      'jsdoc/reject-any-type': 'off',
-      'jsdoc/require-returns': 'off'
-    }
-  },
-  {
-    files: ['**/*.test.js'],
-    languageOptions: {
-      globals: globals.vitest
-    }
-  },
-  {
-    files: ['server/**/*.js'],
-    ...plugin_n.configs['flat/recommended'],
-    languageOptions: {
-      globals: globals.node
-    },
-    rules: {
-      'n/no-unpublished-import': 'off'
-    }
-  },
-  {
-    files: ['bin/**/*.js'],
-    languageOptions: {
-      globals: globals.node
-    }
-  },
-  {
-    files: ['app/**/*.js'],
-    languageOptions: {
-      globals: globals.browser
-    }
-  }
-]);

package/prettier.config.js

@@ -1,13 +0,0 @@
-/**
- * @import { Config } from 'prettier'
- */
-
-/** @type {Config} */
-export default {
-  singleQuote: true,
-  trailingComma: 'none',
-  proseWrap: 'always',
-  plugins: ['@trivago/prettier-plugin-sort-imports'],
-  importOrder: ['^@(.*)$', '<THIRD_PARTY_MODULES>', '^[./]'],
-  importOrderSortSpecifiers: true
-};

package/server/app.test.js

@@ -1,29 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { describe, expect, test } from 'vitest';
-import { createApp } from './app.js';
-import { getConfig } from './config.js';
-
-/**
- * Narrow to function type for basic checks.
- * @param {unknown} value
- * @returns {value is Function}
- */
-function isFunction(value) {
-  return typeof value === 'function';
-}
-
-describe('server app wiring (no listen)', () => {
-  test('createApp returns an express-like app', () => {
-    const config = getConfig();
-    const app = createApp(config);
-    expect(isFunction(app.get)).toBe(true);
-    expect(isFunction(app.use)).toBe(true);
-  });
-
-  test('index.html exists in configured app_dir', () => {
-    const config = getConfig();
-    const index_path = path.join(config.app_dir, 'index.html');
-    expect(fs.existsSync(index_path)).toBe(true);
-  });
-});

package/server/bd.test.js

@@ -1,93 +0,0 @@
-import { spawn as spawnMock } from 'node:child_process';
-import { EventEmitter } from 'node:events';
-import { PassThrough } from 'node:stream';
-import { beforeEach, describe, expect, test, vi } from 'vitest';
-import { getBdBin, runBd, runBdJson } from './bd.js';
-
-// Mock child_process.spawn before importing the module under test
-vi.mock('node:child_process', () => ({ spawn: vi.fn() }));
-
-/**
- * @param {string} stdoutText
- * @param {string} stderrText
- * @param {number} code
- */
-function makeFakeProc(stdoutText, stderrText, code) {
-  const cp = /** @type {any} */ (new EventEmitter());
-  const out = new PassThrough();
-  const err = new PassThrough();
-  cp.stdout = out;
-  cp.stderr = err;
-  // Simulate async emission
-  queueMicrotask(() => {
-    if (stdoutText) {
-      out.write(stdoutText);
-    }
-    out.end();
-    if (stderrText) {
-      err.write(stderrText);
-    }
-    err.end();
-    cp.emit('close', code);
-  });
-  return cp;
-}
-
-const mockedSpawn = /** @type {import('vitest').Mock} */ (spawnMock);
-
-beforeEach(() => {
-  mockedSpawn.mockReset();
-});
-
-describe('getBdBin', () => {
-  test('returns env BD_BIN when set', () => {
-    const prev = process.env.BD_BIN;
-    process.env.BD_BIN = '/custom/bd';
-    expect(getBdBin()).toBe('/custom/bd');
-    if (prev) {
-      process.env.BD_BIN = prev;
-    } else {
-      delete process.env.BD_BIN;
-    }
-  });
-});
-
-describe('runBd', () => {
-  test('returns stdout/stderr and exit code', async () => {
-    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
-    const res = await runBd(['--version']);
-    expect(res.code).toBe(0);
-    expect(res.stdout).toContain('ok');
-  });
-
-  test('non-zero exit propagates code and stderr', async () => {
-    mockedSpawn.mockReturnValueOnce(makeFakeProc('', 'boom', 1));
-    const res = await runBd(['list']);
-    expect(res.code).toBe(1);
-    expect(res.stderr).toContain('boom');
-  });
-});
-
-describe('runBdJson', () => {
-  test('parses valid JSON output', async () => {
-    const json = JSON.stringify([{ id: 'UI-1' }]);
-    mockedSpawn.mockReturnValueOnce(makeFakeProc(json, '', 0));
-    const res = await runBdJson(['list', '--json']);
-    expect(res.code).toBe(0);
-    expect(Array.isArray(res.stdoutJson)).toBe(true);
-  });
-
-  test('invalid JSON yields stderr message with code 0', async () => {
-    mockedSpawn.mockReturnValueOnce(makeFakeProc('not-json', '', 0));
-    const res = await runBdJson(['list', '--json']);
-    expect(res.code).toBe(0);
-    expect(res.stderr).toContain('Invalid JSON');
-  });
-
-  test('non-zero exit returns code and stderr', async () => {
-    mockedSpawn.mockReturnValueOnce(makeFakeProc('', 'oops', 2));
-    const res = await runBdJson(['list', '--json']);
-    expect(res.code).toBe(2);
-    expect(res.stderr).toContain('oops');
-  });
-});

package/server/cli/cli.test.js

@@ -1,109 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
-import * as commands from './commands.js';
-import { main, parseArgs } from './index.js';
-
-vi.mock('./commands.js', () => ({
-  handleStart: vi.fn().mockResolvedValue(0),
-  handleStop: vi.fn().mockResolvedValue(0),
-  handleRestart: vi.fn().mockResolvedValue(0)
-}));
-
-/** @type {import('vitest').MockInstance} */
-let write_mock;
-
-beforeEach(() => {
-  write_mock = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
-});
-
-afterEach(() => {
-  write_mock.mockRestore();
-});
-
-describe('parseArgs', () => {
-  test('returns help flag when -h or --help present', () => {
-    const r1 = parseArgs(['-h']);
-    const r2 = parseArgs(['--help']);
-
-    expect(r1.flags.includes('help')).toBe(true);
-    expect(r2.flags.includes('help')).toBe(true);
-  });
-
-  test('returns command token when valid', () => {
-    expect(parseArgs(['start']).command).toBe('start');
-    expect(parseArgs(['stop']).command).toBe('stop');
-    expect(parseArgs(['restart']).command).toBe('restart');
-  });
-
-  test('recognizes --no-open flag', () => {
-    const r = parseArgs(['start', '--no-open']);
-
-    expect(r.flags.includes('no-open')).toBe(true);
-  });
-});
-
-describe('main', () => {
-  test('prints usage and exits 0 on --help', async () => {
-    const code = await main(['--help']);
-
-    expect(code).toBe(0);
-    expect(write_mock).toHaveBeenCalled();
-  });
-
-  test('prints usage and exits 1 on no command', async () => {
-    const code = await main([]);
-
-    expect(code).toBe(1);
-    expect(write_mock).toHaveBeenCalled();
-  });
-
-  test('dispatches to start handler', async () => {
-    const code = await main(['start']);
-
-    expect(code).toBe(0);
-    expect(commands.handleStart).toHaveBeenCalledTimes(1);
-  });
-
-  test('propagates --no-open to start handler', async () => {
-    await main(['start', '--no-open']);
-
-    expect(commands.handleStart).toHaveBeenCalledWith({ no_open: true });
-  });
-
-  test('reads BDUI_NO_OPEN=1 to disable open', async () => {
-    const prev = process.env.BDUI_NO_OPEN;
-    try {
-      process.env.BDUI_NO_OPEN = '1';
-
-      await main(['start']);
-
-      expect(commands.handleStart).toHaveBeenCalledWith({ no_open: true });
-    } finally {
-      if (prev === undefined) {
-        delete process.env.BDUI_NO_OPEN;
-      } else {
-        process.env.BDUI_NO_OPEN = prev;
-      }
-    }
-  });
-
-  test('dispatches to stop handler', async () => {
-    const code = await main(['stop']);
-
-    expect(code).toBe(0);
-    expect(commands.handleStop).toHaveBeenCalledTimes(1);
-  });
-
-  test('dispatches to restart handler', async () => {
-    const code = await main(['restart']);
-
-    expect(code).toBe(0);
-    expect(commands.handleRestart).toHaveBeenCalledTimes(1);
-  });
-
-  test('unknown command prints usage and exits 1', async () => {
-    const code = await main(['unknown']);
-
-    expect(code).toBe(1);
-    expect(write_mock).toHaveBeenCalled();
-  });
-});

package/server/cli/commands.integration.test.js

@@ -1,155 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import {
-  afterAll,
-  afterEach,
-  beforeAll,
-  describe,
-  expect,
-  test,
-  vi
-} from 'vitest';
-import { handleRestart, handleStart, handleStop } from './commands.js';
-import * as daemon from './daemon.js';
-
-// Mock browser open + readiness wait to avoid external effects and flakiness
-vi.mock('./open.js', () => ({
-  openUrl: async () => true,
-  waitForServer: async () => {}
-}));
-
-/** @type {string} */
-let tmp_runtime_dir;
-/** @type {Record<string, string | undefined>} */
-let prev_env;
-
-beforeAll(() => {
-  // Snapshot selected env vars to restore later
-  prev_env = {
-    BDUI_RUNTIME_DIR: process.env.BDUI_RUNTIME_DIR,
-    PORT: process.env.PORT,
-    BDUI_NO_OPEN: process.env.BDUI_NO_OPEN
-  };
-
-  tmp_runtime_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bdui-it-'));
-  process.env.BDUI_RUNTIME_DIR = tmp_runtime_dir;
-  // Use port 0 so OS assigns an ephemeral port; URL printing still occurs
-  process.env.PORT = '0';
-  // Ensure default start path would not attempt to open the browser if called via CLI
-  process.env.BDUI_NO_OPEN = '1';
-});
-
-afterEach(async () => {
-  // Ensure no stray daemon is left between tests
-  const pid = daemon.readPidFile();
-  if (pid && daemon.isProcessRunning(pid)) {
-    await daemon.terminateProcess(pid, 2000);
-  }
-  daemon.removePidFile();
-  // Clear the daemon log to keep noise down in CI
-  try {
-    fs.writeFileSync(daemon.getLogFilePath(), '', 'utf8');
-  } catch {
-    // ignore
-  }
-});
-
-afterAll(() => {
-  // Restore env
-  if (prev_env.BDUI_RUNTIME_DIR === undefined) {
-    delete process.env.BDUI_RUNTIME_DIR;
-  } else {
-    process.env.BDUI_RUNTIME_DIR = prev_env.BDUI_RUNTIME_DIR;
-  }
-
-  if (prev_env.PORT === undefined) {
-    delete process.env.PORT;
-  } else {
-    process.env.PORT = prev_env.PORT;
-  }
-
-  if (prev_env.BDUI_NO_OPEN === undefined) {
-    delete process.env.BDUI_NO_OPEN;
-  } else {
-    process.env.BDUI_NO_OPEN = prev_env.BDUI_NO_OPEN;
-  }
-
-  try {
-    fs.rmSync(tmp_runtime_dir, { recursive: true, force: true });
-  } catch {
-    // ignore
-  }
-});
-
-describe('commands integration', () => {
-  test('start then stop returns 0 and manages PID file', async () => {
-    // setup
-    const print_spy = vi
-      .spyOn(daemon, 'printServerUrl')
-      .mockImplementation(() => {});
-
-    // execution
-    const start_code = await handleStart({ no_open: true });
-
-    // assertion
-    expect(start_code).toBe(0);
-    const pid_after_start = daemon.readPidFile();
-    expect(typeof pid_after_start).toBe('number');
-    expect(Number(pid_after_start)).toBeGreaterThan(0);
-
-    // execution
-    const stop_code = await handleStop();
-
-    // assertion
-    expect(stop_code).toBe(0);
-    const pid_after_stop = daemon.readPidFile();
-    expect(pid_after_stop).toBeNull();
-
-    print_spy.mockRestore();
-  });
-
-  test('stop returns 2 when not running', async () => {
-    // execution
-    const code = await handleStop();
-
-    // assertion
-    expect(code).toBe(2);
-  });
-
-  test('start is idempotent when already running', async () => {
-    // setup
-    await handleStart({ no_open: true });
-    const start_spy = vi.spyOn(daemon, 'startDaemon');
-
-    // execution
-    const code = await handleStart({ no_open: true });
-
-    // assertion
-    expect(code).toBe(0);
-    expect(start_spy).not.toHaveBeenCalled();
-
-    // cleanup
-    start_spy.mockRestore();
-    await handleStop();
-  });
-
-  test('restart stops (when needed) and starts', async () => {
-    // setup
-    const print_spy = vi
-      .spyOn(daemon, 'printServerUrl')
-      .mockImplementation(() => {});
-
-    // execution
-    const code = await handleRestart();
-
-    // assertion
-    expect(code).toBe(0);
-    const pid = daemon.readPidFile();
-    expect(typeof pid).toBe('number');
-
-    // cleanup
-    await handleStop();
-    print_spy.mockRestore();
-  });
-});

package/server/cli/commands.unit.test.js

@@ -1,94 +0,0 @@
-import { describe, expect, test, vi } from 'vitest';
-import { handleStart, handleStop } from './commands.js';
-import * as daemon from './daemon.js';
-
-describe('handleStart (unit)', () => {
-  test('returns 1 when daemon start fails', async () => {
-    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(null);
-    const is_running = vi
-      .spyOn(daemon, 'isProcessRunning')
-      .mockReturnValue(false);
-    const start = vi.spyOn(daemon, 'startDaemon').mockReturnValue(null);
-
-    const code = await handleStart({ no_open: true });
-
-    expect(code).toBe(1);
-
-    read_pid.mockRestore();
-    is_running.mockRestore();
-    start.mockRestore();
-  });
-
-  test('returns 0 when already running', async () => {
-    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(12345);
-    const is_running = vi
-      .spyOn(daemon, 'isProcessRunning')
-      .mockReturnValue(true);
-    const print_url = vi
-      .spyOn(daemon, 'printServerUrl')
-      .mockImplementation(() => {});
-
-    const code = await handleStart({ no_open: true });
-
-    expect(code).toBe(0);
-    expect(print_url).toHaveBeenCalledTimes(1);
-
-    read_pid.mockRestore();
-    is_running.mockRestore();
-    print_url.mockRestore();
-  });
-});
-
-describe('handleStop (unit)', () => {
-  test('returns 2 when not running and no PID file', async () => {
-    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(null);
-
-    const code = await handleStop();
-
-    expect(code).toBe(2);
-
-    read_pid.mockRestore();
-  });
-
-  test('returns 2 on stale PID and removes file', async () => {
-    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(1111);
-    const is_running = vi
-      .spyOn(daemon, 'isProcessRunning')
-      .mockReturnValue(false);
-    const remove_pid = vi
-      .spyOn(daemon, 'removePidFile')
-      .mockImplementation(() => {});
-
-    const code = await handleStop();
-
-    expect(code).toBe(2);
-    expect(remove_pid).toHaveBeenCalledTimes(1);
-
-    read_pid.mockRestore();
-    is_running.mockRestore();
-    remove_pid.mockRestore();
-  });
-
-  test('returns 0 when process terminates and removes PID', async () => {
-    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(2222);
-    const is_running = vi
-      .spyOn(daemon, 'isProcessRunning')
-      .mockReturnValue(true);
-    const terminate = vi
-      .spyOn(daemon, 'terminateProcess')
-      .mockResolvedValue(true);
-    const remove_pid = vi
-      .spyOn(daemon, 'removePidFile')
-      .mockImplementation(() => {});
-
-    const code = await handleStop();
-
-    expect(code).toBe(0);
-    expect(remove_pid).toHaveBeenCalledTimes(1);
-
-    read_pid.mockRestore();
-    is_running.mockRestore();
-    terminate.mockRestore();
-    remove_pid.mockRestore();
-  });
-});