@seungyeop-lee/beads-ui 0.13.0

package/server/cli/commands.js

@@ -0,0 +1,285 @@
+import { getConfig } from '../config.js';
+import { resolveWorkspaceDatabase } from '../db.js';
+import {
+  detectListeningPort,
+  findAvailablePort,
+  isProcessRunning,
+  printServerUrl,
+  readPidFile,
+  removePidFile,
+  startDaemon,
+  terminateProcess
+} from './daemon.js';
+import {
+  fetchWorkspacesFromServer,
+  openUrl,
+  registerWorkspaceWithServer,
+  waitForServer
+} from './open.js';
+
+const RESTART_SERVER_READY_MS = 400;
+
+const STARTUP_SETTLE_MS = 200;
+const REGISTER_RETRY_ATTEMPTS = 5;
+const REGISTER_RETRY_DELAY_MS = 150;
+
+/**
+ * Handle `start` command. Idempotent when already running.
+ * - Spawns a detached server process, writes PID file, returns 0.
+ * - If already running (PID file present and process alive), prints URL and returns 0.
+ *
+ * @param {{ open?: boolean, is_debug?: boolean, host?: string, port?: number }} [options]
+ * @returns {Promise<number>} Exit code (0 on success)
+ */
+export async function handleStart(options) {
+  // Default: do not open a browser unless explicitly requested via `open: true`.
+  const should_open = options?.open === true;
+  const cwd = process.cwd();
+
+  // Set env vars early so getConfig() reflects CLI overrides in ALL branches,
+  // including the "already running" path that registers workspaces via HTTP.
+  if (options?.host) {
+    process.env.HOST = options.host;
+  }
+  if (options?.port) {
+    process.env.PORT = String(options.port);
+  }
+
+  const existing_pid = readPidFile();
+  if (existing_pid && isProcessRunning(existing_pid)) {
+    // Server is already running - register this workspace dynamically
+    const { url } = getConfig();
+    const registered = await registerCurrentWorkspace(url, cwd);
+    if (registered) {
+      console.log('Workspace registered: %s', cwd);
+    }
+    console.warn('Server is already running.');
+    if (should_open) {
+      await openUrl(url);
+    }
+    return 0;
+  }
+  if (existing_pid && !isProcessRunning(existing_pid)) {
+    // stale PID file
+    removePidFile();
+  }
+
+  const { port: config_port, host: config_host } = getConfig();
+
+  // When the user did not pass an explicit --port, check whether the default
+  // port is already in use. If something is already listening, try to register
+  // with it first — it may be an existing bdui instance we can reuse.
+  // Only auto-increment to the next port if registration fails.
+  let effective_port = options?.port;
+  if (!effective_port) {
+    const available = await findAvailablePort(config_port, config_host);
+    if (available === null) {
+      console.error(
+        'No available port found (tried %d–%d).',
+        config_port,
+        config_port + 9
+      );
+      return 1;
+    }
+    if (available !== config_port) {
+      // Default port is busy — try to register with whatever is there.
+      const existing_url = `http://${config_host}:${config_port}`;
+      const registered = await registerCurrentWorkspace(existing_url, cwd);
+      if (registered) {
+        console.log('Workspace registered with existing server: %s', cwd);
+        if (should_open) {
+          await openUrl(existing_url);
+        }
+        return 0;
+      }
+      // Not a bdui instance — auto-increment to the next available port.
+      console.log('Port %d in use, using %d instead.', config_port, available);
+      effective_port = available;
+    }
+  }
+
+  // Set PORT env so getConfig() returns the correct URL for registration
+  if (effective_port) {
+    process.env.PORT = String(effective_port);
+  }
+  const { url } = getConfig();
+
+  const started = startDaemon({
+    is_debug: options?.is_debug,
+    host: options?.host,
+    port: effective_port
+  });
+  if (started && started.pid > 0) {
+    // Give the spawned daemon a brief moment to fail fast (for example EADDRINUSE).
+    await sleep(STARTUP_SETTLE_MS);
+
+    if (!isProcessRunning(started.pid)) {
+      removePidFile();
+
+      // If another server is already running at the configured URL, register this
+      // workspace there so it appears in the picker instead of silently missing.
+      const registered = await registerCurrentWorkspaceWithRetry(url, cwd);
+      if (registered) {
+        console.warn(
+          'Daemon exited early; registered workspace with existing server: %s',
+          cwd
+        );
+        return 0;
+      }
+      return 1;
+    }
+
+    // Register against the currently reachable server to ensure this workspace
+    // appears in the picker even when startup races with other daemons.
+    void registerCurrentWorkspaceWithRetry(url, cwd);
+
+    printServerUrl();
+    // Auto-open the browser once for a fresh daemon start
+    if (should_open) {
+      // Wait briefly for the server to accept connections (single retry window)
+      await waitForServer(url, 600);
+      // Best-effort open; ignore result
+      await openUrl(url);
+    }
+    return 0;
+  }
+
+  return 1;
+}
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, ms);
+  });
+}
+
+/**
+ * @param {string} url
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function registerCurrentWorkspace(url, cwd) {
+  const workspace_database = resolveWorkspaceDatabase({ cwd });
+  if (
+    workspace_database.source === 'home-default' ||
+    !workspace_database.exists
+  ) {
+    return false;
+  }
+
+  return registerWorkspaceWithServer(url, {
+    path: cwd,
+    database: workspace_database.path
+  });
+}
+
+/**
+ * @param {string} url
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function registerCurrentWorkspaceWithRetry(url, cwd) {
+  for (let i = 0; i < REGISTER_RETRY_ATTEMPTS; i++) {
+    const registered = await registerCurrentWorkspace(url, cwd);
+    if (registered) {
+      return true;
+    }
+    if (i < REGISTER_RETRY_ATTEMPTS - 1) {
+      await sleep(REGISTER_RETRY_DELAY_MS);
+    }
+  }
+  return false;
+}
+
+/**
+ * Handle `stop` command.
+ * - Sends SIGTERM and waits for exit (with SIGKILL fallback), removes PID file.
+ * - Returns 2 if not running.
+ *
+ * @returns {Promise<number>} Exit code
+ */
+export async function handleStop() {
+  const existing_pid = readPidFile();
+  if (!existing_pid) {
+    return 2;
+  }
+
+  if (!isProcessRunning(existing_pid)) {
+    // stale PID file
+    removePidFile();
+    return 2;
+  }
+
+  const terminated = await terminateProcess(existing_pid, 5000);
+  if (terminated) {
+    removePidFile();
+    return 0;
+  }
+
+  // Not terminated within timeout
+  return 1;
+}
+
+/**
+ * Handle `restart` command: stop (ignore not-running) then start.
+ * Accepts the same options as `handleStart` and passes them through,
+ * so restart only opens a browser when `open` is explicitly true.
+ *
+ * When the user does not pass explicit `--port`, the restart detects the
+ * port the running daemon is listening on and reuses it.
+ *
+ * @param {{ open?: boolean, host?: string, port?: number }} [options]
+ * @returns {Promise<number>}
+ */
+export async function handleRestart(options) {
+  // Capture state from the running server before stopping it.
+  let detected_port = null;
+  /** @type {Array<{ path: string, database: string }>} */
+  let saved_workspaces = [];
+  const existing_pid = readPidFile();
+  if (existing_pid && isProcessRunning(existing_pid)) {
+    detected_port = detectListeningPort(existing_pid);
+
+    const { url } = getConfig();
+    saved_workspaces = await fetchWorkspacesFromServer(url);
+  }
+
+  const stop_code = await handleStop();
+  // 0 = stopped, 2 = not running; both are acceptable to proceed
+  if (stop_code !== 0 && stop_code !== 2) {
+    return 1;
+  }
+
+  // Reuse detected port unless the user explicitly passed one.
+  const merged_options = { ...options };
+  if (!merged_options.port && detected_port) {
+    merged_options.port = detected_port;
+  }
+
+  const start_code = await handleStart(merged_options);
+  if (start_code !== 0) {
+    return 1;
+  }
+
+  // Re-register workspaces from the previous server.
+  if (saved_workspaces.length > 0) {
+    const { url } = getConfig();
+    await waitForServer(url, RESTART_SERVER_READY_MS);
+    for (const ws of saved_workspaces) {
+      if (ws.path && ws.database) {
+        await registerWorkspaceWithServer(url, {
+          path: ws.path,
+          database: ws.database
+        });
+      }
+    }
+  }
+
+  return 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}`);
+}