beads-ui 0.1.0

package/server/cli/index.js

@@ -0,0 +1,74 @@
+import { handleRestart, handleStart, handleStop } from './commands.js';
+import { printUsage } from './usage.js';
+
+/**
+ * Parse argv into a command token and flags.
+ * @param {string[]} args
+ * @returns {{ command: string | null, flags: string[] }}
+ */
+export function parseArgs(args) {
+  /** @type {string[]} */
+  const flags = [];
+  /** @type {string | null} */
+  let command = null;
+
+  for (const token of args) {
+    if (token === '--help' || token === '-h') {
+      flags.push('help');
+      continue;
+    }
+    if (token === '--no-open') {
+      flags.push('no-open');
+      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 };
+}
+
+/**
+ * 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 } = parseArgs(args);
+
+  if (flags.includes('help')) {
+    printUsage(process.stdout);
+    return 0;
+  }
+  if (!command) {
+    printUsage(process.stdout);
+    return 1;
+  }
+
+  if (command === 'start') {
+    /** @type {{ no_open: boolean }} */
+    const options = {
+      no_open:
+        flags.includes('no-open') ||
+        String(process.env.BDUI_NO_OPEN || '') === '1'
+    };
+    return await handleStart(options);
+  }
+  if (command === 'stop') {
+    return await handleStop();
+  }
+  if (command === 'restart') {
+    return await handleRestart();
+  }
+
+  // Unknown command path (should not happen due to parseArgs guard)
+  printUsage(process.stdout);
+  return 1;
+}

package/server/cli/open.js

@@ -0,0 +1,96 @@
+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));
+}

package/server/cli/open.test.js

@@ -0,0 +1,26 @@
+import { describe, expect, test } from 'vitest';
+import { computeOpenCommand } from './open.js';
+
+describe('computeOpenCommand', () => {
+  test('returns macOS open command', () => {
+    const r = computeOpenCommand('http://127.0.0.1:3000', 'darwin');
+
+    expect(r.cmd).toBe('open');
+    expect(r.args).toEqual(['http://127.0.0.1:3000']);
+  });
+
+  test('returns Linux xdg-open command', () => {
+    const r = computeOpenCommand('http://127.0.0.1:3000', 'linux');
+
+    expect(r.cmd).toBe('xdg-open');
+    expect(r.args).toEqual(['http://127.0.0.1:3000']);
+  });
+
+  test('returns Windows start command via cmd', () => {
+    const r = computeOpenCommand('http://127.0.0.1:3000', 'win32');
+
+    expect(r.cmd).toBe('cmd');
+    expect(r.args.slice(0, 3)).toEqual(['/c', 'start', '']);
+    expect(r.args[r.args.length - 1]).toBe('http://127.0.0.1:3000');
+  });
+});

package/server/cli/usage.js

@@ -0,0 +1,22 @@
+/**
+ * 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 (daemonized in later steps)',
+    '  stop        Stop the UI server',
+    '  restart     Restart the UI server',
+    '',
+    'Options:',
+    '  -h, --help   Show this help message',
+    '      --no-open  Do not open the browser on start',
+    ''
+  ];
+  for (const line of lines) {
+    out_stream.write(line + '\n');
+  }
+}

package/server/config.js

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Resolve runtime configuration for the server.
+ * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string }}
+ */
+export function getConfig() {
+  const this_file = fileURLToPath(new URL(import.meta.url));
+  const server_dir = path.dirname(this_file);
+  const root_dir = path.resolve(server_dir, '..');
+
+  /** @type {number} */
+  let port_value = Number.parseInt(process.env.PORT || '', 10);
+  if (!Number.isFinite(port_value)) {
+    port_value = 3000;
+  }
+
+  /** @type {string} */
+  const host_value = '127.0.0.1';
+
+  return {
+    host: host_value,
+    port: port_value,
+    env: process.env.NODE_ENV ? String(process.env.NODE_ENV) : 'development',
+    app_dir: path.resolve(root_dir, 'app'),
+    root_dir
+  };
+}

package/server/db.js

