@rsktash/beads-ui 0.1.0

package/server/cli/usage.js

@@ -0,0 +1,27 @@
+/**
+ * Print CLI usage to a stream-like target.
+ *
+ * @param {{ write: (chunk: string) => any }} out_stream
+ */
+export function printUsage(out_stream) {
+  const lines = [
+    'Usage: bdui <command> [options]',
+    '',
+    'Commands:',
+    '  start       Start the UI server',
+    '  stop        Stop the UI server',
+    '  restart     Restart the UI server',
+    '',
+    'Options:',
+    '  -h, --help        Show this help message',
+    '  -v, --version     Show the CLI version',
+    '  -d, --debug       Enable debug logging',
+    '      --open        Open the browser after start/restart',
+    '      --host <addr> Bind to a specific host (default: 127.0.0.1)',
+    '      --port <num>  Bind to a specific port (default: 3000)',
+    ''
+  ];
+  for (const line of lines) {
+    out_stream.write(line + '\n');
+  }
+}

package/server/config.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve runtime configuration for the server.
+ * Notes:
+ * - `app_dir` is resolved relative to the installed package location.
+ * - `root_dir` represents the directory where the process was invoked
+ * (i.e., the current working directory) so DB resolution follows the
+ * caller's context rather than the install location.
+ *
+ * @returns {{ host: string, port: number, app_dir: string, root_dir: string, url: string }}
+ */
+export function getConfig() {
+  const this_file = fileURLToPath(new URL(import.meta.url));
+  const server_dir = path.dirname(this_file);
+  const package_root = path.resolve(server_dir, '..');
+  // Always reflect the directory from which the process was started
+  const root_dir = process.cwd();
+
+  let port_value = Number.parseInt(process.env.PORT || '', 10);
+  if (!Number.isFinite(port_value)) {
+    port_value = 3333;
+  }
+
+  const host_env = process.env.HOST;
+  const host_value = host_env && host_env.length > 0 ? host_env : '127.0.0.1';
+
+  return {
+    host: host_value,
+    port: port_value,
+    app_dir: path.resolve(package_root, 'app'),
+    root_dir,
+    url: `http://${host_value}:${port_value}`
+  };
+}

package/server/db.js

