@rsktash/beads-ui 0.1.0

package/server/app.js

@@ -0,0 +1,120 @@
+/**
+ * @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 — prefer BEADS_UI_STATIC (Vite build output), fall back to app_dir
+  const staticDir = process.env.BEADS_UI_STATIC || config.app_dir;
+  app.use(express.static(staticDir));
+
+  // 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(staticDir, 'index.html');
+    res.sendFile(index_path);
+  });
+
+  return app;
+}

package/server/app.test.js

@@ -0,0 +1,30 @@
+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,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/bd.test.js

@@ -0,0 +1,194 @@
+import { spawn as spawnMock } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { PassThrough } from 'node:stream';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { getBdBin, getGitUserName, 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
+  setTimeout(() => {
+    if (stdoutText) {
+      out.write(stdoutText);
+    }
+    out.end();
+    if (stderrText) {
+      err.write(stderrText);
+    }
+    err.end();
+    cp.emit('close', code);
+  }, 0);
+  return cp;
+}
+
+const mockedSpawn = /** @type {import('vitest').Mock} */ (spawnMock);
+/** @type {string[]} */
+const temp_dirs = [];
+
+function make_temp_dir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bdui-bd-'));
+  temp_dirs.push(dir);
+  return dir;
+}
+
+beforeEach(() => {
+  mockedSpawn.mockReset();
+});
+
+afterEach(() => {
+  for (const dir of temp_dirs.splice(0)) {
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+});
+
+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('prepends --sandbox by default', async () => {
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+    await runBd(['list', '--json']);
+
+    const args = mockedSpawn.mock.calls[0][1];
+    expect(args[0]).toBe('--sandbox');
+    expect(args.slice(1)).toEqual(['list', '--json']);
+  });
+
+  test('does not duplicate --sandbox when caller already provides it', async () => {
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+    await runBd(['--sandbox', 'list', '--json']);
+
+    const args = mockedSpawn.mock.calls[0][1];
+    expect(args).toEqual(['--sandbox', 'list', '--json']);
+  });
+
+  test('allows disabling default sandbox via BDUI_BD_SANDBOX', async () => {
+    const prev = process.env.BDUI_BD_SANDBOX;
+    process.env.BDUI_BD_SANDBOX = '0';
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+
+    await runBd(['list', '--json']);
+
+    const args = mockedSpawn.mock.calls[0][1];
+    expect(args).toEqual(['list', '--json']);
+
+    if (prev === undefined) {
+      delete process.env.BDUI_BD_SANDBOX;
+    } else {
+      process.env.BDUI_BD_SANDBOX = prev;
+    }
+  });
+
+  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');
+  });
+
+  test('sets BEADS_DB for workspace-local SQLite db', async () => {
+    const root = make_temp_dir();
+    const beads_dir = path.join(root, '.beads');
+    fs.mkdirSync(beads_dir, { recursive: true });
+    const workspace_db = path.join(beads_dir, 'ui.db');
+    fs.writeFileSync(workspace_db, '');
+
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+    await runBd(['list'], { cwd: root, env: {} });
+
+    const options = mockedSpawn.mock.calls[0][2];
+    expect(options.env.BEADS_DB).toBe(workspace_db);
+  });
+
+  test('does not force BEADS_DB when workspace has no local SQLite db', async () => {
+    const root = make_temp_dir();
+
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+    await runBd(['list'], { cwd: root, env: {} });
+
+    const options = mockedSpawn.mock.calls[0][2];
+    expect(options.env.BEADS_DB).toBeUndefined();
+  });
+
+  test('preserves explicit BEADS_DB from caller env', async () => {
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('ok', '', 0));
+    await runBd(['list'], { env: { BEADS_DB: '/custom/workspace.db' } });
+
+    const options = mockedSpawn.mock.calls[0][2];
+    expect(options.env.BEADS_DB).toBe('/custom/workspace.db');
+  });
+});
+
+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');
+  });
+});
+
+describe('getGitUserName', () => {
+  test('returns git user name on success', async () => {
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('Alice Smith\n', '', 0));
+    const name = await getGitUserName();
+    expect(name).toBe('Alice Smith');
+  });
+
+  test('returns empty string on failure', async () => {
+    mockedSpawn.mockReturnValueOnce(makeFakeProc('', 'error', 1));
+    const name = await getGitUserName();
+    expect(name).toBe('');
+  });
+});