@seungyeop-lee/beads-ui 0.13.0

package/server/list-adapters.js

@@ -0,0 +1,365 @@
+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 'board-issues': {
+      // Handled by fetchBoardIssues in fetchListForSubscription
+      return [];
+    }
+    case 'filtered-issues': {
+      const p = spec.params || {};
+      const raw = typeof p.statuses === 'string' ? p.statuses : '';
+      const arr = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      const statuses = arr.length > 0 ? arr : ['open', 'in_progress', 'closed'];
+      return [
+        'list',
+        '--json',
+        '--tree=false',
+        '--status',
+        statuses.join(','),
+        '--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 = {}) {
+  // Board-issues: unified fetch for all board columns in a single subscription
+  if (String(spec.type) === 'board-issues') {
+    return fetchBoardIssues(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;
+}
+
+/**
+ * Fetch all board data (ready, blocked, in_progress, closed) in parallel
+ * and merge into a single list with `_board_column` tags.
+ *
+ * Priority (last write wins): closed < ready < in_progress < blocked.
+ *
+ * @param {{ cwd?: string }} [options]
+ * @returns {Promise<FetchListResultSuccess | FetchListResultFailure>}
+ */
+async function fetchBoardIssues(options = {}) {
+  const cwd = options.cwd;
+  const [readyRes, blockedRes, inProgRes, closedRes] = await Promise.all([
+    runBdJson(['ready', '--limit', '1000', '--json'], { cwd }),
+    runBdJson(['blocked', '--json'], { cwd }),
+    runBdJson(['list', '--json', '--tree=false', '--status', 'in_progress'], {
+      cwd
+    }),
+    runBdJson(
+      [
+        'list',
+        '--json',
+        '--tree=false',
+        '--status',
+        'closed',
+        '--limit',
+        '1000'
+      ],
+      { cwd }
+    )
+  ]);
+  /** @type {Map<string, { id: string, created_at: number, updated_at: number, closed_at: number | null } & Record<string, unknown>>} */
+  const itemsById = new Map();
+
+  // 1. closed (lowest priority)
+  if (closedRes.code === 0 && Array.isArray(closedRes.stdoutJson)) {
+    for (const it of normalizeIssueList(closedRes.stdoutJson)) {
+      itemsById.set(it.id, { ...it, _board_column: 'closed' });
+    }
+  }
+  // 2. ready
+  if (readyRes.code === 0 && Array.isArray(readyRes.stdoutJson)) {
+    for (const it of normalizeIssueList(readyRes.stdoutJson)) {
+      itemsById.set(it.id, { ...it, _board_column: 'ready' });
+    }
+  }
+  // 3. in_progress (overrides ready — matches existing client-side dedup)
+  if (inProgRes.code === 0 && Array.isArray(inProgRes.stdoutJson)) {
+    for (const it of normalizeIssueList(inProgRes.stdoutJson)) {
+      itemsById.set(it.id, { ...it, _board_column: 'in_progress' });
+    }
+  }
+  // 4. blocked (highest priority)
+  if (blockedRes.code === 0 && Array.isArray(blockedRes.stdoutJson)) {
+    for (const it of normalizeIssueList(blockedRes.stdoutJson)) {
+      itemsById.set(it.id, { ...it, _board_column: 'blocked' });
+    }
+  }
+
+  const items = Array.from(itemsById.values());
+  if (
+    items.length === 0 &&
+    readyRes.code !== 0 &&
+    blockedRes.code !== 0 &&
+    inProgRes.code !== 0 &&
+    closedRes.code !== 0
+  ) {
+    return {
+      ok: false,
+      error: { code: 'bd_error', message: 'All board queries failed' }
+    };
+  }
+  return { ok: true, items };
+}

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

package/server/registry-watcher.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { debug } from './logging.js';
+
+const log = debug('registry-watcher');
+
+/**
+ * In-memory registry of workspaces registered dynamically via the API.
+ * These supplement the file-based registry at ~/.beads/registry.json.
+ *
+ * @type {Map<string, { path: string, database: string, pid: number, version: string }>}
+ */
+const inMemoryWorkspaces = new Map();
+
+/**
+ * Register a workspace dynamically (in-memory).
+ * This allows `bdui start` to register workspaces when the server is already running.
+ *
+ * @param {{ path: string, database: string }} workspace
+ */
+export function registerWorkspace(workspace) {
+  const normalized = path.resolve(workspace.path);
+  log('registering workspace: %s (db: %s)', normalized, workspace.database);
+  inMemoryWorkspaces.set(normalized, {
+    path: normalized,
+    database: workspace.database,
+    pid: process.pid,
+    version: 'dynamic'
+  });
+}
+
+/**
+ * Get all dynamically registered workspaces (in-memory only).
+ *
+ * @returns {Array<{ path: string, database: string, pid: number, version: string }>}
+ */
+export function getInMemoryWorkspaces() {
+  return Array.from(inMemoryWorkspaces.values());
+}
+
+/**
+ * @typedef {Object} RegistryEntry
+ * @property {string} workspace_path
+ * @property {string} socket_path
+ * @property {string} database_path
+ * @property {number} pid
+ * @property {string} version
+ * @property {string} started_at
+ */
+
+/**
+ * Get the path to the global beads registry file.
+ *
+ * @returns {string}
+ */
+export function getRegistryPath() {
+  return path.join(os.homedir(), '.beads', 'registry.json');
+}
+
+/**
+ * Read and parse the registry file.
+ *
+ * @returns {RegistryEntry[]}
+ */
+export function readRegistry() {
+  const registry_path = getRegistryPath();
+  try {
+    const content = fs.readFileSync(registry_path, 'utf8');
+    const data = JSON.parse(content);
+    if (Array.isArray(data)) {
+      return data;
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Find the registry entry that matches the given root directory.
+ * Matches if the root_dir is the same as or a subdirectory of the workspace_path.
+ *
+ * @param {string} root_dir
+ * @returns {RegistryEntry | null}
+ */
+export function findWorkspaceEntry(root_dir) {
+  const entries = readRegistry();
+  const normalized = path.resolve(root_dir);
+
+  // First, try exact match
+  for (const entry of entries) {
+    if (path.resolve(entry.workspace_path) === normalized) {
+      return entry;
+    }
+  }
+
+  // Then try to find if root_dir is inside a workspace
+  for (const entry of entries) {
+    const workspace = path.resolve(entry.workspace_path);
+    if (normalized.startsWith(workspace + path.sep)) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all available workspaces from both the file-based registry and
+ * dynamically registered in-memory workspaces.
+ *
+ * @returns {Array<{ path: string, database: string, pid: number, version: string }>}
+ */
+export function getAvailableWorkspaces() {
+  const entries = readRegistry();
+  const fileWorkspaces = entries.map((entry) => ({
+    path: entry.workspace_path,
+    database: entry.database_path,
+    pid: entry.pid,
+    version: entry.version
+  }));
+
+  // Merge in-memory workspaces, avoiding duplicates by path
+  const seen = new Set(fileWorkspaces.map((w) => path.resolve(w.path)));
+  const inMemory = getInMemoryWorkspaces().filter(
+    (w) => !seen.has(path.resolve(w.path))
+  );
+
+  return [...fileWorkspaces, ...inMemory];
+}
+
+/**
+ * Watch the global beads registry file and invoke callback when it changes.
+ *
+ * @param {(entries: RegistryEntry[]) => void} onChange
+ * @param {{ debounce_ms?: number }} [options]
+ * @returns {{ close: () => void }}
+ */
+export function watchRegistry(onChange, options = {}) {
+  const debounce_ms = options.debounce_ms ?? 500;
+  const registry_path = getRegistryPath();
+  const registry_dir = path.dirname(registry_path);
+  const registry_file = path.basename(registry_path);
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  /** @type {fs.FSWatcher | undefined} */
+  let watcher;
+
+  const schedule = () => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      try {
+        const entries = readRegistry();
+        onChange(entries);
+      } catch (err) {
+        log('error reading registry on change: %o', err);
+      }
+    }, debounce_ms);
+    timer.unref?.();
+  };
+
+  try {
+    // Ensure the directory exists before watching
+    if (!fs.existsSync(registry_dir)) {
+      log('registry directory does not exist: %s', registry_dir);
+      return { close: () => {} };
+    }
+
+    watcher = fs.watch(
+      registry_dir,
+      { persistent: true },
+      (event_type, filename) => {
+        if (filename && String(filename) !== registry_file) {
+          return;
+        }
+        if (event_type === 'change' || event_type === 'rename') {
+          log('registry %s %s', event_type, filename || '');
+          schedule();
+        }
+      }
+    );
+  } catch (err) {
+    log('unable to watch registry directory: %o', err);
+    return { close: () => {} };
+  }
+
+  return {
+    close() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      watcher?.close();
+    }
+  };
+}