@oar-sh/oar 0.9.0

package/bin/oar.js

@@ -0,0 +1,665 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { randomUUID } from 'crypto';
+import { EventEmitter } from 'events';
+import { fileURLToPath, pathToFileURL } from 'url';
+import { spawn } from 'child_process';
+
+import {
+  migrateStateToOarRoot,
+  resolveOarRoot,
+} from '../server/services/oar-state-migration-service.mjs';
+
+function resolvePackageRoot(metaUrl = import.meta.url) {
+  return path.resolve(path.dirname(fileURLToPath(metaUrl)), '..');
+}
+
+function parsePort(argv = []) {
+  const args = Array.isArray(argv) ? argv : [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = String(args[index] || '');
+    if (arg === '--port' && args[index + 1]) {
+      const parsed = Number.parseInt(String(args[index + 1]), 10);
+      if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) return parsed;
+    }
+    if (arg.startsWith('--port=')) {
+      const parsed = Number.parseInt(arg.slice('--port='.length), 10);
+      if (Number.isInteger(parsed) && parsed > 0 && parsed <= 65535) return parsed;
+    }
+  }
+  return 3333;
+}
+
+function readRelayLock(lockPath) {
+  try {
+    const raw = fs.readFileSync(lockPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      pid: Number.parseInt(String(parsed?.pid ?? ''), 10),
+      startedAt: typeof parsed?.startedAt === 'string' ? parsed.startedAt : null,
+      token: typeof parsed?.token === 'string' ? parsed.token : '',
+    };
+  } catch {
+    return null;
+  }
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readJsonFile(filePath) {
+  if (!filePath) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function openAppendFileDescriptor(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  return fs.openSync(filePath, 'a');
+}
+
+// Pre-OAR managed config location — kept only as a migration source and as the
+// config home for git checkouts, where nothing may change underfoot.
+function getLegacyManagedConfigDir(env = process.env) {
+  if (process.platform === 'win32') {
+    return path.join(
+      env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
+      'copilot-remote',
+    );
+  }
+  return path.join(
+    env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'),
+    'copilot-remote',
+  );
+}
+
+function isGitCheckout(packageRoot) {
+  try { return fs.existsSync(path.join(packageRoot, '.git')); } catch { return false; }
+}
+
+/**
+ * Where launcher-managed state lives. A git checkout keeps every pre-OAR
+ * default (repo-local server/data, legacy managed config) so development and
+ * the two existing machines change nothing. A global install gets the OAR
+ * state root: config, data, logs all under ~/.oar (APPDATA\oar on Windows),
+ * which survives `npm i -g` updates.
+ */
+function resolveStateLayout({ packageRoot, env = process.env } = {}) {
+  if (isGitCheckout(packageRoot)) {
+    return { checkout: true, root: null, configDir: getLegacyManagedConfigDir(env), dataDir: null };
+  }
+  const root = resolveOarRoot(env);
+  return { checkout: false, root, configDir: root, dataDir: path.join(root, 'data') };
+}
+
+function getLauncherLogDir(env = process.env, layout = null) {
+  const envLogDir = String(env.COPILOT_WEB_RELAY_LOG_DIR || '').trim();
+  if (envLogDir) return envLogDir;
+  if (layout && !layout.checkout) return path.join(layout.root, 'logs');
+  return path.join(getLegacyManagedConfigDir(env), 'logs');
+}
+
+function getCopilotHomeDir(env = process.env) {
+  const override = String(env.COPILOT_CONFIG_HOME || '').trim();
+  if (override) return override;
+  if (process.platform === 'win32') {
+    const profile = String(env.USERPROFILE || '').trim();
+    return path.join(profile || os.homedir(), '.copilot');
+  }
+  return path.join(os.homedir(), '.copilot');
+}
+
+function getCopilotUserExtensionsDir(env = process.env) {
+  return path.join(getCopilotHomeDir(env), 'extensions');
+}
+
+function buildGlobalExtensionWrapperSource(entryPath) {
+  const entryUrl = pathToFileURL(path.resolve(String(entryPath || ''))).href;
+  const packageRoot = path.resolve(path.dirname(String(entryPath || '')), '..', '..', '..');
+  return [
+    '// Auto-generated by oar to provide a stable user-global extension entrypoint.',
+    '// Do not edit manually; regenerate via `oar --install-extension`.',
+    '',
+    'import path from "path";',
+    '',
+    `const PACKAGE_ROOT = ${JSON.stringify(packageRoot)};`,
+    'const cwd = path.resolve(process.cwd());',
+    'const normalizedPackageRoot = path.resolve(PACKAGE_ROOT);',
+    'const runningInsidePackage = cwd === normalizedPackageRoot || cwd.startsWith(`${normalizedPackageRoot}${path.sep}`);',
+    'const forceGlobalExtension = process.env.COPILOT_WEB_RELAY_FORCE_GLOBAL_EXTENSION === "true";',
+    '',
+    '// Avoid double-loading when the project-local extension is already discoverable from the repo itself.',
+    'if (!runningInsidePackage || forceGlobalExtension) {',
+    `  await import(${JSON.stringify(entryUrl)});`,
+    '}',
+    '',
+  ].join('\n');
+}
+
+function ensureGlobalExtensionWrapper({ packageRoot, env = process.env, logger = console } = {}) {
+  const sourceEntryPath = path.join(packageRoot, '.github', 'extensions', 'web-relay', 'extension.mjs');
+  if (!fs.existsSync(sourceEntryPath)) {
+    throw new Error(`missing extension entrypoint at ${sourceEntryPath}`);
+  }
+  const targetDir = path.join(getCopilotUserExtensionsDir(env), 'web-relay');
+  const targetFilePath = path.join(targetDir, 'extension.mjs');
+  const nextSource = buildGlobalExtensionWrapperSource(sourceEntryPath);
+  fs.mkdirSync(targetDir, { recursive: true });
+  const currentSource = fs.existsSync(targetFilePath) ? String(fs.readFileSync(targetFilePath, 'utf8')) : '';
+  if (currentSource !== nextSource) {
+    fs.writeFileSync(targetFilePath, nextSource, 'utf8');
+    logger.log?.(`[oar] Updated user extension wrapper: ${targetFilePath}`);
+  } else {
+    logger.log?.(`[oar] User extension wrapper already current: ${targetFilePath}`);
+  }
+  return { targetDir, targetFilePath, sourceEntryPath };
+}
+
+function createDefaultConfig({ port = 3333, token = '' } = {}) {
+  const parsedPort = Number.parseInt(String(port || ''), 10);
+  return {
+    authToken: String(token || '').trim() || randomUUID(),
+    port: Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535 ? parsedPort : 3333,
+    localhostOnly: true,
+    pollIntervalMs: 3000,
+    conversationSessionMode: 'isolated',
+  };
+}
+
+function resolveLauncherConfig({ packageRoot, env = process.env, relayToken = '', relayPort = 3333, layout = null } = {}) {
+  const envConfigPath = String(env.COPILOT_WEB_RELAY_CONFIG || '').trim();
+  const repoConfigPath = path.join(packageRoot, 'server', 'config.json');
+  const oarConfigPath = layout && !layout.checkout ? path.join(layout.configDir, 'config.json') : null;
+  const seedPath = (
+    (envConfigPath && fs.existsSync(envConfigPath) && envConfigPath)
+    || (oarConfigPath && fs.existsSync(oarConfigPath) && oarConfigPath)
+    || (fs.existsSync(repoConfigPath) && repoConfigPath)
+    || null
+  );
+  const managedPath = oarConfigPath || path.join(getLegacyManagedConfigDir(env), 'config.json');
+  const configPath = seedPath || managedPath;
+  const seedConfig = readJsonFile(seedPath) || {};
+  const runtimeConfig = {
+    ...createDefaultConfig({ port: relayPort }),
+    ...seedConfig,
+  };
+  if (relayToken) runtimeConfig.authToken = relayToken;
+  if (!String(runtimeConfig.authToken || '').trim()) runtimeConfig.authToken = randomUUID();
+  const parsedPort = Number.parseInt(String(runtimeConfig.port || relayPort || 3333), 10);
+  runtimeConfig.port = Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
+    ? parsedPort
+    : 3333;
+  return {
+    configPath,
+    managed: !seedPath,
+    config: runtimeConfig,
+  };
+}
+
+export async function detectRunningRelay({
+  lockPath,
+  statusUrl,
+  fetchImpl = globalThis.fetch,
+  isProcessAliveImpl = isProcessAlive,
+} = {}) {
+  const lock = readRelayLock(lockPath);
+  if (Number.isInteger(lock?.pid) && isProcessAliveImpl(lock.pid)) {
+    return { running: true, source: 'lock', lock };
+  }
+
+  if (typeof fetchImpl === 'function' && statusUrl) {
+    try {
+      const response = await fetchImpl(statusUrl, { method: 'GET' });
+      if (response) {
+        return { running: true, source: 'status', lock };
+      }
+    } catch {
+      // Not running or unreachable.
+    }
+  }
+
+  return { running: false, source: null, lock };
+}
+
+export async function launchRelay({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  packageRoot = resolvePackageRoot(),
+  nodeBin = process.execPath,
+  spawnImpl = spawn,
+  fetchImpl = globalThis.fetch,
+  env = process.env,
+  logger = console,
+} = {}) {
+  const args = Array.isArray(argv) ? [...argv] : [];
+  const installExtensionOnly = args.includes('--install-extension');
+  const skipExtensionInstall = args.includes('--no-install-extension');
+  const separatorIdx = args.indexOf('--');
+  const rawLauncherArgs = separatorIdx === -1 ? args : args.slice(0, separatorIdx);
+  const migrateFromIdx = rawLauncherArgs.indexOf('--migrate-from');
+  const migrateFromRoot = migrateFromIdx !== -1 ? String(rawLauncherArgs[migrateFromIdx + 1] || '').trim() : '';
+  const launcherArgs = rawLauncherArgs
+    .filter((arg, idx) => idx !== migrateFromIdx && idx !== migrateFromIdx + 1)
+    .filter((arg) => arg !== '--install-extension' && arg !== '--no-install-extension');
+  const forwardedArgs = separatorIdx === -1 ? [] : args.slice(separatorIdx + 1);
+  if (args.includes('--help') || args.includes('-h')) {
+    logger.log([
+      'Usage: oar [--port <port>] [--token <token>] [--migrate-from <old-checkout>] [--install-extension] [--no-install-extension] [-- [gh copilot args...]]',
+      '',
+      'Starts the web relay server if needed, then launches gh copilot in the current shell.',
+      '--install-extension installs/updates a user-global web-relay wrapper extension and exits.',
+      '--no-install-extension skips automatic wrapper setup for this run.',
+      'Install globally with: npm i -g @oar-sh/oar  (or from a checkout: npm link)',
+    ].join('\n'));
+    return { code: 0, reason: 'help' };
+  }
+
+  if (!skipExtensionInstall || installExtensionOnly) {
+    try {
+      ensureGlobalExtensionWrapper({ packageRoot, env, logger });
+    } catch (error) {
+      logger.error?.(`[oar] Failed to prepare user extension wrapper: ${error?.message || error}`);
+      if (installExtensionOnly) return { code: 1, reason: 'extension-install-failed', error };
+    }
+  }
+  if (installExtensionOnly) {
+    return { code: 0, reason: 'extension-installed' };
+  }
+
+  const port = parsePort(launcherArgs);
+  const serverDir = path.join(packageRoot, 'server');
+  const layout = resolveStateLayout({ packageRoot, env });
+
+  if (!layout.checkout) {
+    // Global install: state lives in the OAR root. Migrate pre-OAR state in
+    // exactly once (marker-guarded); a live source relay blocks the migration.
+    try {
+      const migration = await migrateStateToOarRoot({
+        targetRoot: layout.root,
+        repoServerDir: migrateFromRoot ? path.join(path.resolve(migrateFromRoot), 'server') : null,
+        managedConfigDir: getLegacyManagedConfigDir(env),
+        logger,
+      });
+      if (migration.status === 'blocked-live-relay') {
+        logger.error?.(`[oar] ${migration.error}`);
+        return { code: 1, reason: 'migration-blocked' };
+      }
+    } catch (error) {
+      logger.error?.(`[oar] State migration failed, nothing was changed at the source: ${error?.message || error}`);
+      return { code: 1, reason: 'migration-failed', error };
+    }
+  }
+
+  const lockPath = layout.checkout
+    ? path.join(serverDir, 'data', 'relay-server.lock')
+    : path.join(layout.dataDir, 'relay-server.lock');
+  const statusUrl = `http://localhost:${port}/api/status`;
+  const running = await detectRunningRelay({
+    lockPath,
+    statusUrl,
+    fetchImpl,
+  });
+
+  const runtimeConfig = resolveLauncherConfig({
+    packageRoot,
+    env,
+    relayToken: running?.lock?.token || '',
+    relayPort: port,
+    layout,
+  });
+  if (runtimeConfig.managed || !fs.existsSync(runtimeConfig.configPath)) {
+    writeJsonFile(runtimeConfig.configPath, runtimeConfig.config);
+  }
+
+  const baseEnv = {
+    ...env,
+    COPILOT_WORKSPACE_ROOT: cwd,
+    COPILOT_WEB_RELAY_ROOT: packageRoot,
+    COPILOT_WEB_RELAY_SERVER_DIR: serverDir,
+    COPILOT_WEB_RELAY_CONFIG: runtimeConfig.configPath,
+    COPILOT_WEB_RELAY_LOG_DIR: getLauncherLogDir(env, layout),
+    // Checkouts keep the repo-local server/data default; global installs point
+    // the server at the OAR root so updates cannot wipe the database.
+    ...(layout.checkout ? {} : {
+      COPILOT_WEB_RELAY_DATA_DIR: String(env.COPILOT_WEB_RELAY_DATA_DIR || '').trim() || layout.dataDir,
+    }),
+    GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS: String(env.GITHUB_COPILOT_PROMPT_MODE_EXTENSIONS || 'true'),
+  };
+
+  let serverProc = null;
+  let relayStartedByThisCommand = false;
+  if (running.running) {
+    const pid = Number.isInteger(running?.lock?.pid) ? running.lock.pid : null;
+    logger.log(
+      pid
+        ? `Copilot relay is already running (pid=${pid}) at ${statusUrl}.`
+        : `Copilot relay is already running at ${statusUrl}.`,
+    );
+  } else {
+    logger.log(`Starting Copilot relay from ${cwd}...`);
+    const serverArgs = [path.join(serverDir, 'server.js'), '--token', runtimeConfig.config.authToken, '--port', String(runtimeConfig.config.port)];
+    const logDir = getLauncherLogDir(baseEnv);
+    const serverLogPath = path.join(logDir, 'server.log');
+    const serverErrPath = path.join(logDir, 'server-err.log');
+    const serverOutFd = openAppendFileDescriptor(serverLogPath);
+    const serverErrFd = openAppendFileDescriptor(serverErrPath);
+    try {
+      serverProc = spawnImpl(nodeBin, serverArgs, {
+        cwd: packageRoot,
+        env: baseEnv,
+        stdio: ['ignore', serverOutFd, serverErrFd],
+        windowsHide: false,
+      });
+      relayStartedByThisCommand = true;
+    } catch (error) {
+      try { fs.closeSync(serverOutFd); } catch {}
+      try { fs.closeSync(serverErrFd); } catch {}
+      logger.error?.(`[oar] Failed to launch relay: ${error?.message || error}`);
+      return { code: 1, reason: 'spawn-failed', error };
+    }
+
+    if (!(serverProc instanceof EventEmitter) && typeof serverProc?.on !== 'function') {
+      return { code: 1, reason: 'spawn-invalid-child' };
+    }
+
+    const readyDeadlineMs = 20_000;
+    const ready = await new Promise((resolve) => {
+      const deadline = Date.now() + readyDeadlineMs;
+      const probe = async () => {
+        if (serverProc && serverProc.exitCode !== null) {
+          resolve(false);
+          return;
+        }
+        try {
+          const res = await fetchImpl(statusUrl, {
+            headers: { Authorization: `Bearer ${runtimeConfig.config.authToken}` },
+          });
+          if (res && res.ok) {
+            resolve(true);
+            return;
+          }
+        } catch {
+          // retry
+        }
+        if (Date.now() >= deadline) {
+          resolve(false);
+          return;
+        }
+        setTimeout(probe, 300);
+      };
+      probe();
+    });
+
+    if (!ready) {
+      logger.error?.(`[oar] Relay did not become ready at ${statusUrl}`);
+      try {
+        if (serverProc && typeof serverProc.kill === 'function') serverProc.kill();
+      } catch {}
+      try { fs.closeSync(serverOutFd); } catch {}
+      try { fs.closeSync(serverErrFd); } catch {}
+      return { code: 1, reason: 'server-not-ready' };
+    }
+
+    serverProc.once('exit', () => {
+      try { fs.closeSync(serverOutFd); } catch {}
+      try { fs.closeSync(serverErrFd); } catch {}
+    });
+  }
+
+  const ghArgs = forwardedArgs.length
+    ? ['copilot', '--', ...forwardedArgs]
+    : ['copilot'];
+  logger.log(`Launching Copilot CLI from ${cwd}...`);
+
+  let child;
+  try {
+    child = spawnImpl('gh', ghArgs, {
+      cwd,
+      env: baseEnv,
+      stdio: 'inherit',
+      windowsHide: false,
+    });
+  } catch (error) {
+    logger.error?.(`[oar] Failed to launch Copilot CLI: ${error?.message || error}`);
+    try {
+      if (relayStartedByThisCommand && serverProc && typeof serverProc.kill === 'function') serverProc.kill();
+    } catch {}
+    return { code: 1, reason: 'spawn-failed', error };
+  }
+
+  if (!(child instanceof EventEmitter) && typeof child?.on !== 'function') {
+    try {
+      if (relayStartedByThisCommand && serverProc && typeof serverProc.kill === 'function') serverProc.kill();
+    } catch {}
+    return { code: 1, reason: 'spawn-invalid-child' };
+  }
+
+  const exitCode = await new Promise((resolve) => {
+    child.on('exit', (code, signal) => {
+      resolve(code ?? (signal ? 1 : 0));
+    });
+    child.on('error', (error) => {
+      logger.error?.(`[oar] Copilot CLI process error: ${error?.message || error}`);
+      resolve(1);
+    });
+  });
+
+  if (relayStartedByThisCommand && serverProc && serverProc.exitCode === null) {
+    try {
+      serverProc.kill();
+    } catch {}
+  }
+
+  return { code: exitCode, reason: 'exited' };
+}
+
+function readPackageVersion(packageRoot = resolvePackageRoot()) {
+  try {
+    return String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version || '0.0.0');
+  } catch {
+    return '0.0.0';
+  }
+}
+
+async function promptYesNo(question, { defaultYes = false, interactive = true } = {}) {
+  if (!interactive) return defaultYes;
+  const readline = await import('node:readline/promises');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const suffix = defaultYes ? '[Y/n]' : '[y/N]';
+    const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+    if (!answer) return defaultYes;
+    return answer === 'y' || answer === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function runSetup({ argv = [], env = process.env, logger = console } = {}) {
+  const {
+    buildDefaultConfig, buildSystemdUnit, generateAuthToken, primaryLanAddress, relayUrl,
+  } = await import('../server/services/oar-cli-helpers.mjs');
+
+  const packageRoot = resolvePackageRoot();
+  const layout = resolveStateLayout({ packageRoot, env });
+  const useDefaults = argv.includes('--defaults') || !process.stdin.isTTY;
+  const migrateFromIdx = argv.indexOf('--migrate-from');
+  const migrateFromRoot = migrateFromIdx !== -1 ? String(argv[migrateFromIdx + 1] || '').trim() : '';
+
+  if (!layout.checkout) {
+    const migration = await migrateStateToOarRoot({
+      targetRoot: layout.root,
+      repoServerDir: migrateFromRoot ? path.join(path.resolve(migrateFromRoot), 'server') : null,
+      managedConfigDir: getLegacyManagedConfigDir(env),
+      logger,
+    });
+    if (migration.status === 'blocked-live-relay') {
+      logger.error?.(`[oar] ${migration.error}`);
+      return { code: 1, reason: 'migration-blocked' };
+    }
+    if (migration.status === 'migrated') {
+      logger.log(`[oar] Migrated existing relay state into ${layout.root} (sources untouched).`);
+    }
+  }
+
+  const configPath = layout.checkout
+    ? path.join(packageRoot, 'server', 'config.json')
+    : path.join(layout.configDir, 'config.json');
+  const existing = readJsonFile(configPath);
+
+  let token = String(existing?.authToken || '').trim();
+  if (token) {
+    const regenerate = await promptYesNo('A config already exists. Generate a new auth token (logs every device out)?', {
+      defaultYes: false,
+      interactive: !useDefaults,
+    });
+    if (regenerate) token = generateAuthToken();
+  } else {
+    token = generateAuthToken();
+  }
+
+  const lanAccess = existing
+    ? existing.localhostOnly === false
+    : await promptYesNo('Allow LAN access so your phone can connect directly (otherwise localhost + tunnel only)?', {
+      defaultYes: false,
+      interactive: !useDefaults,
+    });
+
+  const config = { ...buildDefaultConfig({ token }), ...(existing || {}) };
+  config.authToken = token;
+  config.localhostOnly = !lanAccess;
+
+  if (await promptYesNo('Enable the managed cloudflared tunnel (public URL for remote access)?', {
+    defaultYes: false,
+    interactive: !useDefaults,
+  })) {
+    config.cloudflaredTunnel = { ...(config.cloudflaredTunnel || {}), enabled: true };
+  }
+
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  if (process.platform !== 'win32') {
+    try { fs.chmodSync(configPath, 0o600); } catch {}
+  }
+  logger.log(`[oar] Wrote ${configPath}`);
+
+  if (process.platform === 'linux' && !layout.checkout) {
+    if (await promptYesNo('Install a systemd user service so the relay starts on login?', {
+      defaultYes: false,
+      interactive: !useDefaults,
+    })) {
+      const unitDir = path.join(os.homedir(), '.config', 'systemd', 'user');
+      const unitPath = path.join(unitDir, 'oar.service');
+      fs.mkdirSync(unitDir, { recursive: true });
+      fs.writeFileSync(unitPath, buildSystemdUnit({
+        nodeBin: process.execPath,
+        packageRoot,
+        configPath,
+        dataDir: layout.dataDir,
+        logDir: getLauncherLogDir(env, layout),
+      }));
+      logger.log(`[oar] Wrote ${unitPath} — enable it with: systemctl --user enable --now oar`);
+    }
+  } else if (process.platform === 'win32') {
+    logger.log('[oar] Autostart on Windows: enable it in the web UI under Settings → Autostart.');
+  }
+
+  const url = relayUrl({ config, lanAddress: primaryLanAddress() });
+  logger.log('');
+  logger.log(`[oar] Relay URL: ${url}`);
+  if (config.localhostOnly) {
+    logger.log('[oar] localhostOnly is on — reach it from other devices via the tunnel, or rerun `oar setup` for LAN access.');
+  }
+  try {
+    const qrcode = (await import('qrcode-terminal')).default;
+    qrcode.generate(url, { small: true }, (qr) => logger.log(qr));
+  } catch {
+    // QR is a convenience — the URL above is the contract.
+  }
+  logger.log('[oar] Start the relay with: oar');
+  return { code: 0, reason: 'setup-complete' };
+}
+
+async function runDoctor({ env = process.env, logger = console } = {}) {
+  const { DOCTOR_PROBES, renderDoctorReport } = await import('../server/services/oar-cli-helpers.mjs');
+  const { spawnSync } = await import('node:child_process');
+
+  const packageRoot = resolvePackageRoot();
+  const layout = resolveStateLayout({ packageRoot, env });
+  const configPath = layout.checkout
+    ? path.join(packageRoot, 'server', 'config.json')
+    : path.join(layout.configDir, 'config.json');
+  const dbPath = layout.checkout
+    ? path.join(packageRoot, 'server', 'data', 'copilot.db')
+    : path.join(layout.dataDir, 'copilot.db');
+
+  let dbSizeBytes = null;
+  try { dbSizeBytes = fs.statSync(dbPath).size; } catch {}
+
+  const probes = DOCTOR_PROBES.map((probe) => {
+    try {
+      const result = spawnSync(probe.binary, probe.args, { encoding: 'utf8', timeout: 5000, windowsHide: true });
+      const ok = result.status === 0;
+      const version = ok ? String(result.stdout || '').trim().split('\n')[0].slice(0, 60) : '';
+      return { id: probe.id, ok, version };
+    } catch {
+      return { id: probe.id, ok: false };
+    }
+  });
+  probes.push({ id: 'cursor', ok: true, version: 'bundled (@cursor/sdk)' });
+
+  logger.log(renderDoctorReport({
+    version: readPackageVersion(packageRoot),
+    nodeVersion: process.version,
+    platform: process.platform,
+    layout,
+    configPath,
+    config: readJsonFile(configPath),
+    dbPath,
+    dbSizeBytes,
+    probes,
+  }));
+  return { code: 0, reason: 'doctor' };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const command = String(argv[0] || '').trim();
+  if (command === '--version' || command === '-v') {
+    console.log(readPackageVersion());
+    return Promise.resolve({ code: 0, reason: 'version' });
+  }
+  if (command === 'setup') return runSetup({ argv: argv.slice(1) });
+  if (command === 'doctor') return runDoctor({});
+  return launchRelay();
+}
+
+const executedName = process.argv[1] ? path.basename(String(process.argv[1])) : '';
+if (executedName === 'oar.js') {
+  main().then(({ code }) => {
+    process.exit(code ?? 0);
+  }).catch((error) => {
+    console.error(`[oar] Unhandled error: ${error?.message || error}`);
+    process.exit(1);
+  });
+}
+
+export { main, parsePort, readRelayLock, resolvePackageRoot };