@@ -0,0 +1,100 @@
+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
+ * 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;
+
+  // 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) {
+    return { path: nearest, source: 'nearest', exists: fileExists(nearest) };
+  }
+
+  // 4) ~/.beads/default.db
+  const homeDefault = path.join(os.homedir(), '.beads', 'default.db');
+  return {
+    path: homeDefault,
+    source: 'home-default',
+    exists: fileExists(homeDefault)
+  };
+}
+
+/**
+ * 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 beadsDir = path.join(dir, '.beads');
+    try {
+      const entries = fs.readdirSync(beadsDir, { withFileTypes: true });
+      /** @type {string[]} */
+      const dbs = entries
+        .filter((e) => e.isFile() && e.name.endsWith('.db'))
+        .map((e) => e.name)
+        .sort();
+      if (dbs.length > 0) {
+        return path.join(beadsDir, 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,70 @@
+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, resolveDbPath } 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 uiDb = path.join(beads, 'ui.db');
+    fs.writeFileSync(uiDb, '');
+
+    const found = findNearestBeadsDb(nested);
+    expect(found).toBe(uiDb);
+
+    const res = resolveDbPath({ cwd: nested, env: {} });
+    expect(res.path).toBe(uiDb);
+    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();
+    const spy = 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');
+    spy.mockRestore();
+  });
+});

package/server/index.js

@@ -0,0 +1,29 @@
+import { createServer } from 'node:http';
+import { createApp } from './app.js';
+import { getConfig } from './config.js';
+import { watchDb } from './watcher.js';
+import { attachWsServer } from './ws.js';
+
+const config = getConfig();
+const app = createApp(config);
+const server = createServer(app);
+const { notifyIssuesChanged } = attachWsServer(server, {
+  path: '/ws',
+  heartbeat_ms: 30000
+});
+
+// Watch the active beads DB and push invalidation (targeted when possible)
+watchDb(config.root_dir, (payload) => {
+  notifyIssuesChanged(payload);
+});
+
+server.listen(config.port, config.host, () => {
+  console.log(
+    `beads-ui server listening on http://${config.host}:${config.port} (${config.env})`
+  );
+});
+
+server.on('error', (err) => {
+  console.error('Server error:', err);
+  process.exitCode = 1;
+});

package/server/protocol.js

@@ -0,0 +1,3 @@
+// Server-side access to protocol utilities and constants.
+// Import from the shared client definition to ensure a single source of truth.
+export * from '../app/protocol.js';

package/server/protocol.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, test } from 'vitest';
+import {
+  MESSAGE_TYPES,
+  PROTOCOL_VERSION,
+  decodeReply,
+  decodeRequest,
+  isMessageType,
+  isReply,
+  isRequest,
+  makeError,
+  makeOk,
+  makeRequest
+} from './protocol.js';
+
+describe('server/protocol', () => {
+  test('isMessageType returns true for known type', () => {
+    // execution
+    const res = isMessageType('list-issues');
+
+    // assertion
+    expect(res).toBe(true);
+  });
+
+  test('isMessageType returns false for unknown type', () => {
+    // execution
+    const res = isMessageType('not-a-type');
+
+    // assertion
+    expect(res).toBe(false);
+  });
+
+  test('makeRequest and decodeRequest round-trip', () => {
+    // setup
+    const req = makeRequest('show-issue', { id: 'UI-9' }, 'r-9');
+
+    // execution
+    const decoded = decodeRequest(JSON.parse(JSON.stringify(req)));
+
+    // assertion
+    expect(isRequest(req)).toBe(true);
+    expect(decoded.id).toBe('r-9');
+    expect(decoded.type).toBe('show-issue');
+  });
+
+  test('makeOk and makeError create valid replies', () => {
+    // setup
+    const req = makeRequest('list-issues', undefined, 'r-10');
+
+    // execution
+    const ok = makeOk(req, [{ id: 'UI-1' }]);
+    const err = makeError(req, 'boom', 'Something went wrong');
+
+    // assertion
+    expect(isReply(ok)).toBe(true);
+    expect(isReply(err)).toBe(true);
+    expect(ok.ok).toBe(true);
+    expect(err.ok).toBe(false);
+  });
+
+  test('decodeReply accepts ok and error envelopes', () => {
+    // setup
+    const req = makeRequest('edit-text', { id: 'UI-1', text: 'x' }, 'r-11');
+    const ok = makeOk(req, { id: 'UI-1' });
+    const err = makeError(req, 'validation', 'Invalid');
+
+    // execution
+    const ok2 = decodeReply(JSON.parse(JSON.stringify(ok)));
+    const err2 = decodeReply(JSON.parse(JSON.stringify(err)));
+
+    // assertion
+    expect(ok2.ok).toBe(true);
+    expect(err2.ok).toBe(false);
+  });
+
+  test('invalid envelopes throw on decode', () => {
+    // execution + assertion
+    expect(() => decodeRequest({})).toThrow();
+    expect(() => decodeReply({ ok: true })).toThrow();
+  });
+
+  test('exports protocol constants', () => {
+    // assertion
+    expect(typeof PROTOCOL_VERSION).toBe('string');
+    expect(Array.isArray(MESSAGE_TYPES)).toBe(true);
+    expect(MESSAGE_TYPES.length).toBeGreaterThan(0);
+  });
+});