@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/**
+ * Resolve the SQLite DB path used by beads according to precedence:
+ * 1) explicit --db flag (provided via options.explicit_db)
+ * 2) BEADS_DB environment variable
+ * 3) nearest ".beads/*.db" by walking up from cwd (excluding
+ *    "~/.beads/default.db", which is reserved for fallback)
+ * 4) "~/.beads/default.db" fallback
+ *
+ * Returns a normalized absolute path and a `source` indicator. Existence is
+ * returned via the `exists` boolean.
+ *
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, explicit_db?: string }} [options]
+ * @returns {{ path: string, source: 'flag'|'env'|'nearest'|'home-default', exists: boolean }}
+ */
+export function resolveDbPath(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const env = options.env || process.env;
+  const home_default = path.join(os.homedir(), '.beads', 'default.db');
+
+  // 1) explicit flag
+  if (options.explicit_db && options.explicit_db.length > 0) {
+    const p = absFrom(options.explicit_db, cwd);
+    return { path: p, source: 'flag', exists: fileExists(p) };
+  }
+
+  // 2) BEADS_DB env
+  if (env.BEADS_DB && String(env.BEADS_DB).length > 0) {
+    const p = absFrom(String(env.BEADS_DB), cwd);
+    return { path: p, source: 'env', exists: fileExists(p) };
+  }
+
+  // 3) nearest .beads/*.db walking up
+  const nearest = findNearestBeadsDb(cwd);
+  if (nearest && path.normalize(nearest) !== path.normalize(home_default)) {
+    return { path: nearest, source: 'nearest', exists: fileExists(nearest) };
+  }
+
+  // 4) ~/.beads/default.db
+  return {
+    path: home_default,
+    source: 'home-default',
+    exists: fileExists(home_default)
+  };
+}
+
+/**
+ * Resolve the workspace database location used by the UI/server.
+ *
+ * For non-SQLite backends (for example Dolt), this returns the nearest
+ * workspace `.beads` directory when metadata exists. This avoids collapsing
+ * all such workspaces onto the `~/.beads/default.db` fallback.
+ *
+ * @param {{ cwd?: string, env?: Record<string, string | undefined>, explicit_db?: string }} [options]
+ * @returns {{ path: string, source: 'flag'|'env'|'nearest'|'metadata'|'home-default', exists: boolean }}
+ */
+export function resolveWorkspaceDatabase(options = {}) {
+  const sqlite_db = resolveDbPath(options);
+  if (sqlite_db.source !== 'home-default') {
+    return sqlite_db;
+  }
+
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const metadata_path = findNearestBeadsMetadata(cwd);
+  if (metadata_path) {
+    return {
+      path: path.dirname(metadata_path),
+      source: 'metadata',
+      exists: true
+    };
+  }
+
+  return sqlite_db;
+}
+
+/**
+ * Find nearest `.beads/metadata.json` by walking up from start.
+ *
+ * @param {string} start
+ * @returns {string | null}
+ */
+export function findNearestBeadsMetadata(start) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 100; i++) {
+    const metadata_path = path.join(dir, '.beads', 'metadata.json');
+    if (fileExists(metadata_path)) {
+      return metadata_path;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Find nearest .beads/*.db by walking up from start.
+ * First alphabetical .db.
+ *
+ * @param {string} start
+ * @returns {string | null}
+ */
+export function findNearestBeadsDb(start) {
+  let dir = path.resolve(start);
+  // Cap iterations to avoid infinite loop in degenerate cases
+  for (let i = 0; i < 100; i++) {
+    const beads_dir = path.join(dir, '.beads');
+    try {
+      const entries = fs.readdirSync(beads_dir, { withFileTypes: true });
+      const dbs = entries
+        .filter((e) => e.isFile() && e.name.endsWith('.db'))
+        .map((e) => e.name)
+        .sort();
+      if (dbs.length > 0) {
+        return path.join(beads_dir, dbs[0]);
+      }
+    } catch {
+      // ignore and walk up
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Resolve possibly relative `p` against `cwd` to an absolute filesystem path.
+ *
+ * @param {string} p
+ * @param {string} cwd
+ */
+function absFrom(p, cwd) {
+  return path.isAbsolute(p) ? path.normalize(p) : path.join(cwd, p);
+}
+
+/**
+ * @param {string} p
+ */
+function fileExists(p) {
+  try {
+    fs.accessSync(p, fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/server/db.test.js

@@ -0,0 +1,169 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import {
+  findNearestBeadsDb,
+  findNearestBeadsMetadata,
+  resolveDbPath,
+  resolveWorkspaceDatabase
+} from './db.js';
+
+/** @type {string[]} */
+const tmps = [];
+
+function mkdtemp() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'beads-ui-test-'));
+  tmps.push(dir);
+  return dir;
+}
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+afterEach(() => {
+  for (const d of tmps.splice(0)) {
+    try {
+      fs.rmSync(d, { recursive: true, force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+});
+
+describe('resolveDbPath', () => {
+  test('uses explicit_db when provided', () => {
+    const res = resolveDbPath({ cwd: '/x', explicit_db: './my.db', env: {} });
+    expect(res.path.endsWith('/x/my.db')).toBe(true);
+    expect(res.source).toBe('flag');
+  });
+
+  test('uses BEADS_DB from env when set', () => {
+    const res = resolveDbPath({ cwd: '/x', env: { BEADS_DB: '/abs/env.db' } });
+    expect(res.path).toBe('/abs/env.db');
+    expect(res.source).toBe('env');
+  });
+
+  test('finds nearest .beads/ui.db walking up', () => {
+    const root = mkdtemp();
+    const nested = path.join(root, 'a', 'b', 'c');
+    fs.mkdirSync(nested, { recursive: true });
+    const beads = path.join(root, '.beads');
+    fs.mkdirSync(beads);
+    const ui_db = path.join(beads, 'ui.db');
+    fs.writeFileSync(ui_db, '');
+
+    const found = findNearestBeadsDb(nested);
+    expect(found).toBe(ui_db);
+
+    const res = resolveDbPath({ cwd: nested, env: {} });
+    expect(res.path).toBe(ui_db);
+    expect(res.source).toBe('nearest');
+  });
+
+  test('falls back to ~/.beads/default.db when none found', async () => {
+    // Mock os.homedir to a deterministic location using spy
+    const home = mkdtemp();
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+    const mod = await import('./db.js');
+    const res = mod.resolveDbPath({ cwd: '/no/db/here', env: {} });
+    expect(res.path).toBe(path.join(home, '.beads', 'default.db'));
+    expect(res.source).toBe('home-default');
+  });
+
+  test('treats ~/.beads/default.db as fallback, not nearest workspace db', async () => {
+    const home = mkdtemp();
+    const nested = path.join(home, 'projects', 'repo', 'deep');
+    fs.mkdirSync(nested, { recursive: true });
+    const home_beads = path.join(home, '.beads');
+    fs.mkdirSync(home_beads, { recursive: true });
+    fs.writeFileSync(path.join(home_beads, 'default.db'), '');
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+    const mod = await import('./db.js');
+
+    const res = mod.resolveDbPath({ cwd: nested, env: {} });
+
+    expect(res.path).toBe(path.join(home, '.beads', 'default.db'));
+    expect(res.source).toBe('home-default');
+  });
+});
+
+describe('findNearestBeadsMetadata', () => {
+  test('finds nearest metadata walking up', () => {
+    const root = mkdtemp();
+    const nested = path.join(root, 'a', 'b', 'c');
+    fs.mkdirSync(nested, { recursive: true });
+    const beads_dir = path.join(root, '.beads');
+    fs.mkdirSync(beads_dir, { recursive: true });
+    const metadata = path.join(beads_dir, 'metadata.json');
+    fs.writeFileSync(metadata, '{}');
+
+    const found = findNearestBeadsMetadata(nested);
+
+    expect(found).toBe(metadata);
+  });
+
+  test('returns null when metadata is missing', () => {
+    const root = mkdtemp();
+
+    const found = findNearestBeadsMetadata(root);
+
+    expect(found).toBeNull();
+  });
+});
+
+describe('resolveWorkspaceDatabase', () => {
+  test('uses metadata directory for non-SQLite workspace', () => {
+    const root = mkdtemp();
+    const nested = path.join(root, 'workspace', 'nested');
+    fs.mkdirSync(nested, { recursive: true });
+    const beads_dir = path.join(root, '.beads');
+    fs.mkdirSync(beads_dir, { recursive: true });
+    fs.writeFileSync(path.join(beads_dir, 'metadata.json'), '{}');
+
+    const found = resolveWorkspaceDatabase({ cwd: nested, env: {} });
+
+    expect(found.path).toBe(beads_dir);
+    expect(found.source).toBe('metadata');
+    expect(found.exists).toBe(true);
+  });
+
+  test('prefers metadata workspace when home default db exists', async () => {
+    const home = mkdtemp();
+    const root = path.join(home, 'project');
+    const nested = path.join(root, 'workspace', 'nested');
+    fs.mkdirSync(nested, { recursive: true });
+    const home_beads = path.join(home, '.beads');
+    fs.mkdirSync(home_beads, { recursive: true });
+    fs.writeFileSync(path.join(home_beads, 'default.db'), '');
+    const beads_dir = path.join(root, '.beads');
+    fs.mkdirSync(beads_dir, { recursive: true });
+    fs.writeFileSync(path.join(beads_dir, 'metadata.json'), '{}');
+    vi.spyOn(os, 'homedir').mockReturnValue(home);
+    const mod = await import('./db.js');
+
+    const found = mod.resolveWorkspaceDatabase({ cwd: nested, env: {} });
+
+    expect(found.path).toBe(beads_dir);
+    expect(found.source).toBe('metadata');
+    expect(found.exists).toBe(true);
+  });
+
+  test('prefers nearest sqlite database when present', () => {
+    const root = mkdtemp();
+    const nested = path.join(root, 'workspace', 'nested');
+    fs.mkdirSync(nested, { recursive: true });
+    const beads_dir = path.join(root, '.beads');
+    fs.mkdirSync(beads_dir, { recursive: true });
+    fs.writeFileSync(path.join(beads_dir, 'metadata.json'), '{}');
+    const sqlite_db = path.join(beads_dir, 'workspace.db');
+    fs.writeFileSync(sqlite_db, '');
+
+    const found = resolveWorkspaceDatabase({ cwd: nested, env: {} });
+
+    expect(found.path).toBe(sqlite_db);
+    expect(found.source).toBe('nearest');
+    expect(found.exists).toBe(true);
+  });
+});

package/server/dolt-pool.js

@@ -0,0 +1,257 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import mysql from 'mysql2/promise';
+import { findNearestBeadsMetadata } from './db.js';
+import { debug } from './logging.js';
+
+const log = debug('dolt-pool');
+
+const DOLT_PORT = 3307;
+const DOLT_SOCK = '/tmp/bdui-dolt.sock';
+
+/** @type {import('mysql2/promise').Pool | null} */
+let pool = null;
+
+/** @type {import('node:child_process').ChildProcess | null} */
+let serverProcess = null;
+
+/** @type {string | null} */
+let currentDataDir = null;
+
+/**
+ * Resolve the Dolt data directory from the workspace root.
+ * Walks up from cwd to find .beads/metadata.json, then checks for
+ * embeddeddolt/<database>/ structure.
+ *
+ * @param {string} cwd
+ * @returns {{ dataDir: string, database: string } | null}
+ */
+export function resolveDoltDir(cwd) {
+  const metadataPath = findNearestBeadsMetadata(cwd);
+  if (!metadataPath) return null;
+
+  const beadsDir = path.dirname(metadataPath);
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+  } catch {
+    return null;
+  }
+
+  if (metadata.backend !== 'dolt' && metadata.database !== 'dolt') return null;
+
+  const database = metadata.dolt_database || 'default';
+  const dataDir = path.join(beadsDir, 'embeddeddolt', database);
+
+  try {
+    fs.accessSync(path.join(dataDir, '.dolt'), fs.constants.F_OK);
+  } catch {
+    return null;
+  }
+
+  return { dataDir, database };
+}
+
+/**
+ * Start the Dolt SQL server and create a connection pool.
+ * Idempotent — returns existing pool if already running for the same dataDir.
+ *
+ * @param {string} cwd - Workspace root directory
+ * @returns {Promise<import('mysql2/promise').Pool | null>}
+ */
+export async function startDoltServer(cwd) {
+  const resolved = resolveDoltDir(cwd);
+  if (!resolved) {
+    log('no Dolt database found for %s', cwd);
+    return null;
+  }
+
+  const { dataDir, database } = resolved;
+
+  // Already running for this data dir
+  if (pool && currentDataDir === dataDir && serverProcess && !serverProcess.killed) {
+    return pool;
+  }
+
+  // Clean up any previous server
+  await stopDoltServer();
+
+  log('starting dolt sql-server at %s (database=%s)', dataDir, database);
+
+  // Clean up stale socket
+  try { fs.unlinkSync(DOLT_SOCK); } catch { /* ignore */ }
+
+  currentDataDir = dataDir;
+
+  return new Promise((resolve) => {
+    const child = spawn('dolt', [
+      'sql-server',
+      '-P', String(DOLT_PORT),
+      '--socket', DOLT_SOCK,
+      '-l', 'warning'
+    ], {
+      cwd: dataDir,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: false
+    });
+
+    serverProcess = child;
+
+    let resolved_already = false;
+
+    child.stderr?.setEncoding('utf8');
+    child.stderr?.on('data', (chunk) => {
+      // Log warnings/errors from dolt
+      if (chunk.trim()) log('dolt: %s', chunk.trim());
+    });
+
+    child.on('error', (err) => {
+      log('dolt sql-server spawn error: %o', err);
+      if (!resolved_already) {
+        resolved_already = true;
+        resolve(null);
+      }
+    });
+
+    child.on('exit', (code) => {
+      log('dolt sql-server exited with code %d', code);
+      pool = null;
+      serverProcess = null;
+      currentDataDir = null;
+      if (!resolved_already) {
+        resolved_already = true;
+        resolve(null);
+      }
+    });
+
+    // Poll for connectivity instead of parsing stdout
+    let attempts = 0;
+    const maxAttempts = 50; // 50 * 100ms = 5s max
+    const pollInterval = setInterval(async () => {
+      attempts++;
+      if (resolved_already) {
+        clearInterval(pollInterval);
+        return;
+      }
+      if (attempts > maxAttempts) {
+        clearInterval(pollInterval);
+        if (!resolved_already) {
+          resolved_already = true;
+          log('dolt sql-server start timeout after %d attempts', attempts);
+          resolve(null);
+        }
+        return;
+      }
+      try {
+        const p = await createPool(database);
+        clearInterval(pollInterval);
+        if (!resolved_already) {
+          resolved_already = true;
+          pool = p;
+          log('dolt sql-server ready on port %d (after %d polls)', DOLT_PORT, attempts);
+          ensureIndexes(p).catch((err) => log('ensureIndexes error: %o', err));
+          resolve(pool);
+        } else {
+          // Pool created after we already resolved (race); close it
+          try { await p.end(); } catch { /* ignore */ }
+        }
+      } catch (poolErr) {
+        // Not ready yet, retry. Clean up any partial pool.
+        if (poolErr && typeof /** @type {any} */ (poolErr).pool?.end === 'function') {
+          try { await /** @type {any} */ (poolErr).pool.end(); } catch { /* ignore */ }
+        }
+      }
+    }, 100);
+  });
+}
+
+/**
+ * Create a mysql2 connection pool.
+ *
+ * @param {string} database
+ * @returns {Promise<import('mysql2/promise').Pool>}
+ */
+async function createPool(database) {
+  const p = mysql.createPool({
+    host: '127.0.0.1',
+    port: DOLT_PORT,
+    user: 'root',
+    database,
+    waitForConnections: true,
+    connectionLimit: 10,
+    queueLimit: 50,
+    enableKeepAlive: true,
+    keepAliveInitialDelay: 10000,
+    // Dolt dates come as strings; avoid extra parsing
+    dateStrings: true
+  });
+
+  // Verify connectivity
+  const conn = await p.getConnection();
+  conn.release();
+  return p;
+}
+
+/**
+ * Ensure required indexes exist. Idempotent — skips if already present.
+ *
+ * @param {import('mysql2/promise').Pool} p
+ */
+async function ensureIndexes(p) {
+  const [rows] = await p.query(
+    `SELECT 1 FROM information_schema.statistics
+     WHERE table_schema = DATABASE() AND table_name = 'issues'
+       AND index_name = 'idx_ft_issues_title_desc' LIMIT 1`
+  );
+  if (/** @type {any[]} */ (rows).length > 0) {
+    log('FULLTEXT index already exists');
+    return;
+  }
+  log('creating FULLTEXT index on issues(title, description)');
+  await p.query(`ALTER TABLE issues ADD FULLTEXT idx_ft_issues_title_desc (title, description)`);
+  await p.query(`CALL dolt_commit('-Am', 'add FULLTEXT index on issues(title, description)')`);
+  log('FULLTEXT index created');
+}
+
+/**
+ * Get the current pool, or null if not started.
+ *
+ * @returns {import('mysql2/promise').Pool | null}
+ */
+export function getPool() {
+  return pool;
+}
+
+/**
+ * Stop the Dolt SQL server and close the pool.
+ */
+export async function stopDoltServer() {
+  if (pool) {
+    try { await pool.end(); } catch { /* ignore */ }
+    pool = null;
+  }
+  if (serverProcess && !serverProcess.killed) {
+    serverProcess.kill('SIGTERM');
+    serverProcess = null;
+  }
+  currentDataDir = null;
+}
+
+/**
+ * Rebind to a new workspace directory (e.g., after workspace switch).
+ *
+ * @param {string} cwd
+ * @returns {Promise<import('mysql2/promise').Pool | null>}
+ */
+export async function rebindDoltServer(cwd) {
+  const resolved = resolveDoltDir(cwd);
+  if (!resolved) {
+    await stopDoltServer();
+    return null;
+  }
+  if (resolved.dataDir === currentDataDir && pool && serverProcess && !serverProcess.killed) {
+    return pool;
+  }
+  return startDoltServer(cwd);
+}