ompchamber 0.3.0

package/src/cli/lib/commands/update.js

@@ -0,0 +1,120 @@
+// `ompchamber update` — replace this install with the latest GitHub release.
+//
+// The installation mechanics live in the shared update engine so the CLI and
+// the console's "Update" button do the same thing; this command owns the
+// terminal presentation and restarts any instance still serving the previous
+// build.
+
+import { color, configure, error, log, ok, warn, printJson, isJson, isQuiet } from '@/cli/lib/output.js';
+import { listRegistries, findLiveInstance, isProcessAlive, stopInstance } from '@/cli/lib/runtime.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { run as runServe } from '@/cli/lib/commands/serve.js';
+import { resolveInstallContext, resolveOmpChamberVersion, updateOmpChamber } from '@/server/lib/updates/install';
+
+/**
+ * Live instances to restart after an update: every one with `--all`, otherwise
+ * the first. Their recorded port/host/mode is reused, so a server started on a
+ * non-default port comes back on that same port.
+ */
+async function liveInstances(options) {
+  if (options?.all) {
+    const entries = await listRegistries();
+    return entries.filter((entry) => entry && isProcessAlive(Number(entry.pid)));
+  }
+  const live = await findLiveInstance(null);
+  return live ? [live] : [];
+}
+
+async function restartInstances(options, ctx) {
+  const restarted = [];
+  for (const entry of await liveInstances(options)) {
+    log(`Restarting OMPChamber on port ${entry.port} (pid ${entry.pid})...`);
+    await stopInstance(entry, { timeoutMs: STOP_TIMEOUT_MS });
+    await runServe(
+      {
+        ...options,
+        port: entry.port,
+        host: entry.host,
+        lan: entry.host === '0.0.0.0',
+        prod: entry.mode === 'prod',
+        foreground: false,
+        all: false,
+      },
+      ctx,
+    );
+    restarted.push(entry.port);
+  }
+  return restarted;
+}
+
+async function runCheck(pkgRoot, json) {
+  const info = await resolveOmpChamberVersion(pkgRoot);
+  const context = resolveInstallContext(pkgRoot);
+
+  if (json) {
+    printJson({
+      current: info.current,
+      latest: info.latest,
+      updateAvailable: info.updateAvailable,
+      installed: true,
+      method: context.method,
+      reason: context.reason,
+      error: info.error,
+      releaseUrl: info.release?.url ?? null,
+    });
+  } else {
+    log(`Current version: ${info.current ?? 'unknown'}`);
+    if (info.updateAvailable) {
+      log(color.yellow(`New version available: ${info.latest}`));
+    } else if (!info.error) {
+      ok('Already up to date');
+    }
+    if (info.error) warn(info.error);
+  }
+
+  if (info.error) process.exitCode = 1;
+}
+
+export async function run(options, ctx) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const pkgRoot = ctx?.pkgRoot ?? process.cwd();
+  const force = Boolean(options?.force);
+  const shouldRestart = options?.restart !== false;
+  const onStage = quiet || json ? undefined : (label) => process.stdout.write(`${color.dim(`\u203a ${label}...`)}\n`);
+  const onLine = quiet || json ? undefined : (chunk) => process.stdout.write(chunk);
+
+  if (options?.check) {
+    return runCheck(pkgRoot, json);
+  }
+
+  const result = await updateOmpChamber({ force, pkgRoot, onStage, onLine });
+
+  if (json) {
+    // Restarting prints through the serve command; silence it so stdout stays
+    // one JSON document.
+    if (result.success && result.updated && shouldRestart) configure({ json: false, quiet: true });
+    const restarted = result.success && result.updated && shouldRestart ? await restartInstances(options, ctx) : [];
+    printJson({ ...result, restarted });
+    if (!result.success) process.exitCode = 1;
+    return;
+  }
+
+  if (!result.success) {
+    (result.manual ? warn : error)(result.message);
+    process.exitCode = 1;
+    return;
+  }
+
+  ok(result.message);
+  if (!result.updated) return;
+
+  if (!shouldRestart) {
+    log('Restart the server to apply it: `ompchamber restart`.');
+    return;
+  }
+
+  if ((await restartInstances(options, ctx)).length === 0) {
+    log('No running instance to restart.');
+  }
+}

package/src/cli/lib/output.js

