ompchamber 0.3.0

package/src/cli/lib/args.js

@@ -0,0 +1,233 @@
+/**
+ * Command-line argument parsing for the OMPChamber CLI.
+ *
+ * Pure and side-effect free: it never throws, never exits and never writes
+ * to a stream. Callers decide how to react to `unknown` flags.
+ */
+
+const BOOLEAN_LONG = new Set([
+  'lan',
+  'prod',
+  'foreground',
+  'no-daemon',
+  'all',
+  'follow',
+  'check',
+  'force',
+  'no-restart',
+  'json',
+  'quiet',
+  'help',
+  'version',
+]);
+
+// Flags that set another option to a non-`true` value.
+const NEGATED_LONG = {
+  'no-daemon': { key: 'foreground', value: true },
+  'no-restart': { key: 'restart', value: false },
+};
+
+const VALUE_LONG = new Set(['port', 'host', 'hostname', 'lines']);
+
+const SHORT_TO_LONG = {
+  p: 'port',
+  n: 'lines',
+  f: 'follow',
+  c: 'check',
+  q: 'quiet',
+  h: 'help',
+  v: 'version',
+};
+
+const SHORT_VALUE = new Set(['p', 'n']);
+
+function toNumberOrNull(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return null;
+  }
+  const parsed = Number(value.trim());
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function takeValue(tokens, index, inline) {
+  if (typeof inline === 'string' && inline.length > 0) {
+    return { value: inline, nextIndex: index };
+  }
+  const candidate = tokens[index + 1];
+  if (typeof candidate === 'string' && !candidate.startsWith('-')) {
+    return { value: candidate, nextIndex: index + 1 };
+  }
+  return { value: undefined, nextIndex: index };
+}
+
+/**
+ * Parse `process.argv.slice(2)` into a command, positionals and options.
+ */
+export function parseArgs(argv) {
+  const tokens = Array.isArray(argv) ? argv.slice() : [];
+  const options = {
+    port: null,
+    host: null,
+    lan: false,
+    prod: false,
+    foreground: false,
+    all: false,
+    follow: false,
+    check: false,
+    force: false,
+    restart: true,
+    lines: null,
+    json: false,
+    quiet: false,
+    help: false,
+    version: false,
+  };
+  const unknown = [];
+  const nonFlags = [];
+
+  const applyLong = (name, inline, index) => {
+    if (name === 'port') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.port = toNumberOrNull(value);
+      return nextIndex;
+    }
+    if (name === 'lines') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.lines = toNumberOrNull(value);
+      return nextIndex;
+    }
+    if (name === 'host' || name === 'hostname') {
+      const { value, nextIndex } = takeValue(tokens, index, inline);
+      options.host = typeof value === 'string' ? value : null;
+      return nextIndex;
+    }
+    const negated = NEGATED_LONG[name];
+    if (negated) {
+      options[negated.key] = negated.value;
+      return index;
+    }
+    if (BOOLEAN_LONG.has(name)) {
+      options[name] = true;
+      return index;
+    }
+    unknown.push(`--${name}`);
+    return index;
+  };
+
+  for (let i = 0; i < tokens.length; i += 1) {
+    const arg = tokens[i];
+
+    if (typeof arg !== 'string') {
+      continue;
+    }
+
+    if (arg === '--') {
+      for (let j = i + 1; j < tokens.length; j += 1) {
+        nonFlags.push(tokens[j]);
+      }
+      break;
+    }
+
+    if (!arg.startsWith('-') || arg === '-') {
+      nonFlags.push(arg);
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      const name = eq >= 0 ? arg.slice(2, eq) : arg.slice(2);
+      const inline = eq >= 0 ? arg.slice(eq + 1) : undefined;
+      i = applyLong(name, inline, i);
+      continue;
+    }
+
+    const body = arg.slice(1);
+    const shortName = body[0];
+    const attached = body.length > 1 ? body.slice(1) : undefined;
+    const longName = SHORT_TO_LONG[shortName];
+
+    if (!longName) {
+      unknown.push(arg);
+      continue;
+    }
+
+    if (SHORT_VALUE.has(shortName)) {
+      const { value, nextIndex } = takeValue(tokens, i, attached);
+      if (longName === 'port') {
+        options.port = toNumberOrNull(value);
+      } else {
+        options.lines = toNumberOrNull(value);
+      }
+      i = nextIndex;
+      continue;
+    }
+
+    if (attached !== undefined) {
+      unknown.push(arg);
+      continue;
+    }
+
+    options[longName] = true;
+  }
+
+  const command = nonFlags.length > 0 ? nonFlags[0] : null;
+  const positionals = nonFlags.slice(1);
+
+  return { command, positionals, options, unknown };
+}
+
+/**
+ * Full multi-line help text. Returned (not printed) so the caller owns output.
+ */
+export function helpText() {
+  return `OMPChamber - Developer web console and diagnostic chamber for AI Oh-My-Pi
+
+USAGE:
+  ompchamber [COMMAND] [OPTIONS]
+
+COMMANDS:
+  serve          Start the OMPChamber web server (default when no command is given)
+  update         Update OMPChamber to the latest GitHub release
+  stop           Stop the running OMPChamber instance
+  restart        Stop and then start the server again
+  status         Show the status of the running instance
+  logs           Print or follow the server log output
+
+OPTIONS:
+  -p, --port <port>       Web server port (default: 3000)
+  --host <address>        Bind address (default: 127.0.0.1)
+  --hostname <address>    Alias for --host
+  --lan                   Bind to 0.0.0.0 for LAN access
+  --prod                  Run the production build instead of the dev server
+  --foreground            Run the server in the foreground (no daemon)
+  --no-daemon             Alias for --foreground
+  --all                   Apply the command to every running instance
+  -c, --check             Report whether a newer release exists without installing it
+  --force                 Reinstall even when already up to date
+  --no-restart            Do not restart a running instance after updating
+  -f, --follow            Follow log output as it is written
+  -n, --lines <count>     Number of log lines to print
+  --json                  Emit machine-readable JSON output
+  -q, --quiet             Suppress non-essential output
+  -h, --help              Show this help
+  -v, --version           Show the version
+
+ENVIRONMENT:
+  OMPCHAMBER_DATA_DIR     Override the data directory (default: ~/.ompchamber)
+  OMPCHAMBER_PORT         Default web server port
+  OMPCHAMBER_HOST         Default bind address
+  GITHUB_TOKEN            Raise the GitHub API rate limit for update checks
+
+EXAMPLES:
+  ompchamber                       # Start the server on the default port
+  ompchamber serve --port 8080     # Start on port 8080
+  ompchamber serve --lan           # Start and expose the server on the LAN
+  ompchamber serve --prod          # Serve the production build
+  ompchamber update --check        # Is a newer release available?
+  ompchamber update                # Update, then restart a running instance
+  ompchamber stop                  # Stop the running instance
+  ompchamber restart               # Restart the server
+  ompchamber status                # Show whether the server is running
+  ompchamber logs -f -n 200        # Follow the last 200 log lines
+`;
+}

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

