codebase-onboarder 0.3.1 → 0.4.1

package/server/daemon.js

@@ -0,0 +1,195 @@
+// Running the server without the terminal that asked for it.
+//
+// `onboarder start` keeps the process attached: closing the shell kills it, and
+// that is the right behavior for a foreground command. `onboarder start
+// background` wants the opposite — the whole point is that the terminal can go
+// away — so this module does what a shell job control cannot do portably: it
+// re-launches the CLI as a **detached** child with its stdio pointed at a log
+// file, unrefs it, and then waits for the port to actually answer before it
+// claims success.
+//
+// Two rules keep this honest:
+//
+//   1. Never report "running" on the strength of the spawn alone. `spawn`
+//      returning a pid proves a process was created, not that it bound the port
+//      or survived settings validation. Readiness is an HTTP answer from
+//      `/api/health`, polled with a deadline; on timeout the caller gets the
+//      child's last log lines, not a false green light.
+//   2. Detach properly, or "background" is a lie. `detached: true` puts the
+//      child in its own process group, and `unref()` drops our handle on it, so
+//      a Ctrl-C in the parent terminal does not take the server down with it.
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { configPath } from './config.js';
+import { readPidFile } from './pidfile.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+// The installed entry point, not `process.argv[1]`: a globally installed
+// `onboarder` is a symlink into node_modules, and the child has to run the real
+// file to find its siblings.
+export const CLI_ENTRY = path.resolve(HERE, '..', 'bin', 'onboarder.js');
+
+// One file per config, beside the config, so `--config` isolation (tests,
+// containers, several profiles) carries the log with it.
+export function logPath(configFile = configPath()) {
+  return path.join(path.dirname(path.resolve(configFile)), 'onboarder.log');
+}
+
+// Rotated history. One generation is deliberate: a log that grows without bound
+// is a bug report waiting to happen, and one previous file is enough to see what
+// happened just before a crash.
+export const MAX_LOG_BYTES = 2 * 1024 * 1024;
+
+export async function rotateLogIfNeeded(file = logPath(), maxBytes = MAX_LOG_BYTES) {
+  try {
+    const { size } = await fsp.stat(file);
+    if (size <= maxBytes) return false;
+    await fsp.rename(file, file + '.1');
+    return true;
+  } catch {
+    return false; // no log yet, or not ours to move
+  }
+}
+
+export async function readLog(file = logPath(), bytes = 64 * 1024) {
+  try {
+    const handle = await fsp.open(file, 'r');
+    try {
+      const { size } = await handle.stat();
+      const start = Math.max(0, size - bytes);
+      const buffer = Buffer.alloc(size - start);
+      await handle.read(buffer, 0, buffer.length, start);
+      return buffer.toString('utf8');
+    } finally {
+      await handle.close();
+    }
+  } catch {
+    return '';
+  }
+}
+
+// The last `count` lines, oldest first — the shape `onboarder logs` prints and
+// the shape an error report wants pasted into it.
+export async function tailLog(file = logPath(), count = 40) {
+  const text = await readLog(file);
+  const lines = text.split('\n').filter((line) => line.trim());
+  return lines.slice(-Math.max(1, count));
+}
+
+export async function logExists(file = logPath()) {
+  try { await fsp.access(file); return true; } catch { return false; }
+}
+
+// Ask the server whether it is up. A 2xx–4xx from /api/health means the socket
+// is bound and the router is serving; the body is not interesting, the answer is.
+export function probe(url, timeoutMs = 1000) {
+  return new Promise((resolve) => {
+    const request = http.get(url, { timeout: timeoutMs }, (res) => {
+      res.resume();
+      resolve(res.statusCode >= 200 && res.statusCode < 500);
+    });
+    request.on('timeout', () => { request.destroy(); resolve(false); });
+    request.on('error', () => resolve(false));
+  });
+}
+
+export async function waitForReady(url, { timeoutMs = 20000, intervalMs = 200, check = probe } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (await check(url)) return true;
+    if (Date.now() >= deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Re-run this same CLI, detached. The child is a plain foreground `start` — it
+// writes the pid file, prints its own banner, and handles signals exactly as it
+// always has. Nothing about the server changes; only who is holding the terminal
+// does.
+export function spawnDetached({ configFile = configPath(), entry = CLI_ENTRY, env = process.env, log = logPath(configFile) } = {}) {
+  const fd = fs.openSync(log, 'a');
+  try {
+    const child = spawn(process.execPath, [entry, 'start', '--config', configFile], {
+      detached: true,
+      stdio: ['ignore', fd, fd],
+      env: { ...env, ONBOARDER_BACKGROUND: '1' },
+    });
+    child.on('error', () => {});
+    child.unref();
+    return child.pid;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Does the OS still have this process? Signal 0 asks without delivering.
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+
+// Wait for the detached child to become the *recorded* server. The pid file is
+// the authority here, not the spawn pid: it is what `status` and `stop` read,
+// so waiting on it means the process we report is the one the user can control.
+export async function waitForPidFile(configFile, { timeoutMs = 20000, intervalMs = 150, readPid = readPidFile, isAlive = alive } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const pid = readPid(configFile);
+    if (pid && isAlive(pid)) return pid;
+    if (Date.now() >= deadline) return null;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+
+// Follow a growing file. Polling rather than fs.watch: the log is appended by a
+// *different* process, and watchers on a file another process holds open are
+// unreliable across platforms (and absent on some network mounts). Half a second
+// of latency on a human-facing log tail is invisible.
+export function followLog(file, onLine, { intervalMs = 500, from = 'end' } = {}) {
+  let position = 0;
+  let partial = '';
+  let stopped = false;
+  const stop = () => { stopped = true; };
+
+  if (from === 'start') {
+    fsp.readFile(file, 'utf8').then(
+      (text) => { for (const line of text.split('\n')) if (line) onLine(line); },
+      () => {},
+    );
+  }
+
+  const tick = async () => {
+    if (stopped) return;
+    try {
+      const { size } = await fsp.stat(file);
+      if (size < position) { position = 0; partial = ''; } // rotated under us
+      if (size > position) {
+        const handle = await fsp.open(file, 'r');
+        try {
+          const length = size - position;
+          const buffer = Buffer.alloc(length);
+          await handle.read(buffer, 0, length, position);
+          position = size;
+          // A read can land mid-line; hold the remainder until its newline shows.
+          const lines = (partial + buffer.toString('utf8')).split('\n');
+          partial = lines.pop() ?? '';
+          for (const line of lines) onLine(line);
+        } finally {
+          await handle.close();
+        }
+      }
+    } catch {
+      // The file may not exist yet (first run) — try again on the next tick.
+    }
+    if (!stopped) setTimeout(tick, intervalMs).unref();
+  };
+
+  setTimeout(tick, intervalMs).unref();
+  return stop;
+}

package/server/index.js

@@ -23,7 +23,9 @@ import { createLogger } from './logger.js';
 import { createMcpRunner } from './mcp/runner.js';
 import { browserUrl, configPath, isLoopbackHost, readSettings, serverUrls } from './config.js';
 import { tunnelStatus } from './tunnel.js';
-import { pidIsAlive, readPidFile, removePidFile, writePidFile } from './pidfile.js';
+import { pidIsAlive, readPidFile, removePidFile, writePidFile, writeRunInfo, runInfoPath } from './pidfile.js';
+import { logPath } from './daemon.js';
+import { panel, row } from './layout.js';
 
 const logger = createLogger();
 
@@ -63,42 +65,45 @@ export function createServer(config = CONFIG) {
 
 // What the terminal shows once the socket is listening. A pure string builder
 // so the CLI prints exactly this too, and so a test can read it.
-export function startupBanner(settings, { configFile } = {}) {
+//
+// The shape is label/value rows, not prose, because every fact here has to be
+// readable at a glance and copy-pasteable. The one long sentence it used to
+// print — "self-hosted — the network can reach this; every API call needs the
+// access key" — wrapped unpredictably at any terminal width and buried the URL
+// people actually need. Now the detail lives on its own row.
+export function startupBanner(settings, { configFile, columns } = {}) {
   const urls = serverUrls(settings);
-  const lines = ['', '  Onboarder is up.'];
-  lines.push(settings.mode === 'self-hosted'
-    ? (isLoopbackHost(settings.host)
-      ? '  Mode    self-hosted — loopback bind; use a tunnel or change the host for direct network access'
-      : '  Mode    self-hosted — the network can reach this; every API call needs the access key')
-    : '  Mode    local — only this machine can reach it');
-  lines.push('  Local   ' + urls.local);
-  if (urls.network) lines.push('  Network ' + urls.network);
-  if (urls.domain) {
-    lines.push('  Domain  ' + urls.domain);
-    if (settings.domain && !settings.https) {
-      lines.push('  HTTPS   disabled — `onboarder setup` or `onboarder https setup` enables trusted TLS');
-    } else if (settings.https) {
-      lines.push('  HTTPS   Caddy obtains, renews, and terminates TLS for this domain');
-    }
-  }
-  if (settings.mode === 'self-hosted' && settings.accessKey) {
-    lines.push('  Remote browsers show an access-key sign-in page; the key is never put in the URL.');
+  const rows = [];
+  const add = (label, value) => rows.push([label, value]);
+
+  add('URL', urls.local);
+  if (urls.network) add('Network', urls.network);
+  if (urls.domain) add('Public', urls.domain);
+  add('Bind', `${settings.host}:${settings.port}`);
+  add('Mode', settings.mode === 'self-hosted'
+    ? (isLoopbackHost(settings.host) ? 'self-hosted (loopback — use a tunnel)' : 'self-hosted (network reachable)')
+    : 'local (this machine only)');
+
+  if (settings.mode === 'self-hosted') {
+    add('Auth', settings.accessKey
+      ? 'access key required for remote browsers'
+      : 'NO ACCESS KEY — every API call is refused');
   }
-  if (settings.mode === 'self-hosted' && !settings.accessKey) {
-    lines.push('  WARNING self-hosted with no access key — every API call is refused until one is set.');
-    lines.push('          Run `onboarder setup` or `onboarder config key rotate`.');
+  if (settings.domain) {
+    add('HTTPS', settings.https ? 'Caddy terminates TLS for this domain' : 'off — `onboarder https setup` enables it');
   }
   const tunnels = tunnelStatus(settings);
   for (const name of ['cloudflare', 'tailscale']) {
     const t = tunnels[name];
     if (!t.enabled) continue;
-    lines.push(t.installed
-      ? `  Tunnel  ${name}: ${t.command}`
-      : `  Tunnel  ${name} is enabled but its CLI is not installed — ${t.install}`);
+    add('Tunnel', t.installed ? `${name}: ${t.command}` : `${name} enabled, CLI missing — ${t.install}`);
   }
-  if (configFile) lines.push('  Config  ' + configFile);
-  lines.push('');
-  return lines.join('\n');
+  if (configFile) add('Config', configFile);
+
+  // Rendered through the same panel helper the CLI uses, so `node server/index.js`
+  // and `onboarder start` cannot drift apart — and so both adapt to the terminal
+  // width instead of assuming 80 columns.
+  return '\n' + panel('Onboarder is up', rows.map(([label, value]) => row(label, value)), { columns }) + '\n';
 }
 
 // Ask the OS to open the app. Best-effort and detached: a missing opener on a
@@ -164,14 +169,33 @@ export async function startServer({ configFile = configPath(), openBrowser, log
     throw listenError(error, { host, port, pid: recorded && pidIsAlive(recorded) ? recorded : null });
   }
 
+  // The process record is optional by design, so each write is guarded on its
+  // own: a read-only config directory must not stop a server that has already
+  // bound its port, but a *programming* error here would otherwise be swallowed
+  // and look like "it started, but nothing recorded it".
+  try { writePidFile(configFile); } catch { /* read-only config dir */ }
+  // How this process was launched. `background` is a detached child with a log
+  // file; `startup` is one the OS supervisor started at login (also with a log
+  // file); anything else is a person typing `onboarder start` in a terminal.
+  const mode = process.env.ONBOARDER_LAUNCH || (process.env.ONBOARDER_BACKGROUND ? 'background' : 'foreground');
+  const logFile = mode === 'foreground' ? null : logPath(configFile);
   try {
-    writePidFile(configFile);
-    server.once('close', () => removePidFile(configFile));
-    process.once('exit', () => removePidFile(configFile));
-  } catch {
-    // The server is useful even when a read-only config directory cannot hold
-    // the optional process record; binding and serving are the real contract.
+    // Beside the pid: how this instance was launched and where its log goes, so
+    // `onboarder status` answers "how long has it been up, and how do I see its
+    // output" from a record instead of guessing.
+    writeRunInfo(configFile, {
+      mode,
+      host,
+      port,
+      url: serverUrls(live).local,
+      log: logFile,
+      node: process.version,
+    });
+  } catch (error) {
+    logger.warn('could not write the run record', { file: runInfoPath(configFile), error: error.message });
   }
+  server.once('close', () => removePidFile(configFile));
+  process.once('exit', () => removePidFile(configFile));
 
   log(startupBanner(live, { configFile }));
 

package/server/layout.js

@@ -0,0 +1,73 @@
+// Terminal geometry, with no color and no dependencies.
+//
+// This lives here, under `server/`, because two very different callers need
+// identical layout: the CLI (which paints) and the server's own startup banner
+// (which must not import `cli/ui.js` — that would invert the dependency, since
+// the CLI sits on top of the server). So the *shape* is here and the *color* is
+// injected by the caller as a `paint(text, style)` function.
+//
+// Everything is pure string math on purpose: a layout decision is a thing you
+// want to unit-test without spawning a terminal, and the whole reason panels
+// used to look broken is that this math was scattered through the callers.
+
+export function width(text) {
+  return String(text).replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+// The terminal we are drawing into, asked at call time rather than cached at
+// import: a panel printed after the user resized their window should use the
+// new size. Falls back to COLUMNS, then 80, so a pipe or a log file still gets
+// sane output instead of `undefined`.
+export function termWidth(stream = process.stdout) {
+  return stream.columns || Number(process.env.COLUMNS) || 80;
+}
+
+// Shorten to fit, with a real ellipsis. The middle is elided rather than the
+// tail, because in a path or URL the end is the part that identifies it.
+export function fit(text, max, { tail = true } = {}) {
+  const value = String(text);
+  if (max <= 0) return '';
+  if (value.length <= max) return value;
+  if (max === 1) return '…';
+  if (!tail) return value.slice(0, max - 1) + '…';
+  const head = Math.ceil((max - 1) * 0.4);
+  const rest = max - 1 - head;
+  return (head ? value.slice(0, head) + '…' : '…') + value.slice(value.length - rest);
+}
+
+// A titled block of rows that fits the terminal it is printed into. The frame is
+// sized from its contents, then clamped to the available width, and every value
+// is elided to fit rather than allowed to spill past the border — a panel whose
+// right edge is off-screen is what makes output "mess the terminal".
+//
+// `paint` is injected: `(text, style) => string`, where style is 'label' or
+// 'frame'. The default is identity, which is what the server banner and the
+// `--no-color` path want.
+export function panel(title, rows, { indent = '  ', columns, paint = (t) => String(t) } = {}) {
+  // The hard ceiling is the terminal. A floor below it would be a lie: on a 40
+  // column terminal a 59-wide panel is exactly the overflow this exists to
+  // prevent, so the floor only guards against a nonsensical zero, and short
+  // titles/values are handled by the `fit` calls below rather than by a minimum.
+  const available = Math.max(24, (columns || termWidth()) - indent.length);
+  const labelWidth = Math.min(12, Math.max(...rows.map((r) => width(r.label ?? '')), 0));
+  // indent(2) + gap(2) + label + gap(2) + value + right border(2)
+  const valueRoom = Math.max(8, available - 2 - labelWidth - 2 - 2);
+  const body = rows.map((r) => (r.hint
+    ? '  ' + ' '.repeat(labelWidth + 2) + paint(fit(r.hint, valueRoom), 'hint')
+    : '  ' + paint(fit(r.label ?? '', labelWidth).padEnd(labelWidth), 'label') + '  ' + fit(r.value ?? '', valueRoom)));
+
+  // Frame width = whatever the body needs, capped to what the terminal has.
+  const wanted = Math.max(...body.map(width), 12);
+  const inner = Math.max(8, Math.min(available - 2, wanted));
+  const shownTitle = fit(title, Math.max(2, inner - 4));
+  const top = paint('┌─ ', 'frame') + paint(shownTitle, 'title')
+    + ' ' + paint('─'.repeat(Math.max(0, inner - shownTitle.length - 3)) + '┐', 'frame');
+  const bottom = paint('└' + '─'.repeat(inner) + '┘', 'frame');
+  return [top, ...body, bottom].map((line) => indent + line).join('\n');
+}
+
+// A one-line note rendered in the panel's muted voice.
+export const hint = (text) => ({ hint: text });
+
+// A label/value row. Values are stringified here so a caller can pass a number.
+export const row = (label, value) => ({ label, value: String(value) });