beads-enhanced-ui 0.1.0

package/bin/bdui.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Thin CLI entry for `bdui`.
+ * Delegates to `server/cli/index.js` and sets the process exit code.
+ */
+import { main } from '../server/cli/index.js';
+import { debug } from '../server/logging.js';
+
+const argv = process.argv.slice(2);
+
+try {
+  const code = await main(argv);
+  if (Number.isFinite(code)) {
+    process.exitCode = code;
+  }
+} catch (err) {
+  debug('cli')('fatal %o', err);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "beads-enhanced-ui",
+  "version": "0.1.0",
+  "description": "Enhanced local UI for Beads with improved epic rows, status labels, and UX refinements.",
+  "keywords": [
+    "agent",
+    "issue-tracker",
+    "local-first",
+    "ai-tools"
+  ],
+  "homepage": "https://github.com/AlexeyPlatkovsky/beads-enhanced-ui#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexeyPlatkovsky/beads-enhanced-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlexeyPlatkovsky/beads-enhanced-ui/issues"
+  },
+  "author": "Alexey Platkovsky",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "bdui": "bin/bdui.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "all": "npm run lint && npm run tsc && npm test && npm run test:coverage:app && npm run prettier:check",
+    "start": "node server/index.js --debug",
+    "build": "node scripts/build-frontend.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:app": "vitest run --project=jsdom --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "tsc": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .js .",
+    "prettier:write": "prettier --write .",
+    "prettier:check": "prettier --check .",
+    "preversion": "npm run all",
+    "version": "changes --commits --footer",
+    "postversion": "git push --follow-tags && npm publish",
+    "prepack": "npm run build",
+    "postpack": "rm app/main.bundle.js app/main.bundle.js.map"
+  },
+  "dependencies": {
+    "debug": "^4.4.3",
+    "dompurify": "^3.3.0",
+    "express": "^5.2.1",
+    "lit-html": "^3.3.1",
+    "marked": "^17.0.1",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@playwright/test": "^1.58.2",
+    "@studio/changes": "^3.0.0",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.0",
+    "@types/debug": "^4.1.12",
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.19.1",
+    "@types/ws": "^8.18.1",
+    "@vitest/coverage-v8": "^4.1.2",
+    "esbuild": "^0.27.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-import": "^2.29.1",
+    "eslint-plugin-jsdoc": "^61.4.1",
+    "eslint-plugin-n": "^17.9.0",
+    "globals": "^16.5.0",
+    "jsdom": "^27.2.0",
+    "prettier": "^3.7.4",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.15"
+  },
+  "files": [
+    "app/index.html",
+    "app/styles.css",
+    "app/main.bundle.js",
+    "app/main.bundle.js.map",
+    "app/protocol.js",
+    "bin",
+    "server",
+    "CHANGES.md",
+    "LICENSE",
+    "README.md",
+    "!**/*.test.js"
+  ]
+}

package/server/app.js

