beads-enhanced-ui 0.1.0

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;
+});

package/server/list-adapters.js

@@ -0,0 +1,264 @@
+import { runBdJson } from './bd.js';
+import { debug } from './logging.js';
+
+const log = debug('list-adapters');
+
+/**
+ * Build concrete `bd` CLI args for a subscription type + params.
+ * Always includes `--json` for parseable output.
+ *
+ * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
+ * @returns {string[]}
+ */
+export function mapSubscriptionToBdArgs(spec) {
+  const t = String(spec.type);
+  switch (t) {
+    case 'all-issues': {
+      return ['list', '--json', '--tree=false'];
+    }
+    case 'epics': {
+      return ['epic', 'status', '--json'];
+    }
+    case 'blocked-issues': {
+      return ['blocked', '--json'];
+    }
+    case 'ready-issues': {
+      return ['ready', '--limit', '1000', '--json'];
+    }
+    case 'in-progress-issues': {
+      return ['list', '--json', '--tree=false', '--status', 'in_progress'];
+    }
+    case 'closed-issues': {
+      return [
+        'list',
+        '--json',
+        '--tree=false',
+        '--status',
+        'closed',
+        '--limit',
+        '1000'
+      ];
+    }
+    case 'issue-detail': {
+      const p = spec.params || {};
+      const id = String(p.id || '').trim();
+      if (id.length === 0) {
+        throw badRequest('Missing param: params.id');
+      }
+      return ['show', id, '--json'];
+    }
+    default: {
+      throw badRequest(`Unknown subscription type: ${t}`);
+    }
+  }
+}
+
+/**
+ * Normalize bd list output to minimal Issue shape used by the registry.
+ * - Ensures `id` is a string.
+ * - Coerces timestamps to numbers.
+ * - `closed_at` defaults to null when missing or invalid.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>}
+ */
+export function normalizeIssueList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  /** @type {Array<{ id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>} */
+  const out = [];
+  for (const it of value) {
+    const id = String(it.id ?? '');
+    if (id.length === 0) {
+      continue;
+    }
+    const created_at = parseTimestamp(/** @type {any} */ (it).created_at);
+    const updated_at = parseTimestamp(it.updated_at);
+    const closed_raw = it.closed_at;
+    /** @type {number | null} */
+    let closed_at = null;
+    if (closed_raw !== undefined && closed_raw !== null) {
+      const n = parseTimestamp(closed_raw);
+      closed_at = Number.isFinite(n) ? n : null;
+    }
+    out.push({
+      ...it,
+      id,
+      created_at: Number.isFinite(created_at) ? created_at : 0,
+      updated_at: Number.isFinite(updated_at) ? updated_at : 0,
+      closed_at
+    });
+  }
+  return out;
+}
+
+/**
+ * @typedef {Object} FetchListResultSuccess
+ * @property {true} ok
+ * @property {Array<{ id: string, updated_at: number, closed_at: number | null } & Record<string, unknown>>} items
+ */
+
+/**
+ * @typedef {Object} FetchListResultFailure
+ * @property {false} ok
+ * @property {{ code: string, message: string, details?: Record<string, unknown> }} error
+ */
+
+/**
+ * Execute the mapped `bd` command for a subscription spec and return normalized items.
+ * Errors do not throw; they are surfaced as a structured object.
+ *
+ * @param {{ type: string, params?: Record<string, string | number | boolean> }} spec
+ * @param {{ cwd?: string }} [options] - Optional working directory for bd command
+ * @returns {Promise<FetchListResultSuccess | FetchListResultFailure>}
+ */
+export async function fetchListForSubscription(spec, options = {}) {
+  /** @type {string[]} */
+  let args;
+  try {
+    args = mapSubscriptionToBdArgs(spec);
+  } catch (err) {
+    // Surface bad requests (e.g., missing params)
+    log('mapSubscriptionToBdArgs failed for %o: %o', spec, err);
+    const e = toErrorObject(err);
+    return { ok: false, error: e };
+  }
+
+  try {
+    const res = await runBdJson(args, { cwd: options.cwd });
+    if (!res || res.code !== 0 || !('stdoutJson' in res)) {
+      log(
+        'bd failed for %o (args=%o) code=%s stderr=%s',
+        spec,
+        args,
+        res?.code,
+        res?.stderr || ''
+      );
+      return {
+        ok: false,
+        error: {
+          code: 'bd_error',
+          message: String(res?.stderr || 'bd failed'),
+          details: { exit_code: res?.code ?? -1 }
+        }
+      };
+    }
+    // bd show may return a single object; normalize to an array first
+    let raw = Array.isArray(res.stdoutJson)
+      ? res.stdoutJson
+      : res.stdoutJson && typeof res.stdoutJson === 'object'
+        ? [res.stdoutJson]
+        : [];
+
+    // Special-case mapping for `epics`: current bd output nests the epic under
+    // an `epic` key and exposes counters at the top level. Flatten so that
+    // each entry has a top-level `id` and core fields expected by the registry.
+    if (String(spec.type) === 'epics') {
+      raw = raw.map((it) => {
+        if (it && typeof it === 'object' && 'epic' in it) {
+          const e = /** @type {any} */ (it).epic || {};
+          /** @type {Record<string, unknown>} */
+          const flat = {
+            // Required minimal fields for registry + client rendering
+            id: String(e.id ?? ''),
+            title: e.title,
+            status: e.status,
+            issue_type: e.issue_type || 'epic',
+            created_at: e.created_at,
+            updated_at: e.updated_at,
+            closed_at: e.closed_at ?? null,
+            deleted_at: e.deleted_at ?? null,
+            // Preserve useful counters from bd output
+            total_children: /** @type {any} */ (it).total_children,
+            closed_children: /** @type {any} */ (it).closed_children,
+            eligible_for_close: /** @type {any} */ (it).eligible_for_close
+          };
+          return flat;
+        }
+        return it;
+      });
+      raw = raw.filter((it) => {
+        if (!it || typeof it !== 'object') {
+          return false;
+        }
+        const status =
+          typeof (/** @type {any} */ (it).status) === 'string'
+            ? /** @type {any} */ (it).status
+            : '';
+        if (status === 'tombstone') {
+          return false;
+        }
+        const deleted_at = /** @type {any} */ (it).deleted_at;
+        if (deleted_at !== undefined && deleted_at !== null) {
+          return false;
+        }
+        return true;
+      });
+    }
+
+    const items = normalizeIssueList(raw);
+    return { ok: true, items };
+  } catch (err) {
+    log('bd invocation failed for %o (args=%o): %o', spec, args, err);
+    return {
+      ok: false,
+      error: {
+        code: 'bd_error',
+        message:
+          (err && /** @type {any} */ (err).message) || 'bd invocation failed'
+      }
+    };
+  }
+}
+
+/**
+ * Create a `bad_request` error object.
+ *
+ * @param {string} message
+ */
+function badRequest(message) {
+  const e = new Error(message);
+  // @ts-expect-error add code
+  e.code = 'bad_request';
+  return e;
+}
+
+/**
+ * Normalize arbitrary thrown values to a structured error object.
+ *
+ * @param {unknown} err
+ * @returns {FetchListResultFailure['error']}
+ */
+function toErrorObject(err) {
+  if (err && typeof err === 'object') {
+    const any = /** @type {{ code?: unknown, message?: unknown }} */ (err);
+    const code = typeof any.code === 'string' ? any.code : 'bad_request';
+    const message =
+      typeof any.message === 'string' ? any.message : 'Request error';
+    return { code, message };
+  }
+  return { code: 'bad_request', message: 'Request error' };
+}
+
+/**
+ * Parse a bd timestamp string to epoch ms using Date.parse.
+ * Falls back to numeric coercion when parsing fails.
+ *
+ * @param {unknown} v
+ * @returns {number}
+ */
+function parseTimestamp(v) {
+  if (typeof v === 'string') {
+    const ms = Date.parse(v);
+    if (Number.isFinite(ms)) {
+      return ms;
+    }
+    const n = Number(v);
+    return Number.isFinite(n) ? n : 0;
+  }
+  if (typeof v === 'number') {
+    return Number.isFinite(v) ? v : 0;
+  }
+  return 0;
+}

package/server/logging.js

@@ -0,0 +1,23 @@
+/**
+ * Debug logger helper for Node server/CLI.
+ */
+import createDebug from 'debug';
+
+/**
+ * Create a namespaced logger for Node runtime.
+ *
+ * @param {string} ns - Module namespace suffix (e.g., 'ws', 'watcher').
+ */
+export function debug(ns) {
+  return createDebug(`beads-ui:${ns}`);
+}
+
+/**
+ * Enable all `beads-ui:*` debug logs at runtime for Node/CLI.
+ * Safe to call multiple times.
+ */
+export function enableAllDebug() {
+  // `debug` exposes a global enable/disable API.
+  // Enabling after loggers are created updates their `.enabled` state.
+  createDebug.enable(process.env.DEBUG || 'beads-ui:*');
+}