@seungyeop-lee/beads-ui 0.13.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,82 @@
+{
+  "name": "@seungyeop-lee/beads-ui",
+  "version": "0.13.0",
+  "description": "Local UI for Beads — Collaborate on issues with your coding agent.",
+  "keywords": [
+    "agent",
+    "issue-tracker",
+    "local-first",
+    "ai-tools"
+  ],
+  "homepage": "https://github.com/seungyeop-lee/beads-ui",
+  "author": "seungyeop-lee",
+  "type": "module",
+  "bin": {
+    "bdui": "bin/bdui.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "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",
+    "@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",
+    "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",
+    "lefthook": "^2.1.6",
+    "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"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seungyeop-lee/beads-ui.git"
+  },
+  "scripts": {
+    "all": "pnpm lint && pnpm tsc && pnpm test && pnpm prettier:check",
+    "start": "node server/index.js --debug",
+    "build": "node scripts/build-frontend.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "tsc": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint --ext .js .",
+    "prettier:write": "prettier --write .",
+    "prettier:check": "prettier --check .",
+    "preversion": "pnpm all",
+    "version": "changes --commits --footer",
+    "postversion": "git push --follow-tags && pnpm publish"
+  }
+}

package/server/app.js

@@ -0,0 +1,119 @@
+/**
+ * @import { Express, Request, Response } from 'express'
+ */
+import express from 'express';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  getAvailableWorkspaces,
+  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 });
+  });
+
+  // List all known workspaces (file-based registry + in-memory)
+  app.get('/api/workspaces', (_req, res) => {
+    const workspaces = getAvailableWorkspaces();
+    res.status(200).json({ ok: true, workspaces });
+  });
+
+  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 };
+}