@@ -0,0 +1,110 @@
+/**
+ * @import { Express, Request, Response } from 'express'
+ */
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import { registerWorkspace } from './registry-watcher.js';
+
+/**
+ * Create and configure the Express application.
+ *
+ * @param {{ host: string, port: number, 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 });
+  });
+
+  // Enable JSON body parsing for API endpoints
+  app.use(express.json());
+
+  // Register workspace endpoint - allows CLI to register workspaces dynamically
+  // when the server is already running
+  /**
+   * @param {Request} req
+   * @param {Response} res
+   */
+  app.post('/api/register-workspace', (req, res) => {
+    const { path: workspace_path, database } = req.body || {};
+    if (!workspace_path || typeof workspace_path !== 'string') {
+      res.status(400).json({ ok: false, error: 'Missing or invalid path' });
+      return;
+    }
+    if (!database || typeof database !== 'string') {
+      res.status(400).json({ ok: false, error: 'Missing or invalid database' });
+      return;
+    }
+    registerWorkspace({ path: workspace_path, database });
+    res.status(200).json({ ok: true, registered: workspace_path });
+  });
+
+  if (
+    !fs.statSync(path.resolve(config.app_dir, 'main.bundle.js'), {
+      throwIfNoEntry: false
+    })
+  ) {
+    /**
+     * On-demand bundle for the browser using esbuild.
+     *
+     * @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: 'inline',
+          minify: false,
+          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');
+        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/bd.js

@@ -0,0 +1,227 @@
+import { spawn } from 'node:child_process';
+import { resolveDbPath } from './db.js';
+import { debug } from './logging.js';
+
+const log = debug('bd');
+/** @type {Promise<void>} */
+let bd_run_queue = Promise.resolve();
+
+/**
+ * Get the git user name from git config.
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<string>}
+ */
+export async function getGitUserName(options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn('git', ['config', 'user.name'], {
+      cwd: options.cwd || process.cwd(),
+      shell: false,
+      windowsHide: true
+    });
+
+    /** @type {string[]} */
+    const chunks = [];
+
+    if (child.stdout) {
+      child.stdout.setEncoding('utf8');
+      child.stdout.on('data', (chunk) => chunks.push(String(chunk)));
+    }
+
+    child.on('error', () => resolve(''));
+    child.on('close', (code) => {
+      if (code !== 0) {
+        resolve('');
+        return;
+      }
+      resolve(chunks.join('').trim());
+    });
+  });
+}
+
+/**
+ * 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 = {}) {
+  return withBdRunQueue(async () => runBdUnlocked(args, options));
+}
+
+/**
+ * Run the `bd` CLI with provided arguments without queueing.
+ *
+ * @param {string[]} args
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, timeout_ms?: number }} [options]
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+function runBdUnlocked(args, options = {}) {
+  const bin = getBdBin();
+
+  // Set BEADS_DB only when the workspace has a local SQLite DB.
+  // Do not force BEADS_DB from global fallback paths; this can override
+  // backend autodetection in non-SQLite workspaces (for example Dolt).
+  const db_path = resolveDbPath({
+    cwd: options.cwd || process.cwd(),
+    env: options.env || process.env
+  });
+  const env_with_db = { ...(options.env || process.env) };
+  if (db_path.source === 'nearest' && db_path.exists) {
+    env_with_db.BEADS_DB = db_path.path;
+  }
+
+  const spawn_opts = {
+    cwd: options.cwd || process.cwd(),
+    env: env_with_db,
+    shell: false,
+    windowsHide: true
+  };
+
+  /** @type {string[]} */
+  const final_args = buildBdArgs(args);
+
+  return new Promise((resolve) => {
+    const child = spawn(bin, final_args, spawn_opts);
+
+    /** @type {string[]} */
+    const out_chunks = [];
+    /** @type {string[]} */
+    const err_chunks = [];
+
+    if (child.stdout) {
+      child.stdout.setEncoding('utf8');
+      child.stdout.on('data', (chunk) => {
+        out_chunks.push(String(chunk));
+      });
+    }
+    if (child.stderr) {
+      child.stderr.setEncoding('utf8');
+      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', (err) => {
+      // Treat spawn error as an immediate non-zero exit; log for diagnostics.
+      log('spawn error running %s %o', bin, err);
+      finish(127);
+    });
+    child.on('close', (code) => {
+      finish(code);
+    });
+  });
+}
+
+/**
+ * Build final bd CLI arguments.
+ * bdui defaults to sandbox mode to avoid sync/autopush overhead on interactive
+ * UI requests. Set `BDUI_BD_SANDBOX=0` (or "false") to opt out.
+ *
+ * @param {string[]} args
+ * @returns {string[]}
+ */
+function buildBdArgs(args) {
+  const arg_set = new Set(args);
+  const raw_sandbox = String(process.env.BDUI_BD_SANDBOX || '').toLowerCase();
+  const sandbox_disabled = raw_sandbox === '0' || raw_sandbox === 'false';
+  const should_prepend_sandbox = !sandbox_disabled && !arg_set.has('--sandbox');
+
+  if (!should_prepend_sandbox) {
+    return args.slice();
+  }
+
+  return ['--sandbox', ...args];
+}
+
+/**
+ * Serialize `bd` invocations.
+ * Dolt embedded mode can crash when multiple `bd` processes run concurrently
+ * against the same workspace.
+ *
+ * @template T
+ * @param {() => Promise<T>} operation
+ * @returns {Promise<T>}
+ */
+async function withBdRunQueue(operation) {
+  const previous = bd_run_queue;
+  /** @type {() => void} */
+  let release = () => {};
+  bd_run_queue = new Promise((resolve) => {
+    release = resolve;
+  });
+
+  await previous.catch(() => {});
+  try {
+    return await operation();
+  } finally {
+    release();
+  }
+}
+
+/**
+ * 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) {
+    log(
+      'bd exited with code %d (args=%o) stderr=%s',
+      result.code,
+      args,
+      result.stderr
+    );
+    return { code: result.code, stderr: result.stderr };
+  }
+  /** @type {unknown} */
+  let parsed;
+  try {
+    parsed = JSON.parse(result.stdout || 'null');
+  } catch (err) {
+    log('bd returned invalid JSON (args=%o): %o', args, err);
+    return { code: 0, stderr: 'Invalid JSON from bd' };
+  }
+  return { code: 0, stdoutJson: parsed };
+}

package/server/cli/commands.js

