@seungyeop-lee/beads-ui 0.13.0

package/server/cli/index.js

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises';
+import { enableAllDebug } from '../logging.js';
+import { handleRestart, handleStart, handleStop } from './commands.js';
+import { printUsage } from './usage.js';
+
+/**
+ * Parse argv into a command token, flags, and options.
+ *
+ * @param {string[]} args
+ * @returns {{ command: string | null, flags: string[], options: { host?: string, port?: number } }}
+ */
+export function parseArgs(args) {
+  /** @type {string[]} */
+  const flags = [];
+  /** @type {string | null} */
+  let command = null;
+  /** @type {{ host?: string, port?: number }} */
+  const options = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (token === '--help' || token === '-h') {
+      flags.push('help');
+      continue;
+    }
+    if (token === '--debug' || token === '-d') {
+      flags.push('debug');
+      continue;
+    }
+    if (token === '--open') {
+      flags.push('open');
+      continue;
+    }
+    if (token === '--version' || token === '-v') {
+      flags.push('version');
+      continue;
+    }
+    if (token === '--host' && i + 1 < args.length) {
+      options.host = args[++i];
+      continue;
+    }
+    if (token === '--port' && i + 1 < args.length) {
+      const port_value = Number.parseInt(args[++i], 10);
+      if (Number.isFinite(port_value) && port_value > 0) {
+        options.port = port_value;
+      }
+      continue;
+    }
+    if (
+      !command &&
+      (token === 'start' || token === 'stop' || token === 'restart')
+    ) {
+      command = token;
+      continue;
+    }
+    // Ignore unrecognized tokens for now; future flags may be parsed here.
+  }
+
+  return { command, flags, options };
+}
+
+/**
+ * Load the package.json version string.
+ *
+ * @returns {Promise<string>}
+ */
+async function loadVersion() {
+  const package_url = new URL('../../package.json', import.meta.url);
+  const package_text = await readFile(package_url, 'utf8');
+  const package_data = JSON.parse(package_text);
+  const version = package_data.version;
+  if (typeof version !== 'string') {
+    throw new Error('Invalid package.json version');
+  }
+  return version;
+}
+
+/**
+ * CLI main entry. Returns an exit code and prints usage on `--help` or errors.
+ * No side effects beyond invoking stub handlers.
+ *
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+export async function main(args) {
+  const { command, flags, options } = parseArgs(args);
+
+  const is_debug = flags.includes('debug');
+  if (is_debug) {
+    enableAllDebug();
+  }
+
+  if (flags.includes('version')) {
+    const version = await loadVersion();
+    process.stdout.write(`${version}\n`);
+    return 0;
+  }
+  if (flags.includes('help')) {
+    printUsage(process.stdout);
+    return 0;
+  }
+  if (!command) {
+    printUsage(process.stdout);
+    return 1;
+  }
+
+  if (command === 'start') {
+    /**
+     * Default behavior: do NOT open a browser. `--open` explicitly opens.
+     */
+    const start_options = {
+      open: flags.includes('open'),
+      is_debug: is_debug || Boolean(process.env.DEBUG),
+      host: options.host,
+      port: options.port
+    };
+    return await handleStart(start_options);
+  }
+  if (command === 'stop') {
+    return await handleStop();
+  }
+  if (command === 'restart') {
+    const restart_options = {
+      open: flags.includes('open'),
+      is_debug: is_debug || Boolean(process.env.DEBUG),
+      host: options.host,
+      port: options.port
+    };
+    return await handleRestart(restart_options);
+  }
+
+  // Unknown command path (should not happen due to parseArgs guard)
+  printUsage(process.stdout);
+  return 1;
+}

package/server/cli/open.js

