beads-ui 0.1.0

package/docs/quickstart.md

@@ -0,0 +1,142 @@
+# 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

@@ -0,0 +1,59 @@
+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/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "beads-ui",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "bdui": "bin/bdui.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "all": "npm run lint && npm run typecheck && npm test && npm run format:check",
+    "start": "node server/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .js .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "preversion": "npm run all",
+    "version": "changes",
+    "postversion": "git push --follow-tags && npm publish"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.38.0",
+    "@studio/changes": "^3.0.0",
+    "@trivago/prettier-plugin-sort-imports": "^5.2.2",
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.7.4",
+    "@types/ws": "^8.18.1",
+    "eslint": "^9.11.0",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^48.10.2",
+    "eslint-plugin-n": "^17.9.0",
+    "eslint-plugin-promise": "^6.1.1",
+    "globals": "^16.4.0",
+    "jsdom": "^27.0.1",
+    "prettier": "^3.3.3",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.11",
+    "express": "^5.1.0",
+    "lit-html": "^3.3.1",
+    "ws": "^8.18.3"
+  }
+}

package/prettier.config.js

@@ -0,0 +1,13 @@
+/**
+ * @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.js

@@ -0,0 +1,80 @@
+/**
+ * @import { Express, Request, Response } from 'express'
+ */
+import express from 'express';
+import path from 'node:path';
+
+/**
+ * Create and configure the Express application.
+ * @param {{ host: string, port: number, env: string, app_dir: string, root_dir: string }} config - Server configuration.
+ * @returns {Express} Configured Express app instance.
+ */
+export function createApp(config) {
+  const app = express();
+
+  // Basic hardening and config
+  app.disable('x-powered-by');
+
+  // Health endpoint
+  /**
+   * @param {Request} _req
+   * @param {Response} res
+   */
+  app.get('/healthz', (_req, res) => {
+    res.type('application/json');
+    res.status(200).send({ ok: true });
+  });
+
+  /**
+   * On-demand bundle for the browser using esbuild.
+   * Note: esbuild is loaded lazily so tests don't require it to be installed.
+   * @param {Request} _req
+   * @param {Response} res
+   */
+  app.get('/main.bundle.js', async (_req, res) => {
+    try {
+      const esbuild = await import('esbuild');
+      const entry = path.join(config.app_dir, 'main.js');
+      const result = await esbuild.build({
+        entryPoints: [entry],
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2020',
+        sourcemap: config.env === 'production' ? false : 'inline',
+        minify: config.env === 'production',
+        write: false
+      });
+      const out = result.outputFiles && result.outputFiles[0];
+      if (!out) {
+        res.status(500).type('text/plain').send('Bundle failed: no output');
+        return;
+      }
+      res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+      if (config.env !== 'production') {
+        res.setHeader('Cache-Control', 'no-store');
+      }
+      res.send(out.text);
+    } catch (err) {
+      res
+        .status(500)
+        .type('text/plain')
+        .send('Bundle error: ' + (err && /** @type {any} */ (err).message));
+    }
+  });
+
+  // Static assets from /app
+  app.use(express.static(config.app_dir));
+
+  // Root serves index.html explicitly (even if static would catch it)
+  /**
+   * @param {Request} _req
+   * @param {Response} res
+   */
+  app.get('/', (_req, res) => {
+    const index_path = path.join(config.app_dir, 'index.html');
+    res.sendFile(index_path);
+  });
+
+  return app;
+}

package/server/app.test.js

@@ -0,0 +1,29 @@
+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.js

@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process';
+import { resolveDbPath } from './db.js';
+
+/**
+ * Resolve the bd executable path.
+ * @returns {string}
+ */
+export function getBdBin() {
+  const env_value = process.env.BD_BIN;
+  if (env_value && env_value.length > 0) {
+    return env_value;
+  }
+  return 'bd';
+}
+
+/**
+ * Run the `bd` CLI with provided arguments.
+ * Shell is not used to avoid injection; args must be pre-split.
+ * @param {string[]} args - Arguments to pass (e.g., ["list", "--json"]).
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+export function runBd(args, options = {}) {
+  const bin = getBdBin();
+  const spawn_opts = {
+    cwd: options.cwd || process.cwd(),
+    env: options.env ? options.env : process.env,
+    shell: false
+  };
+
+  // Ensure a consistent DB by injecting --db if missing, following beads precedence.
+  /** @type {string[]} */
+  const finalArgs = withDbArg(args, spawn_opts.cwd, spawn_opts.env);
+
+  return new Promise((resolve) => {
+    const child = spawn(bin, finalArgs, spawn_opts);
+
+    /** @type {string[]} */
+    const out_chunks = [];
+    /** @type {string[]} */
+    const err_chunks = [];
+
+    if (child.stdout) {
+      child.stdout.setEncoding('utf8');
+      /** @param {string} chunk */
+      child.stdout.on('data', (chunk) => {
+        out_chunks.push(String(chunk));
+      });
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding('utf8');
+      /** @param {string} chunk */
+      child.stderr.on('data', (chunk) => {
+        err_chunks.push(String(chunk));
+      });
+    }
+
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timer;
+    if (options.timeout_ms && options.timeout_ms > 0) {
+      timer = setTimeout(() => {
+        child.kill('SIGKILL');
+      }, options.timeout_ms);
+      timer.unref?.();
+    }
+
+    /**
+     * @param {number | string | null} code
+     */
+    const finish = (code) => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve({
+        code: Number(code || 0),
+        stdout: out_chunks.join(''),
+        stderr: err_chunks.join('')
+      });
+    };
+
+    child.on('error', () => {
+      // Treat spawn error as an immediate non-zero exit with captured stderr message.
+      finish(127);
+    });
+    child.on('close', (code) => {
+      finish(code);
+    });
+  });
+}
+
+/**
+ * Run `bd` and parse JSON from stdout if exit code is 0.
+ * @param {string[]} args - Must include flags that cause JSON to be printed (e.g., `--json`).
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
+ * @returns {Promise<{ code: number, stdoutJson?: unknown, stderr?: string }>}
+ */
+export async function runBdJson(args, options = {}) {
+  const result = await runBd(args, options);
+  if (result.code !== 0) {
+    return { code: result.code, stderr: result.stderr };
+  }
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout || 'null');
+  } catch {
+    return { code: 0, stderr: 'Invalid JSON from bd' };
+  }
+  return { code: 0, stdoutJson: parsed };
+}
+
+/**
+ * Add a resolved "--db <path>" pair to args when none present.
+ * @param {string[]} args
+ * @param {string} cwd
+ * @param {Record<string, string | undefined>} env
+ * @returns {string[]}
+ */
+function withDbArg(args, cwd, env) {
+  if (args.includes('--db')) {
+    return args.slice();
+  }
+  const resolved = resolveDbPath({ cwd, env });
+  return ['--db', resolved.path, ...args];
+}

package/server/bd.test.js

@@ -0,0 +1,93 @@
+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');
+  });
+});