beads-ui 0.1.0

package/server/cli/cli.test.js

@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as commands from './commands.js';
+import { main, parseArgs } from './index.js';
+
+vi.mock('./commands.js', () => ({
+  handleStart: vi.fn().mockResolvedValue(0),
+  handleStop: vi.fn().mockResolvedValue(0),
+  handleRestart: vi.fn().mockResolvedValue(0)
+}));
+
+/** @type {import('vitest').MockInstance} */
+let write_mock;
+
+beforeEach(() => {
+  write_mock = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+});
+
+afterEach(() => {
+  write_mock.mockRestore();
+});
+
+describe('parseArgs', () => {
+  test('returns help flag when -h or --help present', () => {
+    const r1 = parseArgs(['-h']);
+    const r2 = parseArgs(['--help']);
+
+    expect(r1.flags.includes('help')).toBe(true);
+    expect(r2.flags.includes('help')).toBe(true);
+  });
+
+  test('returns command token when valid', () => {
+    expect(parseArgs(['start']).command).toBe('start');
+    expect(parseArgs(['stop']).command).toBe('stop');
+    expect(parseArgs(['restart']).command).toBe('restart');
+  });
+
+  test('recognizes --no-open flag', () => {
+    const r = parseArgs(['start', '--no-open']);
+
+    expect(r.flags.includes('no-open')).toBe(true);
+  });
+});
+
+describe('main', () => {
+  test('prints usage and exits 0 on --help', async () => {
+    const code = await main(['--help']);
+
+    expect(code).toBe(0);
+    expect(write_mock).toHaveBeenCalled();
+  });
+
+  test('prints usage and exits 1 on no command', async () => {
+    const code = await main([]);
+
+    expect(code).toBe(1);
+    expect(write_mock).toHaveBeenCalled();
+  });
+
+  test('dispatches to start handler', async () => {
+    const code = await main(['start']);
+
+    expect(code).toBe(0);
+    expect(commands.handleStart).toHaveBeenCalledTimes(1);
+  });
+
+  test('propagates --no-open to start handler', async () => {
+    await main(['start', '--no-open']);
+
+    expect(commands.handleStart).toHaveBeenCalledWith({ no_open: true });
+  });
+
+  test('reads BDUI_NO_OPEN=1 to disable open', async () => {
+    const prev = process.env.BDUI_NO_OPEN;
+    try {
+      process.env.BDUI_NO_OPEN = '1';
+
+      await main(['start']);
+
+      expect(commands.handleStart).toHaveBeenCalledWith({ no_open: true });
+    } finally {
+      if (prev === undefined) {
+        delete process.env.BDUI_NO_OPEN;
+      } else {
+        process.env.BDUI_NO_OPEN = prev;
+      }
+    }
+  });
+
+  test('dispatches to stop handler', async () => {
+    const code = await main(['stop']);
+
+    expect(code).toBe(0);
+    expect(commands.handleStop).toHaveBeenCalledTimes(1);
+  });
+
+  test('dispatches to restart handler', async () => {
+    const code = await main(['restart']);
+
+    expect(code).toBe(0);
+    expect(commands.handleRestart).toHaveBeenCalledTimes(1);
+  });
+
+  test('unknown command prints usage and exits 1', async () => {
+    const code = await main(['unknown']);
+
+    expect(code).toBe(1);
+    expect(write_mock).toHaveBeenCalled();
+  });
+});

package/server/cli/commands.integration.test.js

