beads-ui 0.2.0 → 0.3.1

package/server/cli/daemon.js

@@ -1,24 +1,27 @@
+/**
+ * @import { SpawnOptions } from 'node:child_process'
+ */
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getConfig } from '../config.js';
+import { resolveDbPath } from '../db.js';
 
 /**
  * Resolve the runtime directory used for PID and log files.
  * Prefers `BDUI_RUNTIME_DIR`, then `$XDG_RUNTIME_DIR/beads-ui`,
  * and finally `os.tmpdir()/beads-ui`.
+ *
  * @returns {string}
  */
 export function getRuntimeDir() {
-  /** @type {string | undefined} */
   const override_dir = process.env.BDUI_RUNTIME_DIR;
   if (override_dir && override_dir.length > 0) {
     return ensureDir(override_dir);
   }
 
-  /** @type {string | undefined} */
   const xdg_dir = process.env.XDG_RUNTIME_DIR;
   if (xdg_dir && xdg_dir.length > 0) {
     return ensureDir(path.join(xdg_dir, 'beads-ui'));
@@ -29,6 +32,7 @@ export function getRuntimeDir() {
 
 /**
  * Ensure a directory exists with safe permissions and return its path.
+ *
  * @param {string} dir_path
  * @returns {string}
  */
@@ -59,6 +63,7 @@ export function getLogFilePath() {
 
 /**
  * Read PID from the PID file if present.
+ *
  * @returns {number | null}
  */
 export function readPidFile() {
@@ -98,6 +103,7 @@ export function removePidFile() {
 
 /**
  * Check whether a process is running.
+ *
  * @param {number} pid
  * @returns {boolean}
  */
@@ -120,6 +126,7 @@ export function isProcessRunning(pid) {
 
 /**
  * Compute the absolute path to the server entry file.
+ *
  * @returns {string}
  */
 export function getServerEntryPath() {
@@ -132,6 +139,7 @@ export function getServerEntryPath() {
 /**
  * Spawn the server as a detached daemon, redirecting stdio to the log file.
  * Writes the PID file upon success.
+ *
  * @returns {{ pid: number } | null} Returns child PID on success; null on failure.
  */
 export function startDaemon() {
@@ -148,7 +156,7 @@ export function startDaemon() {
     log_fd = -1;
   }
 
-  /** @type {import('node:child_process').SpawnOptions} */
+  /** @type {SpawnOptions} */
   const opts = {
     detached: true,
     env: { ...process.env },
@@ -181,6 +189,7 @@ export function startDaemon() {
 
 /**
  * Send SIGTERM then (optionally) SIGKILL to stop a process and wait for exit.
+ *
  * @param {number} pid
  * @param {number} timeout_ms
  * @returns {Promise<boolean>} Resolves true if the process is gone.
@@ -233,7 +242,12 @@ function sleep(ms) {
  * Print the server URL derived from current config.
  */
 export function printServerUrl() {
-  const cfg = getConfig();
-  const url = 'http://' + cfg.host + ':' + String(cfg.port);
+  const { url } = getConfig();
   console.log(url);
+
+  // Resolve from the caller's working directory by default
+  const resolved_db = resolveDbPath();
+  console.log(
+    `db: ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
+  );
 }

package/server/cli/index.js

@@ -3,6 +3,7 @@ import { printUsage } from './usage.js';
 
 /**
  * Parse argv into a command token and flags.
+ *
  * @param {string[]} args
  * @returns {{ command: string | null, flags: string[] }}
  */
@@ -41,6 +42,7 @@ export function parseArgs(args) {
 /**
  * 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>}
  */
@@ -61,7 +63,6 @@ export async function main(args) {
      * Default behavior: do NOT open a browser.
      * `--open` explicitly opens, overriding env/config; `--no-open` forces closed.
      */
-    /** @type {{ no_open: boolean }} */
     const options = {
       no_open: true
     };
@@ -83,7 +84,6 @@ export async function main(args) {
     return await handleStop();
   }
   if (command === 'restart') {
-    /** @type {{ no_open: boolean }} */
     const options = { no_open: true };
     const has_open = flags.includes('open');
     const has_no_open = flags.includes('no-open');

package/server/cli/open.js

@@ -3,6 +3,7 @@ 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[] }}
@@ -21,6 +22,7 @@ export function computeOpenCommand(url, platform) {
 
 /**
  * Open the given URL in the default browser. Best-effort; resolves true on spawn success.
+ *
  * @param {string} url
  * @returns {Promise<boolean>}
  */
@@ -41,6 +43,7 @@ export async function openUrl(url) {
 /**
  * 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>}

package/server/cli/usage.js

@@ -1,5 +1,6 @@
 /**
  * Print CLI usage to a stream-like target.
+ *
  * @param {{ write: (chunk: string) => any }} out_stream
  */
 export function printUsage(out_stream) {
@@ -7,7 +8,7 @@ export function printUsage(out_stream) {
     'Usage: bdui <command> [options]',
     '',
     'Commands:',
-    '  start       Start the UI server (daemonized in later steps)',
+    '  start       Start the UI server',
     '  stop        Stop the UI server',
     '  restart     Restart the UI server',
     '',

package/server/config.js

@@ -3,27 +3,34 @@ import { fileURLToPath } from 'node:url';
 
 /**
  * Resolve runtime configuration for the server.
- * @returns {{ host: string, port: number, env: string, app_dir: string, root_dir: string }}
+ * 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, env: string, 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 root_dir = path.resolve(server_dir, '..');
+  const package_root = path.resolve(server_dir, '..');
+  // Always reflect the directory from which the process was started
+  const root_dir = process.cwd();
 
-  /** @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
+    app_dir: path.resolve(package_root, 'app'),
+    root_dir,
+    url: `http://${host_value}:${port_value}`
   };
 }

package/server/db.js

@@ -11,6 +11,7 @@ import path from 'node:path';
  *
  * 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 }}
  */
@@ -48,6 +49,7 @@ export function resolveDbPath(options = {}) {
 /**
  * Find nearest .beads/*.db by walking up from start.
  * First alphabetical .db.
+ *
  * @param {string} start
  * @returns {string | null}
  */
@@ -58,7 +60,6 @@ export function findNearestBeadsDb(start) {
     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)
@@ -80,6 +81,7 @@ export function findNearestBeadsDb(start) {
 
 /**
  * Resolve possibly relative `p` against `cwd` to an absolute filesystem path.
+ *
  * @param {string} p
  * @param {string} cwd
  */

package/server/index.js

@@ -7,14 +7,18 @@ import { attachWsServer } from './ws.js';
 const config = getConfig();
 const app = createApp(config);
 const server = createServer(app);
-const { notifyIssuesChanged } = attachWsServer(server, {
+const { scheduleListRefresh } = attachWsServer(server, {
   path: '/ws',
-  heartbeat_ms: 30000
+  heartbeat_ms: 30000,
+  // Coalesce DB change bursts into one refresh run
+  refresh_debounce_ms: 75
 });
 
-// Watch the active beads DB and push invalidation (targeted when possible)
-watchDb(config.root_dir, (payload) => {
-  notifyIssuesChanged(payload);
+// Watch the active beads DB and schedule subscription refresh for active lists
+watchDb(config.root_dir, () => {
+  // Schedule subscription list refresh run for active subscriptions
+  scheduleListRefresh();
+  // v2: all updates flow via subscription push envelopes only
 });
 
 server.listen(config.port, config.host, () => {

package/server/list-adapters.js

@@ -0,0 +1,224 @@
+import { runBdJson } from './bd.js';
+
+/**
+ * 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'];
+    }
+    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', '--status', 'in_progress'];
+    }
+    case 'closed-issues': {
+      return ['list', '--json', '--status', 'closed'];
+    }
+    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
+ * @returns {Promise<FetchListResultSuccess | FetchListResultFailure>}
+ */
+export async function fetchListForSubscription(spec) {
+  /** @type {string[]} */
+  let args;
+  try {
+    args = mapSubscriptionToBdArgs(spec);
+  } catch (err) {
+    const e = toErrorObject(err);
+    return { ok: false, error: e };
+  }
+
+  try {
+    const res = await runBdJson(args);
+    if (!res || res.code !== 0 || !('stdoutJson' in res)) {
+      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,
+            // 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;
+      });
+    }
+
+    const items = normalizeIssueList(raw);
+    return { ok: true, items };
+  } catch (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;
+}