@@ -0,0 +1,178 @@
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+
+/**
+ * Compute a platform-specific command to open a URL in the default browser.
+ *
+ * @param {string} url
+ * @param {string} platform
+ * @returns {{ cmd: string, args: string[] }}
+ */
+export function computeOpenCommand(url, platform) {
+  if (platform === 'darwin') {
+    return { cmd: 'open', args: [url] };
+  }
+  if (platform === 'win32') {
+    // Use `start` via cmd.exe to open URLs
+    return { cmd: 'cmd', args: ['/c', 'start', '', url] };
+  }
+  // Assume Linux/other Unix with xdg-open
+  return { cmd: 'xdg-open', args: [url] };
+}
+
+/**
+ * Open the given URL in the default browser. Best-effort; resolves true on spawn success.
+ *
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+export async function openUrl(url) {
+  const { cmd, args } = computeOpenCommand(url, process.platform);
+  try {
+    const child = spawn(cmd, args, {
+      stdio: 'ignore',
+      detached: false
+    });
+    // If spawn succeeded and pid is present, consider it a success
+    return typeof child.pid === 'number' && child.pid > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Wait until the server at the URL accepts a connection, with a brief retry.
+ * Does not throw; returns when either a connection was accepted or timeout elapsed.
+ *
+ * @param {string} url
+ * @param {number} total_timeout_ms
+ * @returns {Promise<void>}
+ */
+export async function waitForServer(url, total_timeout_ms = 600) {
+  const deadline = Date.now() + total_timeout_ms;
+
+  // Attempt one GET; if it fails, wait and try once more within the deadline
+  const tryOnce = () =>
+    new Promise((resolve) => {
+      let done = false;
+      const req = http.get(url, (res) => {
+        // Any response implies the server is accepting connections
+        if (!done) {
+          done = true;
+          res.resume();
+          resolve(undefined);
+        }
+      });
+      req.on('error', () => {
+        if (!done) {
+          done = true;
+          resolve(undefined);
+        }
+      });
+      req.setTimeout(200, () => {
+        try {
+          req.destroy();
+        } catch {
+          void 0;
+        }
+        if (!done) {
+          done = true;
+          resolve(undefined);
+        }
+      });
+    });
+
+  await tryOnce();
+
+  if (Date.now() < deadline) {
+    const remaining = Math.max(0, deadline - Date.now());
+    await sleep(remaining);
+  }
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Fetch the list of workspaces from the running server.
+ *
+ * @param {string} base_url - Server base URL (e.g., "http://127.0.0.1:3000")
+ * @returns {Promise<Array<{ path: string, database: string }>>}
+ */
+export async function fetchWorkspacesFromServer(base_url) {
+  return new Promise((resolve) => {
+    const url = new URL('/api/workspaces', base_url);
+    const req = http.get(url, (res) => {
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.ok && Array.isArray(parsed.workspaces)) {
+            resolve(parsed.workspaces);
+          } else {
+            resolve([]);
+          }
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+    req.on('error', () => resolve([]));
+    req.setTimeout(2000, () => {
+      try {
+        req.destroy();
+      } catch {
+        void 0;
+      }
+      resolve([]);
+    });
+  });
+}
+
+/**
+ * Register a workspace with the running server.
+ * Makes a POST request to /api/register-workspace.
+ *
+ * @param {string} base_url - Server base URL (e.g., "http://127.0.0.1:3000")
+ * @param {{ path: string, database: string }} workspace
+ * @returns {Promise<boolean>} True if registration succeeded
+ */
+export async function registerWorkspaceWithServer(base_url, workspace) {
+  return new Promise((resolve) => {
+    const url = new URL('/api/register-workspace', base_url);
+    const body = JSON.stringify(workspace);
+    const req = http.request(
+      url,
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body)
+        }
+      },
+      (res) => {
+        res.resume();
+        resolve(res.statusCode === 200);
+      }
+    );
+    req.on('error', () => resolve(false));
+    req.setTimeout(2000, () => {
+      try {
+        req.destroy();
+      } catch {
+        void 0;
+      }
+      resolve(false);
+    });
+    req.write(body);
+    req.end();
+  });
+}

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 = 3000;
+  }
+
+  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/index.js

@@ -0,0 +1,76 @@
+import { createServer } from 'node:http';
+import { createApp } from './app.js';
+import { printServerUrl } from './cli/daemon.js';
+import { getConfig } from './config.js';
+import { resolveWorkspaceDatabase } from './db.js';
+import { debug, enableAllDebug } from './logging.js';
+import { registerWorkspace, watchRegistry } from './registry-watcher.js';
+import { watchDb } from './watcher.js';
+import { attachWsServer } from './ws.js';
+
+if (process.argv.includes('--debug') || process.argv.includes('-d')) {
+  enableAllDebug();
+}
+
+// Parse --host and --port from argv and set env vars before getConfig()
+for (let i = 0; i < process.argv.length; i++) {
+  if (process.argv[i] === '--host' && process.argv[i + 1]) {
+    process.env.HOST = process.argv[++i];
+  }
+  if (process.argv[i] === '--port' && process.argv[i + 1]) {
+    process.env.PORT = process.argv[++i];
+  }
+}
+
+const config = getConfig();
+const app = createApp(config);
+const server = createServer(app);
+const log = debug('server');
+
+// Register the initial workspace (from cwd) so it appears in the workspace picker
+// even without the beads daemon running
+const workspace_database = resolveWorkspaceDatabase({ cwd: config.root_dir });
+if (workspace_database.source !== 'home-default' && workspace_database.exists) {
+  registerWorkspace({
+    path: config.root_dir,
+    database: workspace_database.path
+  });
+}
+
+// Watch the active beads DB and schedule subscription refresh for active lists
+const db_watcher = watchDb(config.root_dir, () => {
+  // Schedule subscription list refresh run for active subscriptions
+  log('db change detected → schedule refresh');
+  scheduleListRefresh();
+  // v2: all updates flow via subscription push envelopes only
+});
+
+const { scheduleListRefresh } = attachWsServer(server, {
+  path: '/ws',
+  heartbeat_ms: 30000,
+  // Coalesce DB change bursts into one refresh run
+  refresh_debounce_ms: 75,
+  root_dir: config.root_dir,
+  watcher: db_watcher
+});
+
+// Watch the global registry for workspace changes (e.g., when user starts
+// bd daemon in a different project). This enables automatic workspace switching.
+watchRegistry(
+  (entries) => {
+    log('registry changed: %d entries', entries.length);
+    // Find if there's a newer workspace that matches our initial root
+    // For now, we just log the change - users can switch via set-workspace
+    // Future: could auto-switch if a workspace was started in a parent/child dir
+  },
+  { debounce_ms: 500 }
+);
+
+server.listen(config.port, config.host, () => {
+  printServerUrl();
+});
+
+server.on('error', (err) => {
+  log('server error %o', err);
+  process.exitCode = 1;
+});