@rsktash/beads-ui 0.1.0

package/server/cli/daemon.js

@@ -0,0 +1,340 @@
+/**
+ * @import { SpawnOptions } from 'node:child_process'
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import net from 'node:net';
+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);
+  });
+}
+
+/**
+ * Detect the TCP port a process is listening on by inspecting OS state.
+ * Returns the first LISTEN port found for the given PID, or null.
+ *
+ * @param {number} pid
+ * @returns {number | null}
+ */
+export function detectListeningPort(pid) {
+  try {
+    const output = execFileSync(
+      'lsof',
+      ['-iTCP', '-sTCP:LISTEN', '-a', '-p', String(pid), '-Fn', '-P'],
+      { encoding: 'utf8', timeout: 3000 }
+    );
+
+    // lsof -Fn outputs lines like "n*:3000" or "n127.0.0.1:4000"
+    for (const line of output.split('\n')) {
+      if (line.startsWith('n')) {
+        const colon_index = line.lastIndexOf(':');
+        if (colon_index >= 0) {
+          const port_value = Number.parseInt(line.slice(colon_index + 1), 10);
+          if (Number.isFinite(port_value) && port_value > 0) {
+            return port_value;
+          }
+        }
+      }
+    }
+  } catch {
+    // lsof not available or process gone — fall through
+  }
+  return null;
+}
+
+/**
+ * Check whether a TCP port is available on the given host.
+ *
+ * @param {number} port
+ * @param {string} host
+ * @returns {Promise<boolean>}
+ */
+export function isPortAvailable(port, host) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.listen(port, host, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+/**
+ * Starting from `port`, find the first available port on `host`.
+ * Tries up to `max_attempts` consecutive ports.
+ *
+ * @param {number} port
+ * @param {string} host
+ * @param {number} [max_attempts]
+ * @returns {Promise<number | null>}
+ */
+export async function findAvailablePort(port, host, max_attempts = 10) {
+  for (let i = 0; i < max_attempts; i++) {
+    if (await isPortAvailable(port + i, host)) {
+      return port + i;
+    }
+  }
+  return null;
+}
+
+/**
+ * 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/daemon.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, test, vi } from 'vitest';
+import { resolveWorkspaceDatabase } from '../db.js';
+import { printServerUrl } from './daemon.js';
+
+vi.mock('../db.js', () => ({
+  resolveWorkspaceDatabase: vi.fn(() => ({
+    path: '/repo/.beads',
+    source: 'metadata',
+    exists: true
+  }))
+}));
+
+vi.mock('../config.js', () => ({
+  getConfig: () => ({ url: 'http://127.0.0.1:3000' })
+}));
+
+describe('printServerUrl', () => {
+  test('prints workspace-aware database resolution', () => {
+    const log_spy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    printServerUrl();
+
+    expect(resolveWorkspaceDatabase).toHaveBeenCalledTimes(1);
+    expect(log_spy).toHaveBeenCalledWith('beads db   /repo/.beads (metadata)');
+    expect(log_spy).toHaveBeenCalledWith(
+      'beads ui   listening on http://127.0.0.1:3000'
+    );
+
+    log_spy.mockRestore();
+  });
+});

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,178 @@
+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));
+}
+
+/**
+ * Fetch the list of workspaces from the running server.
+ *
+ * @param {string} base_url - Server base URL (e.g., "http://127.0.0.1:3000")
+ * @returns {Promise<Array<{ path: string, database: string }>>}
+ */
+export async function fetchWorkspacesFromServer(base_url) {
+  return new Promise((resolve) => {
+    const url = new URL('/api/workspaces', base_url);
+    const req = http.get(url, (res) => {
+      let data = '';
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+      res.on('end', () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.ok && Array.isArray(parsed.workspaces)) {
+            resolve(parsed.workspaces);
+          } else {
+            resolve([]);
+          }
+        } catch {
+          resolve([]);
+        }
+      });
+    });
+    req.on('error', () => resolve([]));
+    req.setTimeout(2000, () => {
+      try {
+        req.destroy();
+      } catch {
+        void 0;
+      }
+      resolve([]);
+    });
+  });
+}
+
+/**
+ * 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/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');
+  });
+});