@@ -0,0 +1,136 @@
+const state = {
+  json: false,
+  quiet: false,
+};
+
+/**
+ * Store module-level output flags for the current process.
+ */
+export function configure({ json = false, quiet = false } = {}) {
+  state.json = Boolean(json);
+  state.quiet = Boolean(quiet);
+}
+
+export function isQuiet() {
+  return state.quiet;
+}
+
+export function isJson() {
+  return state.json;
+}
+
+function colorsEnabled() {
+  return Bun.enableANSIColors;
+}
+
+function paint(open, close, text) {
+  const value = String(text);
+  if (!colorsEnabled()) {
+    return value;
+  }
+  return `\u001b[${open}m${value}\u001b[${close}m`;
+}
+
+/**
+ * ANSI helpers. Every entry is `(text) => string` and degrades to a plain
+ * pass-through when Bun reports ANSI colors unsupported (non-TTY stdout,
+ * NO_COLOR set, or FORCE_COLOR=0).
+ */
+export const color = {
+  red: (text) => paint(31, 39, text),
+  green: (text) => paint(32, 39, text),
+  yellow: (text) => paint(33, 39, text),
+  dim: (text) => paint(2, 22, text),
+  bold: (text) => paint(1, 22, text),
+};
+
+/**
+ * Write a line to stdout unless quiet mode is active.
+ */
+export function log(message) {
+  if (state.quiet) {
+    return;
+  }
+  process.stdout.write(`${message}\n`);
+}
+
+/**
+ * Write a success line (green check prefix) to stdout unless quiet.
+ */
+export function ok(message) {
+  if (state.quiet) {
+    return;
+  }
+  process.stdout.write(`${color.green('\u2713')} ${message}\n`);
+}
+
+/**
+ * Write a warning line to stderr. Never suppressed.
+ */
+export function warn(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write an error line to stderr. Never suppressed.
+ */
+export function error(message) {
+  process.stderr.write(`${message}\n`);
+}
+
+/**
+ * Write a pretty-printed JSON document to stdout.
+ */
+export function printJson(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+/**
+ * Report a fatal error and terminate with the given exit code.
+ */
+export function fail(message, code = 1) {
+  error(message);
+  process.exit(code);
+}
+
+/**
+ * Render a simple padded plain-text table for human output.
+ */
+export function formatTable(rows, headers = []) {
+  const body = Array.isArray(rows) ? rows.map((row) => (Array.isArray(row) ? row : [row])) : [];
+  const head = Array.isArray(headers) ? headers : [];
+  const columns = Math.max(head.length, ...body.map((row) => row.length), 0);
+
+  if (columns === 0) {
+    return '';
+  }
+
+  const widths = [];
+  for (let i = 0; i < columns; i += 1) {
+    const headerWidth = head[i] === undefined ? 0 : String(head[i]).length;
+    const cellWidth = body.reduce((max, row) => {
+      const cell = row[i] === undefined || row[i] === null ? '' : String(row[i]);
+      return Math.max(max, cell.length);
+    }, 0);
+    widths[i] = Math.max(headerWidth, cellWidth);
+  }
+
+  const renderRow = (row) =>
+    widths
+      .map((width, i) => {
+        const cell = row[i] === undefined || row[i] === null ? '' : String(row[i]);
+        return cell.padEnd(width);
+      })
+      .join('  ')
+      .trimEnd();
+
+  const lines = [];
+  if (head.length > 0) {
+    lines.push(renderRow(head));
+    lines.push(widths.map((width) => '-'.repeat(width)).join('  '));
+  }
+  for (const row of body) {
+    lines.push(renderRow(row));
+  }
+  return lines.join('\n');
+}

package/src/cli/lib/path-utils.js

@@ -0,0 +1,48 @@
+// Minimal path helpers for the CLI — Bun has no path builtin (Bun.path is
+// undefined), and the CLI only needs POSIX-style join/resolve/dirname on
+// absolute native paths.
+
+import { homedir } from 'node:os';
+
+/** Join path segments with the platform separator without duplicated separators. */
+export function joinPath(...segments) {
+  let joined = '';
+  for (const segment of segments) {
+    if (!segment) continue;
+    if (!joined) {
+      joined = segment;
+    } else if (joined.endsWith('/') || segment.startsWith('/')) {
+      joined = `${joined.replace(/\/+$/, '')}/${segment.replace(/^\/+/, '')}`;
+    } else {
+      joined = `${joined}/${segment}`;
+    }
+  }
+  return joined;
+}
+
+/** Resolve a path to an absolute normalized path. */
+export function resolvePath(...segments) {
+  const joined = joinPath(...segments);
+  if (joined.startsWith('/')) {
+    return joined.replace(/\/{2,}/g, '/').replace(/(.+)\/$/, '$1');
+  }
+  return joinPath(process.cwd(), joined).replace(/\/{2,}/g, '/').replace(/(.+)\/$/, '$1');
+}
+
+/** Directory portion of an absolute path ('/' for the root). */
+export function dirnameOf(value) {
+  const index = value.lastIndexOf('/');
+  if (index <= 0) return '/';
+  return value.slice(0, index);
+}
+
+/**
+ * Current user home directory. Uses `os.homedir()` rather than `Bun.env.HOME`
+ * because the env var is absent when the CLI runs without a shell (cron,
+ * launchd, GUI launcher) — there it would yield '' and make every derived data
+ * path relative to the cwd, so `stop`/`status` would look in the wrong place.
+ * `os.homedir()` falls back to getpwuid on POSIX and USERPROFILE on Windows.
+ */
+export function homeDir() {
+  return homedir();
+}

package/src/cli/lib/path-utils.test.js

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { homedir } from 'node:os';
+
+import { dirnameOf, homeDir, joinPath, resolvePath } from '@/cli/lib/path-utils.js';
+
+describe('homeDir', () => {
+  // The CLI must resolve the same data directory as the server (which uses
+  // os.homedir()). Reading Bun.env.HOME yields '' without a shell (cron,
+  // launchd, GUI launcher), which silently made every derived path relative to
+  // the cwd — `stop`/`status` then missed the running instance.
+  test('is absolute even when HOME is absent from the environment', () => {
+    const saved = Bun.env.HOME;
+    try {
+      delete Bun.env.HOME;
+      expect(homeDir()).toBe(homedir());
+      expect(homeDir().startsWith('/')).toBe(true);
+    } finally {
+      if (saved !== undefined) Bun.env.HOME = saved;
+    }
+  });
+
+  test('agrees with os.homedir()', () => {
+    expect(homeDir()).toBe(homedir());
+  });
+});
+
+describe('joinPath', () => {
+  test('keeps a single separator between segments', () => {
+    expect(joinPath('/a', 'b', 'c')).toBe('/a/b/c');
+    expect(joinPath('/a/', '/b')).toBe('/a/b');
+    expect(joinPath('/a//', '//b')).toBe('/a/b');
+  });
+
+  test('skips empty segments', () => {
+    expect(joinPath('/a', '', 'b')).toBe('/a/b');
+  });
+});
+
+describe('resolvePath', () => {
+  test('returns an absolute path for an absolute input', () => {
+    expect(resolvePath('/tmp/x')).toBe('/tmp/x');
+    expect(resolvePath('/tmp/x/')).toBe('/tmp/x');
+  });
+
+  test('resolves relative input against the cwd', () => {
+    expect(resolvePath('rel/dir')).toBe(joinPath(process.cwd(), 'rel/dir'));
+  });
+
+  test('the data dir derived from homeDir is always absolute', () => {
+    const saved = Bun.env.HOME;
+    try {
+      delete Bun.env.HOME;
+      expect(joinPath(homeDir(), '.ompchamber').startsWith('/')).toBe(true);
+    } finally {
+      if (saved !== undefined) Bun.env.HOME = saved;
+    }
+  });
+});
+
+describe('dirnameOf', () => {
+  test('returns the parent of an absolute path', () => {
+    expect(dirnameOf('/a/b/c')).toBe('/a/b');
+    expect(dirnameOf('/a')).toBe('/');
+    expect(dirnameOf('/')).toBe('/');
+  });
+});

package/src/cli/lib/paths.js

@@ -0,0 +1,60 @@
+import fs from 'node:fs';
+import { joinPath, resolvePath, homeDir } from '@/cli/lib/path-utils.js';
+
+/**
+ * Resolve the OMPChamber data directory.
+ *
+ * Matches the convention used by app/db.server.ts so the CLI and the web
+ * console always agree on where state lives.
+ */
+export function getDataDir() {
+  const override = Bun.env.OMPCHAMBER_DATA_DIR;
+  if (typeof override === 'string' && override.trim().length > 0) {
+    return resolvePath(override.trim());
+  }
+  return joinPath(homeDir(), '.ompchamber');
+}
+
+/**
+ * Directory holding per-instance registry files (`<port>.json`).
+ * Created on demand with owner-only permissions.
+ */
+export function getRunDir() {
+  const dir = joinPath(getDataDir(), 'run');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return dir;
+}
+
+/**
+ * Directory holding per-instance log files.
+ */
+export function getLogsDir() {
+  const dir = joinPath(getDataDir(), 'logs');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/**
+ * Registry file describing the running instance bound to `port`.
+ */
+export function getRegistryPath(port) {
+  return joinPath(getRunDir(), `${port}.json`);
+}
+
+/**
+ * Log file for the running instance bound to `port`.
+ */
+export function getLogFilePath(port) {
+  return joinPath(getLogsDir(), `ompchamber-${port}.log`);
+}
+
+/**
+ * Ensure the full data directory tree exists and return every path.
+ */
+export function ensureDataDirs() {
+  return {
+    dataDir: getDataDir(),
+    runDir: getRunDir(),
+    logsDir: getLogsDir(),
+  };
+}

package/src/cli/lib/process-lifecycle.js

@@ -0,0 +1,110 @@
+// ESM port of ompweb/bin/process-lifecycle.js.
+// Semantics are preserved exactly: POSIX signals the whole process group
+// (`process.kill(-pid, signal)`) with a `child.kill(signal)` fallback, while
+// win32 shells out to `taskkill /pid <pid> /t [/f]`.
+
+const forwardedSignals = ['SIGINT', 'SIGTERM'];
+const shutdownTimeoutMs = 5_000;
+
+// Time to wait for a terminated process tree to actually exit.
+export const STOP_TIMEOUT_MS = 5_000;
+
+// Signal numbers for the 128+N shell exit-code convention (os.constants.signals
+// equivalent; only signals forwarded by this module are needed).
+const SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGKILL: 9 };
+
+function getSignalExitCode(signal) {
+  const signalNumber = signal ? SIGNAL_NUMBERS[signal] : undefined;
+  return typeof signalNumber === 'number' ? 128 + signalNumber : 1;
+}
+
+export function killChildTree(child, force, platform = process.platform, gracefulSignal = 'SIGTERM') {
+  if (platform === 'win32' && child.pid) {
+    const reaper = Bun.spawn({
+      cmd: ['taskkill', '/pid', String(child.pid), '/t', ...(force ? ['/f'] : [])],
+      stdout: 'ignore',
+      stderr: 'ignore',
+      windowsHide: true,
+    });
+    const fallback = () => {
+      try { child.kill(force ? 'SIGKILL' : 'SIGTERM'); } catch {}
+    };
+    void reaper.exited.then((code) => {
+      if (code !== 0) fallback();
+    }, fallback);
+    reaper.unref?.();
+    return;
+  }
+
+  const signal = force ? 'SIGKILL' : gracefulSignal;
+  if (platform !== 'win32' && child.pid) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {}
+  }
+
+  try { child.kill(signal); } catch {}
+}
+
+function childHasExited(child) {
+  return (child.exitCode !== null && child.exitCode !== undefined)
+    || (child.signalCode !== null && child.signalCode !== undefined);
+}
+
+function waitForChildExit(child, timeoutMs) {
+  if (childHasExited(child)) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const finish = (exited) => {
+      clearTimeout(timer);
+      resolve(exited);
+    };
+    const timer = setTimeout(() => finish(childHasExited(child)), timeoutMs);
+    timer.unref?.();
+    void child.exited.then(() => finish(true));
+  });
+}
+
+export async function terminateChildProcess(child, timeoutMs = STOP_TIMEOUT_MS, platform = process.platform) {
+  if (childHasExited(child)) return true;
+  const exited = waitForChildExit(child, timeoutMs);
+  killChildTree(child, true, platform);
+  return exited;
+}
+
+export function wireChildProcessLifecycle(child, parentProcess = process, timeoutMs = shutdownTimeoutMs, handleChildExit) {
+  const signalHandlers = new Map();
+  let shutdownTimer;
+  let settled = false;
+  const platform = parentProcess.platform ?? process.platform;
+
+  const forceKill = () => killChildTree(child, true, platform);
+
+  for (const signal of forwardedSignals) {
+    const handler = () => {
+      if (shutdownTimer) {
+        forceKill();
+        return;
+      }
+
+      shutdownTimer = setTimeout(forceKill, timeoutMs);
+      shutdownTimer.unref?.();
+      killChildTree(child, false, platform, signal);
+    };
+    signalHandlers.set(signal, handler);
+    parentProcess.on(signal, handler);
+  }
+
+  void child.exited.then((code) => {
+    if (settled) return;
+    settled = true;
+    if (shutdownTimer) clearTimeout(shutdownTimer);
+
+    for (const [forwardedSignal, handler] of signalHandlers) {
+      parentProcess.removeListener(forwardedSignal, handler);
+    }
+    if (handleChildExit?.({ code, signal: child.signalCode }) === true) return;
+
+    parentProcess.exit(code ?? getSignalExitCode(child.signalCode));
+  });
+}