@@ -0,0 +1,155 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  test,
+  vi
+} from 'vitest';
+import { handleRestart, handleStart, handleStop } from './commands.js';
+import * as daemon from './daemon.js';
+
+// Mock browser open + readiness wait to avoid external effects and flakiness
+vi.mock('./open.js', () => ({
+  openUrl: async () => true,
+  waitForServer: async () => {}
+}));
+
+/** @type {string} */
+let tmp_runtime_dir;
+/** @type {Record<string, string | undefined>} */
+let prev_env;
+
+beforeAll(() => {
+  // Snapshot selected env vars to restore later
+  prev_env = {
+    BDUI_RUNTIME_DIR: process.env.BDUI_RUNTIME_DIR,
+    PORT: process.env.PORT,
+    BDUI_NO_OPEN: process.env.BDUI_NO_OPEN
+  };
+
+  tmp_runtime_dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bdui-it-'));
+  process.env.BDUI_RUNTIME_DIR = tmp_runtime_dir;
+  // Use port 0 so OS assigns an ephemeral port; URL printing still occurs
+  process.env.PORT = '0';
+  // Ensure default start path would not attempt to open the browser if called via CLI
+  process.env.BDUI_NO_OPEN = '1';
+});
+
+afterEach(async () => {
+  // Ensure no stray daemon is left between tests
+  const pid = daemon.readPidFile();
+  if (pid && daemon.isProcessRunning(pid)) {
+    await daemon.terminateProcess(pid, 2000);
+  }
+  daemon.removePidFile();
+  // Clear the daemon log to keep noise down in CI
+  try {
+    fs.writeFileSync(daemon.getLogFilePath(), '', 'utf8');
+  } catch {
+    // ignore
+  }
+});
+
+afterAll(() => {
+  // Restore env
+  if (prev_env.BDUI_RUNTIME_DIR === undefined) {
+    delete process.env.BDUI_RUNTIME_DIR;
+  } else {
+    process.env.BDUI_RUNTIME_DIR = prev_env.BDUI_RUNTIME_DIR;
+  }
+
+  if (prev_env.PORT === undefined) {
+    delete process.env.PORT;
+  } else {
+    process.env.PORT = prev_env.PORT;
+  }
+
+  if (prev_env.BDUI_NO_OPEN === undefined) {
+    delete process.env.BDUI_NO_OPEN;
+  } else {
+    process.env.BDUI_NO_OPEN = prev_env.BDUI_NO_OPEN;
+  }
+
+  try {
+    fs.rmSync(tmp_runtime_dir, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+});
+
+describe('commands integration', () => {
+  test('start then stop returns 0 and manages PID file', async () => {
+    // setup
+    const print_spy = vi
+      .spyOn(daemon, 'printServerUrl')
+      .mockImplementation(() => {});
+
+    // execution
+    const start_code = await handleStart({ no_open: true });
+
+    // assertion
+    expect(start_code).toBe(0);
+    const pid_after_start = daemon.readPidFile();
+    expect(typeof pid_after_start).toBe('number');
+    expect(Number(pid_after_start)).toBeGreaterThan(0);
+
+    // execution
+    const stop_code = await handleStop();
+
+    // assertion
+    expect(stop_code).toBe(0);
+    const pid_after_stop = daemon.readPidFile();
+    expect(pid_after_stop).toBeNull();
+
+    print_spy.mockRestore();
+  });
+
+  test('stop returns 2 when not running', async () => {
+    // execution
+    const code = await handleStop();
+
+    // assertion
+    expect(code).toBe(2);
+  });
+
+  test('start is idempotent when already running', async () => {
+    // setup
+    await handleStart({ no_open: true });
+    const start_spy = vi.spyOn(daemon, 'startDaemon');
+
+    // execution
+    const code = await handleStart({ no_open: true });
+
+    // assertion
+    expect(code).toBe(0);
+    expect(start_spy).not.toHaveBeenCalled();
+
+    // cleanup
+    start_spy.mockRestore();
+    await handleStop();
+  });
+
+  test('restart stops (when needed) and starts', async () => {
+    // setup
+    const print_spy = vi
+      .spyOn(daemon, 'printServerUrl')
+      .mockImplementation(() => {});
+
+    // execution
+    const code = await handleRestart();
+
+    // assertion
+    expect(code).toBe(0);
+    const pid = daemon.readPidFile();
+    expect(typeof pid).toBe('number');
+
+    // cleanup
+    await handleStop();
+    print_spy.mockRestore();
+  });
+});

package/server/cli/commands.js

@@ -0,0 +1,91 @@
+import { getConfig } from '../config.js';
+import {
+  isProcessRunning,
+  printServerUrl,
+  readPidFile,
+  removePidFile,
+  startDaemon,
+  terminateProcess
+} from './daemon.js';
+import { openUrl, waitForServer } from './open.js';
+
+/**
+ * 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.
+ * @returns {Promise<number>} Exit code (0 on success)
+ */
+/**
+ * @param {{ no_open?: boolean }} [options]
+ */
+export async function handleStart(options) {
+  const no_open = options?.no_open === true;
+  const existing_pid = readPidFile();
+  if (existing_pid && isProcessRunning(existing_pid)) {
+    printServerUrl();
+    return 0;
+  }
+  if (existing_pid && !isProcessRunning(existing_pid)) {
+    // stale PID file
+    removePidFile();
+  }
+
+  const started = startDaemon();
+  if (started && started.pid > 0) {
+    printServerUrl();
+    // Auto-open the browser once for a fresh daemon start
+    if (!no_open) {
+      const cfg = getConfig();
+      const url = 'http://' + cfg.host + ':' + String(cfg.port);
+      // 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;
+}
+
+/**
+ * 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.
+ * @returns {Promise<number>} Exit code (0 on success)
+ */
+export async function handleRestart() {
+  const stop_code = await handleStop();
+  // 0 = stopped, 2 = not running; both are acceptable to proceed
+  if (stop_code !== 0 && stop_code !== 2) {
+    return 1;
+  }
+  const start_code = await handleStart();
+  return start_code === 0 ? 0 : 1;
+}

package/server/cli/commands.unit.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, test, vi } from 'vitest';
+import { handleStart, handleStop } from './commands.js';
+import * as daemon from './daemon.js';
+
+describe('handleStart (unit)', () => {
+  test('returns 1 when daemon start fails', async () => {
+    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(null);
+    const is_running = vi
+      .spyOn(daemon, 'isProcessRunning')
+      .mockReturnValue(false);
+    const start = vi.spyOn(daemon, 'startDaemon').mockReturnValue(null);
+
+    const code = await handleStart({ no_open: true });
+
+    expect(code).toBe(1);
+
+    read_pid.mockRestore();
+    is_running.mockRestore();
+    start.mockRestore();
+  });
+
+  test('returns 0 when already running', async () => {
+    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(12345);
+    const is_running = vi
+      .spyOn(daemon, 'isProcessRunning')
+      .mockReturnValue(true);
+    const print_url = vi
+      .spyOn(daemon, 'printServerUrl')
+      .mockImplementation(() => {});
+
+    const code = await handleStart({ no_open: true });
+
+    expect(code).toBe(0);
+    expect(print_url).toHaveBeenCalledTimes(1);
+
+    read_pid.mockRestore();
+    is_running.mockRestore();
+    print_url.mockRestore();
+  });
+});
+
+describe('handleStop (unit)', () => {
+  test('returns 2 when not running and no PID file', async () => {
+    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(null);
+
+    const code = await handleStop();
+
+    expect(code).toBe(2);
+
+    read_pid.mockRestore();
+  });
+
+  test('returns 2 on stale PID and removes file', async () => {
+    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(1111);
+    const is_running = vi
+      .spyOn(daemon, 'isProcessRunning')
+      .mockReturnValue(false);
+    const remove_pid = vi
+      .spyOn(daemon, 'removePidFile')
+      .mockImplementation(() => {});
+
+    const code = await handleStop();
+
+    expect(code).toBe(2);
+    expect(remove_pid).toHaveBeenCalledTimes(1);
+
+    read_pid.mockRestore();
+    is_running.mockRestore();
+    remove_pid.mockRestore();
+  });
+
+  test('returns 0 when process terminates and removes PID', async () => {
+    const read_pid = vi.spyOn(daemon, 'readPidFile').mockReturnValue(2222);
+    const is_running = vi
+      .spyOn(daemon, 'isProcessRunning')
+      .mockReturnValue(true);
+    const terminate = vi
+      .spyOn(daemon, 'terminateProcess')
+      .mockResolvedValue(true);
+    const remove_pid = vi
+      .spyOn(daemon, 'removePidFile')
+      .mockImplementation(() => {});
+
+    const code = await handleStop();
+
+    expect(code).toBe(0);
+    expect(remove_pid).toHaveBeenCalledTimes(1);
+
+    read_pid.mockRestore();
+    is_running.mockRestore();
+    terminate.mockRestore();
+    remove_pid.mockRestore();
+  });
+});

package/server/cli/daemon.js

@@ -0,0 +1,239 @@
+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';
+
+/**
+ * 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'));
+  }
+
+  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.
+ * @returns {{ pid: number } | null} Returns child PID on success; null on failure.
+ */
+export function startDaemon() {
+  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');
+  } catch {
+    // If log cannot be opened, fallback to ignoring stdio
+    log_fd = -1;
+  }
+
+  /** @type {import('node:child_process').SpawnOptions} */
+  const opts = {
+    detached: true,
+    env: { ...process.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) {
+      writePidFile(child_pid);
+      return { pid: child_pid };
+    }
+    return null;
+  } catch (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() {
+  const cfg = getConfig();
+  const url = 'http://' + cfg.host + ':' + String(cfg.port);
+  console.log(url);
+}