@@ -0,0 +1,203 @@
+import { getConfig } from '../config.js';
+import { resolveWorkspaceDatabase } from '../db.js';
+import {
+  isProcessRunning,
+  printServerUrl,
+  readPidFile,
+  removePidFile,
+  startDaemon,
+  terminateProcess
+} from './daemon.js';
+import { openUrl, registerWorkspaceWithServer, waitForServer } from './open.js';
+
+const STARTUP_SETTLE_MS = 200;
+const REGISTER_RETRY_ATTEMPTS = 5;
+const REGISTER_RETRY_DELAY_MS = 150;
+
+/**
+ * Handle `start` command. Idempotent when already running.
+ * - Spawns a detached server process, writes PID file, returns 0.
+ * - If already running (PID file present and process alive), prints URL and returns 0.
+ *
+ * @param {{ open?: boolean, is_debug?: boolean, host?: string, port?: number }} [options]
+ * @returns {Promise<number>} Exit code (0 on success)
+ */
+export async function handleStart(options) {
+  // Default: do not open a browser unless explicitly requested via `open: true`.
+  const should_open = options?.open === true;
+  const cwd = process.cwd();
+
+  // Set env vars early so getConfig() reflects CLI overrides in ALL branches,
+  // including the "already running" path that registers workspaces via HTTP.
+  if (options?.host) {
+    process.env.HOST = options.host;
+  }
+  if (options?.port) {
+    process.env.PORT = String(options.port);
+  }
+
+  const existing_pid = readPidFile();
+  if (existing_pid && isProcessRunning(existing_pid)) {
+    // Server is already running - register this workspace dynamically
+    const { url } = getConfig();
+    const registered = await registerCurrentWorkspace(url, cwd);
+    if (registered) {
+      console.log('Workspace registered: %s', cwd);
+    }
+    console.warn('Server is already running.');
+    if (should_open) {
+      await openUrl(url);
+    }
+    return 0;
+  }
+  if (existing_pid && !isProcessRunning(existing_pid)) {
+    // stale PID file
+    removePidFile();
+  }
+
+  const { url } = getConfig();
+
+  const started = startDaemon({
+    is_debug: options?.is_debug,
+    host: options?.host,
+    port: options?.port
+  });
+  if (started && started.pid > 0) {
+    // Give the spawned daemon a brief moment to fail fast (for example EADDRINUSE).
+    await sleep(STARTUP_SETTLE_MS);
+
+    if (!isProcessRunning(started.pid)) {
+      removePidFile();
+
+      // If another server is already running at the configured URL, register this
+      // workspace there so it appears in the picker instead of silently missing.
+      const registered = await registerCurrentWorkspaceWithRetry(url, cwd);
+      if (registered) {
+        console.warn(
+          'Daemon exited early; registered workspace with existing server: %s',
+          cwd
+        );
+        return 0;
+      }
+      return 1;
+    }
+
+    // Register against the currently reachable server to ensure this workspace
+    // appears in the picker even when startup races with other daemons.
+    void registerCurrentWorkspaceWithRetry(url, cwd);
+
+    printServerUrl();
+    // Auto-open the browser once for a fresh daemon start
+    if (should_open) {
+      // Wait briefly for the server to accept connections (single retry window)
+      await waitForServer(url, 600);
+      // Best-effort open; ignore result
+      await openUrl(url);
+    }
+    return 0;
+  }
+
+  return 1;
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}
+
+/**
+ * @param {string} url
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function registerCurrentWorkspace(url, cwd) {
+  const workspace_database = resolveWorkspaceDatabase({ cwd });
+  if (
+    workspace_database.source === 'home-default' ||
+    !workspace_database.exists
+  ) {
+    return false;
+  }
+
+  return registerWorkspaceWithServer(url, {
+    path: cwd,
+    database: workspace_database.path
+  });
+}
+
+/**
+ * @param {string} url
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function registerCurrentWorkspaceWithRetry(url, cwd) {
+  for (let i = 0; i < REGISTER_RETRY_ATTEMPTS; i++) {
+    const registered = await registerCurrentWorkspace(url, cwd);
+    if (registered) {
+      return true;
+    }
+    if (i < REGISTER_RETRY_ATTEMPTS - 1) {
+      await sleep(REGISTER_RETRY_DELAY_MS);
+    }
+  }
+  return false;
+}
+
+/**
+ * Handle `stop` command.
+ * - Sends SIGTERM and waits for exit (with SIGKILL fallback), removes PID file.
+ * - Returns 2 if not running.
+ *
+ * @returns {Promise<number>} Exit code
+ */
+export async function handleStop() {
+  const existing_pid = readPidFile();
+  if (!existing_pid) {
+    return 2;
+  }
+
+  if (!isProcessRunning(existing_pid)) {
+    // stale PID file
+    removePidFile();
+    return 2;
+  }
+
+  const terminated = await terminateProcess(existing_pid, 5000);
+  if (terminated) {
+    removePidFile();
+    return 0;
+  }
+
+  // Not terminated within timeout
+  return 1;
+}
+
+/**
+ * Handle `restart` command: stop (ignore not-running) then start.
+ *
+ * @returns {Promise<number>} Exit code (0 on success)
+ */
+/**
+ * Handle `restart` command: stop (ignore not-running) then start.
+ * Accepts the same options as `handleStart` and passes them through,
+ * so restart only opens a browser when `open` is explicitly true.
+ *
+ * @param {{ open?: boolean }} [options]
+ * @returns {Promise<number>}
+ */
+export async function handleRestart(options) {
+  const stop_code = await handleStop();
+  // 0 = stopped, 2 = not running; both are acceptable to proceed
+  if (stop_code !== 0 && stop_code !== 2) {
+    return 1;
+  }
+  const start_code = await handleStart(options);
+  return start_code === 0 ? 0 : 1;
+}