@rsktash/beads-ui 0.1.0

package/server/cli/cli.test.js

@@ -0,0 +1,207 @@
+import { readFile } from 'node:fs/promises';
+import { beforeEach, describe, expect, test, vi } from 'vitest';
+import * as logging from '../logging.js';
+import * as commands from './commands.js';
+import { main, parseArgs } from './index.js';
+
+vi.mock('node:fs/promises', () => ({
+  readFile: vi.fn()
+}));
+
+vi.mock('../logging.js', () => ({
+  enableAllDebug: vi.fn(),
+  debug: () => () => {}
+}));
+
+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;
+/** @type {import('vitest').MockInstance} */
+let read_file_mock;
+
+beforeEach(() => {
+  write_mock = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  read_file_mock = vi.mocked(readFile);
+  read_file_mock.mockResolvedValue(JSON.stringify({ version: '1.2.3' }));
+});
+
+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 --debug and -d flags', () => {
+    const r1 = parseArgs(['--debug']);
+    const r2 = parseArgs(['-d']);
+
+    expect(r1.flags.includes('debug')).toBe(true);
+    expect(r2.flags.includes('debug')).toBe(true);
+  });
+  test('recognizes --open flag', () => {
+    const r = parseArgs(['start', '--open']);
+
+    expect(r.flags.includes('open')).toBe(true);
+  });
+
+  test('recognizes -v and --version flags', () => {
+    const r1 = parseArgs(['-v']);
+    const r2 = parseArgs(['--version']);
+
+    expect(r1.flags.includes('version')).toBe(true);
+    expect(r2.flags.includes('version')).toBe(true);
+  });
+
+  test('parses --host option', () => {
+    const r = parseArgs(['start', '--host', '0.0.0.0']);
+
+    expect(r.options.host).toBe('0.0.0.0');
+  });
+
+  test('parses --port option', () => {
+    const r = parseArgs(['start', '--port', '8080']);
+
+    expect(r.options.port).toBe(8080);
+  });
+
+  test('ignores invalid --port value', () => {
+    const r = parseArgs(['start', '--port', 'abc']);
+
+    expect(r.options.port).toBeUndefined();
+  });
+});
+
+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 version and exits 0 on --version', async () => {
+    const code = await main(['--version']);
+
+    expect(code).toBe(0);
+    expect(write_mock).toHaveBeenCalled();
+    const output = write_mock.mock.calls.map((c) => String(c[0])).join('');
+    expect(output.trim()).toBe('1.2.3');
+  });
+
+  test('enables debug when --debug passed', async () => {
+    const spy = vi.spyOn(logging, 'enableAllDebug');
+
+    await main(['--debug', '--help']);
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  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 --open to start handler', async () => {
+    await main(['start', '--open']);
+
+    expect(commands.handleStart).toHaveBeenCalledWith({
+      open: true,
+      is_debug: false,
+      host: undefined,
+      port: undefined
+    });
+  });
+
+  test('propagates --host and --port to start handler', async () => {
+    await main(['start', '--host', '0.0.0.0', '--port', '8080']);
+
+    expect(commands.handleStart).toHaveBeenCalledWith({
+      open: false,
+      is_debug: false,
+      host: '0.0.0.0',
+      port: 8080
+    });
+  });
+
+  test('help lists --open', async () => {
+    const write_spy = write_mock;
+    write_spy.mockClear();
+
+    await main(['--help']);
+
+    const output = write_spy.mock.calls.map((c) => String(c[0])).join('');
+    expect(output.includes('--open')).toBe(true);
+  });
+
+  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);
+    expect(commands.handleRestart).toHaveBeenCalledWith({
+      open: false,
+      is_debug: false,
+      host: undefined,
+      port: undefined
+    });
+  });
+
+  test('propagates --open to restart handler', async () => {
+    await main(['restart', '--open']);
+
+    expect(commands.handleRestart).toHaveBeenCalledWith({
+      open: true,
+      is_debug: false,
+      host: undefined,
+      port: undefined
+    });
+  });
+
+  test('propagates --host and --port to restart handler', async () => {
+    await main(['restart', '--host', '0.0.0.0', '--port', '9000']);
+
+    expect(commands.handleRestart).toHaveBeenCalledWith({
+      open: false,
+      is_debug: false,
+      host: '0.0.0.0',
+      port: 9000
+    });
+  });
+
+  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,148 @@
+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 () => {},
+  registerWorkspaceWithServer: async () => true
+}));
+
+// Mock db resolution to avoid file system dependencies
+vi.mock('../db.js', () => ({
+  resolveDbPath: () => ({
+    path: '/mock/test.db',
+    source: 'nearest',
+    exists: true
+  }),
+  resolveWorkspaceDatabase: () => ({
+    path: '/mock/test.db',
+    source: 'nearest',
+    exists: true
+  })
+}));
+
+/** @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
+  };
+
+  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';
+  vi.spyOn(console, 'log').mockImplementation(() => {});
+});
+
+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();
+});
+
+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;
+  }
+
+  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
+    vi.spyOn(daemon, 'printServerUrl').mockImplementation(() => {});
+
+    // execution
+    const start_code = await handleStart({ open: false });
+
+    // 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();
+  });
+
+  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({ open: false });
+    const start_spy = vi.spyOn(daemon, 'startDaemon');
+
+    // execution
+    const code = await handleStart({ open: false });
+
+    // assertion
+    expect(code).toBe(0);
+    expect(start_spy).not.toHaveBeenCalled();
+
+    // cleanup
+    await handleStop();
+  });
+
+  test('restart stops (when needed) and starts', async () => {
+    // setup
+    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();
+  });
+});

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;
+}