package/server/watcher.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveDbPath } from './db.js';
+
+/**
+ * Watch the resolved beads SQLite DB file and invoke a callback after a debounce window.
+ * The DB path is resolved following beads precedence and can be overridden via options.
+ * @param {string} root_dir - Project root directory (starting point for resolution).
+ * @param {(payload: { ts: number }) => void} on_change - Called when changes are detected.
+ * @param {{ debounce_ms?: number, explicit_db?: string }} [options]
+ * @returns {{ close: () => void, rebind: (opts?: { root_dir?: string, explicit_db?: string }) => void, path: string }}
+ */
+export function watchDb(root_dir, on_change, options = {}) {
+  const debounce_ms = options.debounce_ms ?? 250;
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {fs.FSWatcher | undefined} */
+  let watcher;
+  /** @type {string} */
+  let current_path = '';
+  /** @type {string} */
+  let current_dir = '';
+  /** @type {string} */
+  let current_file = '';
+
+  const schedule = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      on_change({ ts: Date.now() });
+    }, debounce_ms);
+    timer.unref?.();
+  };
+
+  /**
+   * Attach a watcher to the directory containing the resolved DB path.
+   * @param {string} base_dir
+   * @param {string | undefined} explicit_db
+   */
+  const bind = (base_dir, explicit_db) => {
+    const resolved = resolveDbPath({ cwd: base_dir, explicit_db });
+    current_path = resolved.path;
+    current_dir = path.dirname(current_path);
+    current_file = path.basename(current_path);
+    if (!resolved.exists) {
+      console.warn(
+        'watchDb: resolved DB does not exist yet:',
+        current_path,
+        '\nHint: set --db, export BEADS_DB, or run `bd init` in your workspace.'
+      );
+    }
+
+    // (Re)create watcher
+    try {
+      watcher = fs.watch(
+        current_dir,
+        { persistent: true },
+        (event_type, filename) => {
+          if (filename && String(filename) !== current_file) {
+            return;
+          }
+          if (event_type === 'change' || event_type === 'rename') {
+            schedule();
+          }
+        }
+      );
+    } catch (err) {
+      console.warn('watchDb: unable to watch directory', current_dir, err);
+    }
+  };
+
+  // initial bind
+  bind(root_dir, options.explicit_db);
+
+  return {
+    get path() {
+      return current_path;
+    },
+    close() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+    },
+    /**
+     * Re-resolve and reattach watcher when root_dir or explicit_db changes.
+     * @param {{ root_dir?: string, explicit_db?: string }} [opts]
+     */
+    rebind(opts = {}) {
+      const next_root = opts.root_dir ? String(opts.root_dir) : root_dir;
+      const next_explicit = opts.explicit_db ?? options.explicit_db;
+      const nextResolved = resolveDbPath({
+        cwd: next_root,
+        explicit_db: next_explicit
+      });
+      const next_path = nextResolved.path;
+      if (next_path !== current_path) {
+        // swap watcher
+        watcher?.close();
+        bind(next_root, next_explicit);
+      }
+    }
+  };
+}