beads-enhanced-ui 0.1.0

package/server/cli/daemon.js

@@ -0,0 +1,271 @@
+/**
+ * @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 { resolveWorkspaceDatabase } 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() {
+  const override_dir = process.env.BDUI_RUNTIME_DIR;
+  if (override_dir && override_dir.length > 0) {
+    return ensureDir(override_dir);
+  }
+
+  const xdg_dir = process.env.XDG_RUNTIME_DIR;
+  if (xdg_dir && xdg_dir.length > 0) {
+    return ensureDir(path.join(xdg_dir, 'beads-ui'));
+  }
+
+  return ensureDir(path.join(os.tmpdir(), 'beads-ui'));
+}
+
+/**
+ * Ensure a directory exists with safe permissions and return its path.
+ *
+ * @param {string} dir_path
+ * @returns {string}
+ */
+function ensureDir(dir_path) {
+  try {
+    fs.mkdirSync(dir_path, { recursive: true, mode: 0o700 });
+  } catch {
+    // Best-effort; permission errors will surface on file ops later.
+  }
+  return dir_path;
+}
+
+/**
+ * @returns {string}
+ */
+export function getPidFilePath() {
+  const runtime_dir = getRuntimeDir();
+  return path.join(runtime_dir, 'server.pid');
+}
+
+/**
+ * @returns {string}
+ */
+export function getLogFilePath() {
+  const runtime_dir = getRuntimeDir();
+  return path.join(runtime_dir, 'daemon.log');
+}
+
+/**
+ * Read PID from the PID file if present.
+ *
+ * @returns {number | null}
+ */
+export function readPidFile() {
+  const pid_file = getPidFilePath();
+  try {
+    const text = fs.readFileSync(pid_file, 'utf8');
+    const pid_value = Number.parseInt(text.trim(), 10);
+    if (Number.isFinite(pid_value) && pid_value > 0) {
+      return pid_value;
+    }
+  } catch {
+    // ignore missing or unreadable
+  }
+  return null;
+}
+
+/**
+ * @param {number} pid
+ */
+export function writePidFile(pid) {
+  const pid_file = getPidFilePath();
+  try {
+    fs.writeFileSync(pid_file, String(pid) + '\n', { encoding: 'utf8' });
+  } catch {
+    // ignore write errors; daemon still runs but management degrades
+  }
+}
+
+export function removePidFile() {
+  const pid_file = getPidFilePath();
+  try {
+    fs.unlinkSync(pid_file);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Check whether a process is running.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isProcessRunning(pid) {
+  try {
+    if (pid <= 0) {
+      return false;
+    }
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const code = /** @type {{ code?: string }} */ (err).code;
+    if (code === 'ESRCH') {
+      return false;
+    }
+    // EPERM or other errors imply the process likely exists but is not killable
+    return true;
+  }
+}
+
+/**
+ * Compute the absolute path to the server entry file.
+ *
+ * @returns {string}
+ */
+export function getServerEntryPath() {
+  const here = fileURLToPath(new URL(import.meta.url));
+  const cli_dir = path.dirname(here);
+  const server_entry = path.resolve(cli_dir, '..', 'index.js');
+  return server_entry;
+}
+
+/**
+ * Spawn the server as a detached daemon, redirecting stdio to the log file.
+ * Writes the PID file upon success.
+ *
+ * @param {{ is_debug?: boolean, host?: string, port?: number }} [options]
+ * @returns {{ pid: number } | null} Returns child PID on success; null on failure.
+ */
+export function startDaemon(options = {}) {
+  const server_entry = getServerEntryPath();
+  const log_file = getLogFilePath();
+
+  // Open the log file for appending; reuse for both stdout and stderr
+  /** @type {number} */
+  let log_fd;
+  try {
+    log_fd = fs.openSync(log_file, 'a');
+    if (options.is_debug) {
+      console.debug('log file  ', log_file);
+    }
+  } catch {
+    // If log cannot be opened, fallback to ignoring stdio
+    log_fd = -1;
+  }
+
+  /** @type {Record<string, string | undefined>} */
+  const spawn_env = { ...process.env };
+  if (options.host) {
+    spawn_env.HOST = options.host;
+  }
+  if (options.port) {
+    spawn_env.PORT = String(options.port);
+  }
+
+  /** @type {SpawnOptions} */
+  const opts = {
+    cwd: process.cwd(),
+    detached: true,
+    env: spawn_env,
+    stdio: log_fd >= 0 ? ['ignore', log_fd, log_fd] : 'ignore',
+    windowsHide: true
+  };
+
+  try {
+    const child = spawn(process.execPath, [server_entry], opts);
+    // Detach fully from the parent
+    child.unref();
+    const child_pid = typeof child.pid === 'number' ? child.pid : -1;
+    if (child_pid > 0) {
+      if (options.is_debug) {
+        console.debug('starting  ', child_pid);
+      }
+      writePidFile(child_pid);
+      return { pid: child_pid };
+    }
+    return null;
+  } catch (err) {
+    console.error('start error', err);
+    // Log startup error to log file for traceability
+    try {
+      const message =
+        new Date().toISOString() + ' start error: ' + String(err) + '\n';
+      fs.appendFileSync(log_file, message, 'utf8');
+    } catch {
+      // ignore
+    }
+    return null;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function terminateProcess(pid, timeout_ms) {
+  try {
+    process.kill(pid, 'SIGTERM');
+  } catch (err) {
+    const code = /** @type {{ code?: string }} */ (err).code;
+    if (code === 'ESRCH') {
+      return true;
+    }
+    // On EPERM or others, continue to wait/poll
+  }
+
+  const start_time = Date.now();
+  // Poll until process no longer exists or timeout
+  while (Date.now() - start_time < timeout_ms) {
+    if (!isProcessRunning(pid)) {
+      return true;
+    }
+    await sleep(100);
+  }
+
+  // Fallback to SIGKILL
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    // ignore
+  }
+
+  // Give a brief moment after SIGKILL
+  await sleep(50);
+  return !isProcessRunning(pid);
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}
+
+/**
+ * Print the server URL derived from current config.
+ */
+export function printServerUrl() {
+  // Resolve from the caller's working directory by default
+  const resolved_db = resolveWorkspaceDatabase();
+  console.log(
+    `beads db   ${resolved_db.path} (${resolved_db.source}${resolved_db.exists ? '' : ', missing'})`
+  );
+
+  const { url } = getConfig();
+  console.log(`beads ui   listening on ${url}`);
+}

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,139 @@
+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));
+}
+
+/**
+ * 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}`
+  };
+}