@@ -0,0 +1,108 @@
+// `ompchamber logs` — print or follow the server log file.
+
+import { findLiveInstance } from '@/cli/lib/runtime.js';
+import { getLogFilePath } from '@/cli/lib/paths.js';
+import { log, printJson, fail, isJson, isQuiet } from '@/cli/lib/output.js';
+const DEFAULT_LINES = 50;
+const FOLLOW_INTERVAL_MS = 300;
+
+function resolvePort(options) {
+  const raw = options?.port;
+  if (raw !== null && raw !== undefined) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const env = Bun.env.OMPCHAMBER_PORT;
+  if (typeof env === 'string' && env.trim().length > 0) {
+    const parsed = Number(env.trim());
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 3000;
+}
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function splitLines(content) {
+  const lines = content.split('\n');
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+function writeLines(lines) {
+  for (const line of lines) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function followFile(filePath, initialCount) {
+  const initial = await Bun.file(filePath).text();
+  writeLines(splitLines(initial).slice(-initialCount));
+
+  let position = Buffer.byteLength(initial, 'utf8');
+  let running = true;
+  const stop = () => { running = false; };
+
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    while (running) {
+      await sleep(FOLLOW_INTERVAL_MS);
+
+      let size;
+      try {
+        size = (await Bun.file(filePath).stat()).size;
+      } catch {
+        continue;
+      }
+      if (size < position) position = 0;
+      if (size === position) continue;
+
+      const chunk = await Bun.file(filePath).slice(position, size).text();
+      position = size;
+      process.stdout.write(chunk);
+    }
+  } finally {
+    process.removeListener('SIGINT', stop);
+    process.removeListener('SIGTERM', stop);
+  }
+}
+
+export async function run(options) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const requested = explicitPort(options);
+  const live = await findLiveInstance(requested);
+  const logFile = live?.logFile ?? getLogFilePath(requested ?? resolvePort(options));
+
+  if (!(await Bun.file(logFile).exists())) {
+    fail(`No log file found at ${logFile}.\nStart the server first with \`ompchamber serve\`.`);
+  }
+
+  const requestedLines = Number(options?.lines);
+  const lineCount = Number.isFinite(requestedLines) && requestedLines > 0
+    ? Math.trunc(requestedLines)
+    : DEFAULT_LINES;
+
+  if (json) {
+    printJson({ logFile, lines: splitLines(await Bun.file(logFile).text()).slice(-lineCount) });
+    return;
+  }
+
+  if (!quiet) log(`Log file: ${logFile}`);
+
+  if (options?.follow) {
+    await followFile(logFile, lineCount);
+    return;
+  }
+
+  writeLines(splitLines(await Bun.file(logFile).text()).slice(-lineCount));
+}

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

@@ -0,0 +1,28 @@
+// `ompchamber restart` — stop the live instance (if any), then serve again.
+
+import { findLiveInstance, stopInstance } from '@/cli/lib/runtime.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { log, isJson, isQuiet } from '@/cli/lib/output.js';
+import { run as runServe } from '@/cli/lib/commands/serve.js';
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export async function run(options, ctx) {
+  const json = isJson();
+  const quiet = isQuiet();
+  const live = await findLiveInstance(explicitPort(options));
+
+  if (live) {
+    if (!json && !quiet) {
+      log(`Stopping OMPChamber on port ${live.port} (pid ${live.pid})...`);
+    }
+    await stopInstance(live, { timeoutMs: STOP_TIMEOUT_MS });
+  }
+
+  return runServe(options, ctx);
+}

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

@@ -0,0 +1,109 @@
+// `ompchamber serve` — start the Remix dev or production server.
+
+import { joinPath } from '@/cli/lib/path-utils.js';
+import {
+  spawnDetachedServer,
+  buildServeInvocation,
+  waitForHealth,
+  findLiveInstance,
+  probeHost,
+} from '@/cli/lib/runtime.js';
+import { log, ok, warn, fail, printJson, isJson, isQuiet } from '@/cli/lib/output.js';
+import { wireChildProcessLifecycle } from '@/cli/lib/process-lifecycle.js';
+
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOST = '127.0.0.1';
+
+export function resolvePort(options) {
+  const raw = options?.port;
+  if (raw !== null && raw !== undefined) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const env = Bun.env.OMPCHAMBER_PORT;
+  if (typeof env === 'string' && env.trim().length > 0) {
+    const parsed = Number(env.trim());
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return DEFAULT_PORT;
+}
+
+export function resolveHost(options) {
+  if (options?.lan) return '0.0.0.0';
+  const raw = options?.host;
+  if (typeof raw === 'string' && raw.length > 0) return raw;
+  const env = Bun.env.OMPCHAMBER_HOST;
+  if (typeof env === 'string' && env.length > 0) return env;
+  return DEFAULT_HOST;
+}
+
+export async function run(options, ctx) {
+  const port = resolvePort(options);
+  const host = resolveHost(options);
+  const mode = options?.prod ? 'prod' : 'dev';
+  const json = isJson();
+  const quiet = isQuiet();
+  const pkgRoot = ctx?.pkgRoot ?? process.cwd();
+
+  if (mode === 'prod') {
+    const serverEntry = joinPath(pkgRoot, 'dist', 'client', 'index.html');
+    // Bun.file().exists() is file-only (false for directories) — correct here,
+    // where the target is always a regular file. For directory guards use
+    // pathExists() in src/server/lib/omp/core/paths.ts.
+    if (!(await Bun.file(serverEntry).exists())) {
+      fail(`Production build not found at ${serverEntry}.\nRun \`bun run build\` first, then retry with --prod.`);
+    }
+  }
+
+  const existing = await findLiveInstance(port);
+  if (existing) {
+    fail(`An OMPChamber instance is already running on port ${port} (pid ${existing.pid}).\nUse \`ompchamber restart\` or a different \`--port\`.`);
+  }
+
+  if (options?.foreground) {
+    return runForeground({ pkgRoot, mode, port, host, quiet });
+  }
+
+  const { entry } = spawnDetachedServer({ pkgRoot, mode, port, host });
+
+  if (!quiet && !json) {
+    log(`Starting OMPChamber (${mode}) on ${entry.url} (pid ${entry.pid})...`);
+  }
+
+  const health = await waitForHealth(port, host);
+
+  if (json) {
+    printJson(entry);
+    return;
+  }
+
+  if (!health) {
+    warn(`Server started (pid ${entry.pid}) but the health check did not pass.\nCheck logs: ${entry.logFile}`);
+    return;
+  }
+
+  ok(`OMPChamber ${mode} server ready`);
+  log(`  url:   ${entry.url}`);
+  log(`  pid:   ${entry.pid}`);
+  log(`  logs:  ${entry.logFile}`);
+}
+
+function runForeground({ pkgRoot, mode, port, host, quiet }) {
+  const { file, args, env } = buildServeInvocation({ pkgRoot, mode, port, host });
+  const url = `http://${probeHost(host)}:${port}`;
+  if (!quiet) {
+    log(`Running OMPChamber (${mode}) in the foreground on ${url} (Ctrl+C to stop)...`);
+  }
+  const child = Bun.spawn({
+    cmd: [file, ...args],
+    cwd: pkgRoot,
+    stdin: 'inherit',
+    stdout: 'inherit',
+    stderr: 'inherit',
+    env,
+  });
+  wireChildProcessLifecycle(child, process, 5000);
+  return new Promise((resolve) => {
+    void child.exited.then(resolve);
+  });
+}

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

@@ -0,0 +1,63 @@
+// `ompchamber status` — report the live instance, its health and log path.
+
+import { findLiveInstance, waitForHealth, probeHost } from '@/cli/lib/runtime.js';
+import { log, ok, printJson, isJson } from '@/cli/lib/output.js';
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function formatUptime(startedAt) {
+  const started = Date.parse(startedAt);
+  if (!Number.isFinite(started)) return 'unknown';
+  let seconds = Math.max(0, Math.floor((Date.now() - started) / 1000));
+  const hours = Math.floor(seconds / 3600);
+  seconds -= hours * 3600;
+  const minutes = Math.floor(seconds / 60);
+  seconds -= minutes * 60;
+  if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
+  if (minutes > 0) return `${minutes}m ${seconds}s`;
+  return `${seconds}s`;
+}
+
+function formatHealth(health) {
+  if (!health) return 'unreachable';
+  const version = health.version ?? 'unknown';
+  const mock = health.mock ? ', mock' : '';
+  return `ok (version ${version}${mock})`;
+}
+
+export async function run(options) {
+  const json = isJson();
+  const live = await findLiveInstance(explicitPort(options));
+
+  if (!live) {
+    if (json) {
+      printJson({ running: false });
+      return;
+    }
+    log('OMPChamber is not running.');
+    return;
+  }
+
+  const health = await waitForHealth(live.port, live.host, 4000);
+  const merged = { ...live, running: true, health };
+
+  if (json) {
+    printJson(merged);
+    return;
+  }
+
+  ok('OMPChamber is running');
+  log(`  instance: ${live.port}`);
+  log(`  pid:      ${live.pid}`);
+  log(`  port:     ${live.port}`);
+  log(`  url:      ${live.url ?? `http://${probeHost(live.host)}:${live.port}`}`);
+  log(`  mode:     ${live.mode ?? 'unknown'}`);
+  log(`  uptime:   ${formatUptime(live.startedAt)}`);
+  log(`  health:   ${formatHealth(health)}`);
+  log(`  log:      ${live.logFile}`);
+}

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

@@ -0,0 +1,63 @@
+// `ompchamber stop` — stop one or every live OMPChamber instance.
+
+import { listRegistries, findLiveInstance, isProcessAlive, stopInstance } from '@/cli/lib/runtime.js';
+import { STOP_TIMEOUT_MS } from '@/cli/lib/process-lifecycle.js';
+import { ok, warn, printJson, isJson } from '@/cli/lib/output.js';
+
+function resolvePort(options) {
+  const raw = options?.port;
+  if (raw !== null && raw !== undefined) {
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  const env = Bun.env.OMPCHAMBER_PORT;
+  if (typeof env === 'string' && env.trim().length > 0) {
+    const parsed = Number(env.trim());
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return 3000;
+}
+
+function explicitPort(options) {
+  const raw = options?.port;
+  if (raw === null || raw === undefined) return null;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+export async function run(options) {
+  const json = isJson();
+
+  let targets;
+  if (options?.all) {
+    targets = (await listRegistries()).filter((entry) => entry && isProcessAlive(Number(entry.pid)));
+  } else {
+    const live = await findLiveInstance(explicitPort(options));
+    targets = live ? [live] : [];
+  }
+
+  if (targets.length === 0) {
+    if (json) {
+      printJson({ stopped: [] });
+      return;
+    }
+    warn(options?.all
+      ? 'No running OMPChamber instances found.'
+      : `No running OMPChamber instance on port ${explicitPort(options) ?? resolvePort(options)}.`);
+    return;
+  }
+
+  const stopped = [];
+  for (const entry of targets) {
+    const gone = await stopInstance(entry, { timeoutMs: STOP_TIMEOUT_MS });
+    stopped.push({ port: entry.port, pid: entry.pid, stopped: gone });
+    if (json) continue;
+    if (gone) {
+      ok(`Stopped OMPChamber on port ${entry.port} (pid ${entry.pid}).`);
+    } else {
+      warn(`OMPChamber on port ${entry.port} (pid ${entry.pid}) did not exit cleanly.`);
+    }
+  }
+
+  if (json) printJson({ stopped });
+}