@oar-sh/oar 0.9.8 → 0.9.9

package/server/services/cloudflared-tunnel-service.mjs

@@ -2,16 +2,17 @@
 
 import path from 'path';
 import fs from 'fs';
-import { createRequire } from 'module';
 import { spawn } from 'child_process';
 
-const requireFromHere = createRequire(import.meta.url);
-
 const BACKOFF_STEPS = [5_000, 10_000, 20_000, 40_000, 60_000];
 const READINESS_WINDOW_MS = 5_000;
 const STABLE_CONNECTION_MS = 30_000;
 const FAST_EXIT_MS = 10_000;
 const MAX_CONSECUTIVE_FAST_EXITS = 3;
+const BINARY_RECHECK_MS = 60_000;
+// What Windows starts without a shell. A `.cmd`/`.bat` launcher would need
+// cmd.exe, and the tunnel token does not go through a shell command line.
+const WINDOWS_DIRECT_EXTENSIONS = ['.exe', '.com'];
 
 function toText(value) {
   return String(value || '').trim();
@@ -29,28 +30,91 @@ function normalizeExtraArgs(rawValue) {
   return rawValue.map((entry) => toText(entry)).filter(Boolean);
 }
 
-// The npm `cloudflared` package downloads the official binary on demand; it is an
-// optional dependency, so absence must degrade to a config error, never a crash.
-// `requireImpl` is a seam: the package is optional, so a suite running under
-// `npm ci --omit=optional` (or after a failed postinstall download) must still be
-// able to exercise this logic instead of silently testing the host's install state.
-export function resolveCloudflaredBinaryFromPackage({
-  existsSync = fs.existsSync,
-  requireImpl = requireFromHere,
+function hasDirectoryPart(value) {
+  return value.includes('/') || value.includes('\\');
+}
+
+/**
+ * Where the cloudflared the tunnel would run really is, or null. OAR ships no
+ * copy: a name is looked up on PATH (on Windows with the `.exe`/`.com`
+ * suffixes PATHEXT lists), a path must be an executable file.
+ */
+export function locateCloudflaredBinary(binary, {
+  platform = process.platform,
+  env = process.env,
+  fsImpl = fs,
+  pathImpl = platform === 'win32' ? path.win32 : path.posix,
 } = {}) {
-  try {
-    const mod = requireImpl('cloudflared');
-    const bin = toText(mod?.bin);
-    // `bin` is where the package *will* place the binary; it only exists after
-    // the on-demand download has run, so an un-downloaded path is not usable.
-    if (bin && existsSync(bin)) return bin;
-  } catch {}
+  const name = toText(binary);
+  if (!name) return null;
+
+  let names = [name];
+  if (platform === 'win32' && !WINDOWS_DIRECT_EXTENSIONS.includes(pathImpl.extname(name).toLowerCase())) {
+    const listed = String(env?.PATHEXT || '')
+      .split(';')
+      .map((ext) => toText(ext).toLowerCase())
+      .filter((ext) => WINDOWS_DIRECT_EXTENSIONS.includes(ext));
+    names = (listed.length ? listed : WINDOWS_DIRECT_EXTENSIONS).map((ext) => `${name}${ext}`);
+  }
+
+  const isExecutableFile = (candidate) => {
+    try {
+      if (!fsImpl.statSync(candidate).isFile()) return false;
+      // Windows has no execute bit; the suffix above decided.
+      if (platform !== 'win32') fsImpl.accessSync(candidate, fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  const dirs = hasDirectoryPart(name)
+    ? [null]
+    : String(env?.PATH ?? env?.Path ?? '').split(pathImpl.delimiter).map(toText).filter(Boolean);
+  for (const dir of dirs) {
+    for (const candidate of names) {
+      const full = dir === null ? candidate : pathImpl.join(dir, candidate);
+      if (isExecutableFile(full)) return full;
+    }
+  }
   return null;
 }
 
+export function cloudflaredInstallPointer(platform = process.platform) {
+  if (platform === 'win32') return 'install it with: winget install --id Cloudflare.cloudflared';
+  if (platform === 'darwin') return 'install it with: brew install cloudflared';
+  return "install it from Cloudflare's package repository: https://pkg.cloudflare.com/";
+}
+
+/** The one sentence the tunnel state, the status dot and the CLI show. */
+export function describeMissingCloudflaredBinary({ binary = '', binarySource = 'path', platform = process.platform } = {}) {
+  const pointer = cloudflaredInstallPointer(platform);
+  if (binarySource === 'config') {
+    return `cloudflared was not found as configured (${binary}) — correct cloudflaredTunnel.binary, or ${pointer}`;
+  }
+  return `cloudflared is not installed — ${pointer}`;
+}
+
+/**
+ * The tunnel in one line for a CLI status row. Takes the manager's state or
+ * the `cloudflaredTunnel` object of `/api/status`; the public address is the
+ * caller's to pass, the relay does not know it (the route lives in Cloudflare).
+ */
+export function describeTunnelState(state, { url = '' } = {}) {
+  const tunnel = state && typeof state === 'object' ? state : {};
+  const managed = toText(tunnel.mode).toLowerCase() === 'managed' || tunnel.enabled === true;
+  if (!managed) return 'off';
+  const reason = toText(tunnel.lastError);
+  if (tunnel.connected === true) {
+    const address = toText(url);
+    return address ? `running (${address})` : 'running';
+  }
+  if (tunnel.binaryMissing === true || tunnel.valid === false) return reason ? `off: ${reason}` : 'off';
+  return reason ? `not connected (${reason})` : 'not connected';
+}
+
 export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   env = process.env,
-  resolveBinary = resolveCloudflaredBinaryFromPackage,
   configBaseDir = process.cwd(),
   pathImpl = path,
 } = {}) {
@@ -64,33 +128,20 @@ export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   const binaryInput = toText(env?.COPILOT_CLOUDFLARED_BINARY) || toText(raw.binary);
   const extraArgs = normalizeExtraArgs(raw.extraArgs);
 
-  let binary = '';
-  let binarySource = null;
+  // The configured binary, else `cloudflared` from PATH. Whether it is really
+  // there is checked when the tunnel starts (locateCloudflaredBinary).
+  let binary = 'cloudflared';
+  let binarySource = 'path';
   if (binaryInput) {
-    binary = binaryInput.includes('/') || binaryInput.includes('\\')
+    binary = hasDirectoryPart(binaryInput)
       ? pathImpl.resolve(configBaseDir, binaryInput)
       : binaryInput;
     binarySource = 'config';
-  } else {
-    let packageBinary = null;
-    try {
-      packageBinary = toText(typeof resolveBinary === 'function' ? resolveBinary() : '');
-    } catch {
-      packageBinary = null;
-    }
-    if (packageBinary) {
-      binary = packageBinary;
-      binarySource = 'package';
-    } else {
-      binary = 'cloudflared';
-      binarySource = 'path';
-    }
   }
 
   const errors = [];
   if (mode === 'managed') {
     if (!token) errors.push('cloudflaredTunnel.token is required when cloudflaredTunnel.mode is "managed"');
-    if (!binary) errors.push('cloudflaredTunnel.binary could not be resolved (install the "cloudflared" package or set cloudflaredTunnel.binary)');
   }
 
   return {
@@ -106,6 +157,28 @@ export function normalizeCloudflaredTunnelConfig(rawConfig = {}, {
   };
 }
 
+/**
+ * The tunnel as `oar doctor` reports it, from the config alone (no relay
+ * needed): whether the built-in tunnel is on and whether it could start.
+ */
+export function describeConfiguredTunnel(rawConfig = {}, {
+  env = process.env,
+  platform = process.platform,
+  configBaseDir = process.cwd(),
+  pathImpl = path,
+  locateBinary = locateCloudflaredBinary,
+} = {}) {
+  const tunnelConfig = normalizeCloudflaredTunnelConfig(rawConfig, { env, configBaseDir, pathImpl });
+  if (tunnelConfig.mode !== 'managed') return 'disabled';
+  if (!tunnelConfig.valid) return `managed, cannot start: ${tunnelConfig.errors[0]}`;
+  const located = locateBinary(tunnelConfig.binary, { platform, env });
+  if (!located) {
+    const { binary, binarySource } = tunnelConfig;
+    return `managed, cannot start: ${describeMissingCloudflaredBinary({ binary, binarySource, platform })}`;
+  }
+  return `managed (cloudflared: ${located})`;
+}
+
 export function buildCloudflaredArgs(tunnelConfig) {
   return ['tunnel', 'run', '--token', tunnelConfig.token, ...tunnelConfig.extraArgs];
 }
@@ -145,12 +218,11 @@ export function createCloudflaredTunnelManager({
   clearTimeoutImpl = clearTimeout,
   configBaseDir = process.cwd(),
   env = process.env,
-  resolveBinary = resolveCloudflaredBinaryFromPackage,
+  locateBinary = locateCloudflaredBinary,
   pathImpl = path,
 } = {}) {
   const tunnelConfig = normalizeCloudflaredTunnelConfig(rawTunnelConfig, {
     env,
-    resolveBinary,
     configBaseDir,
     pathImpl,
   });
@@ -174,6 +246,7 @@ export function createCloudflaredTunnelManager({
     lastError: tunnelConfig.errors[0] || null,
     lastEventAt: nowIso(),
     binary: tunnelConfig.binary || null,
+    binaryMissing: false,
     proc: null,
     backoffTimer: null,
   };
@@ -189,6 +262,7 @@ export function createCloudflaredTunnelManager({
       reconnectAttempts: state.reconnectAttempts,
       connectedSince: state.connectedSince,
       lastError: state.lastError,
+      binaryMissing: state.binaryMissing,
     });
   };
 
@@ -220,9 +294,33 @@ export function createCloudflaredTunnelManager({
       return;
     }
 
+    // OAR ships no cloudflared. Without one the tunnel stays off, the state
+    // says how to install it, and a look every minute starts the tunnel once
+    // it is there (no relay restart, as long as it lands on the relay's PATH).
+    let located = null;
+    try { located = toText(locateBinary(tunnelConfig.binary, { platform, env })); } catch {}
+    if (!located) {
+      if (!state.binaryMissing) {
+        state.binaryMissing = true;
+        state.lastError = describeMissingCloudflaredBinary({
+          binary: tunnelConfig.binary,
+          binarySource: tunnelConfig.binarySource,
+          platform,
+        });
+        warn(`Tunnel not started: ${state.lastError}`);
+        updateBlockingState();
+        emitStatus();
+      }
+      if (state.backoffTimer) clearTimeoutImpl(state.backoffTimer);
+      state.backoffTimer = setTimeoutImpl(spawnTunnel, BINARY_RECHECK_MS);
+      if (typeof state.backoffTimer?.unref === 'function') state.backoffTimer.unref();
+      return;
+    }
+    state.binaryMissing = false;
+
     const args = buildCloudflaredArgs(tunnelConfig);
-    log(`Spawning: ${tunnelConfig.binary} ${redactCloudflaredArgs(args).join(' ')}`);
-    const proc = spawnImpl(tunnelConfig.binary, args, buildSpawnOptions(platform, ['ignore', 'pipe', 'pipe']));
+    log(`Spawning: ${located} ${redactCloudflaredArgs(args).join(' ')}`);
+    const proc = spawnImpl(located, args, buildSpawnOptions(platform, ['ignore', 'pipe', 'pipe']));
     state.proc = proc;
     state.lastError = null;
     updateBlockingState();

package/server/services/file-serving.mjs

@@ -0,0 +1,155 @@
+// Serving a file from disk so that what arrives is the file as it is now:
+// one open, one fstat, and length, validators and bytes all from that handle.
+// The headers tell every cache on the way, the browser's and a CDN's alike,
+// to keep nothing.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { applySafeServedContentHeaders } from './safe-served-content.mjs';
+
+/**
+ * A short token that changes whenever the file's bytes may have changed
+ * (modification time or size). It goes into download URLs as `v=…`: the
+ * server ignores it, and a changed file gets a URL nothing has seen before.
+ */
+export function fileVersionToken({ mtimeMs, size } = {}) {
+  const modified = Math.floor(Number(mtimeMs));
+  const bytes = Number(size);
+  if (!Number.isFinite(modified) || !Number.isFinite(bytes) || modified < 0 || bytes < 0) return '';
+  return `${modified.toString(36)}-${Math.floor(bytes).toString(36)}`;
+}
+
+/**
+ * `Cache-Control` speaks to browsers and to proxies that honour it. The two
+ * CDN headers bind the edge itself: Cloudflare obeys them ahead of
+ * `Cache-Control` and of a "cache everything" rule that would otherwise
+ * override the origin's wish.
+ */
+export function applyNoStoreHeaders(res) {
+  res.setHeader('Cache-Control', 'no-store');
+  applyCdnNoStoreHeaders(res);
+}
+
+export function applyCdnNoStoreHeaders(res) {
+  res.setHeader('CDN-Cache-Control', 'no-store');
+  res.setHeader('Cloudflare-CDN-Cache-Control', 'no-store');
+}
+
+/**
+ * The name a download is saved under, when the client asks for one (`as=…`).
+ * Accepted only as a plain file name with the real file's extension, so the
+ * request cannot change what kind of file the browser believes it gets.
+ */
+export function downloadNameOverride(requested, realName) {
+  const wanted = String(requested || '').trim();
+  if (!wanted || wanted.length > 200) return '';
+  if (/[\\/:*?"<>|\u0000-\u001f\u007f]/.test(wanted) || wanted === '.' || wanted === '..') return '';
+  const realExt = path.extname(String(realName || '')).toLowerCase();
+  if (path.extname(wanted).toLowerCase() !== realExt) return '';
+  return wanted;
+}
+
+function appendUrlParam(url, key, value) {
+  if (!value) return url;
+  return `${url}${url.includes('?') ? '&' : '?'}${key}=${encodeURIComponent(value)}`;
+}
+
+/** `url` with the file's version token appended, or unchanged when there is none. */
+export function withFileVersion(url, version) {
+  return appendUrlParam(String(url || ''), 'v', String(version || ''));
+}
+
+/**
+ * `cacheControl` replaces the no-store default for content whose URL names
+ * its bytes (an upload addressed by its hash): such an answer may be kept.
+ */
+export function serveFileWithRangeSupport(req, res, filePath, meta, { safeName, cacheDelete = null, fsImpl = fs, cacheControl = '' } = {}) {
+  const realName = safeName || path.basename(filePath).replace(/"/g, '');
+  const name = downloadNameOverride(req.query?.as, realName) || realName;
+  const rangeHeader = req.headers['range'];
+
+  const fail = (error) => {
+    if (cacheDelete) cacheDelete(filePath);
+    if (res.headersSent) { res.destroy(error); return; }
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR' || error?.code === 'EISDIR') {
+      res.status(404).json({ error: 'File not found' });
+      return;
+    }
+    res.status(500).json({ error: 'Failed to read file' });
+  };
+
+  // The caller's `meta` may be a moment old (it is cached). Size, validators
+  // and bytes all come from this one handle instead: a length taken from an
+  // older stat cut a file that had just grown down to its previous size.
+  let fd = null;
+  let stat = null;
+  try {
+    fd = fsImpl.openSync(filePath, 'r');
+    stat = fsImpl.fstatSync(fd);
+  } catch (error) {
+    if (fd !== null) { try { fsImpl.closeSync(fd); } catch {} }
+    fail(error);
+    return;
+  }
+  const closeFd = () => { try { fsImpl.closeSync(fd); } catch {} };
+  if (!stat.isFile()) {
+    closeFd();
+    fail(Object.assign(new Error('Not a file'), { code: 'EISDIR' }));
+    return;
+  }
+  const fileSize = Number(stat.size || 0);
+
+  // From here until the stream owns the handle, any throw (a header value
+  // `setHeader` refuses, say) must close the handle, or every such request
+  // would leak one.
+  let start = 0;
+  let end = fileSize - 1;
+  try {
+    res.setHeader('Accept-Ranges', 'bytes');
+    if (cacheControl) res.setHeader('Cache-Control', cacheControl);
+    else applyNoStoreHeaders(res);
+    // Validators cost nothing next to no-store, and they let a client or a
+    // person with curl see which version of the file an answer carries.
+    const version = fileVersionToken({ mtimeMs: stat.mtimeMs, size: fileSize });
+    if (version) res.setHeader('ETag', `W/"${version}"`);
+    if (Number.isFinite(stat.mtimeMs)) res.setHeader('Last-Modified', new Date(stat.mtimeMs).toUTCString());
+    // Neutralize browser-executable types (HTML/SVG/XML), force nosniff, and
+    // sandbox the response so a worker-written workspace file can't run as script
+    // on this origin. Media stays inline for preview; everything else downloads.
+    applySafeServedContentHeaders(res, meta?.contentType, { fileName: name });
+
+    if (rangeHeader) {
+      const match = /bytes=(\d+)-(\d*)/.exec(rangeHeader);
+      const from = match ? parseInt(match[1], 10) : NaN;
+      const to = match && match[2] ? parseInt(match[2], 10) : fileSize - 1;
+      if (!match || from > to || from >= fileSize || to >= fileSize) {
+        closeFd();
+        res.setHeader('Content-Range', `bytes */${fileSize}`);
+        res.status(416).end();
+        return;
+      }
+      start = from;
+      end = to;
+      res.setHeader('Content-Range', `bytes ${start}-${end}/${fileSize}`);
+      res.status(206);
+    }
+    res.setHeader('Content-Length', String(Math.max(0, end - start + 1)));
+  } catch (error) {
+    closeFd();
+    fail(error);
+    return;
+  }
+  if (end - start + 1 <= 0) {
+    closeFd();
+    res.end();
+    return;
+  }
+  // Bounded to the size just read, so a file that grows while it is sent
+  // still yields exactly the announced number of bytes.
+  const stream = fsImpl.createReadStream(null, { fd, start, end, autoClose: true });
+  stream.on('error', fail);
+  // A client that goes away mid-download would otherwise leave the handle open.
+  res.on?.('close', () => stream.destroy());
+  stream.pipe(res);
+}

package/server/services/message-pin-list.mjs

@@ -0,0 +1,52 @@
+'use strict';
+
+// The list of pinned messages a conversation carries: one short plain-text
+// preview per pin, so the browser can show the list without loading (or
+// rendering markdown for) messages outside its history page.
+
+import { stripRelayPromptContext } from './relay-prompt-sanitizer.mjs';
+
+export const MESSAGE_PIN_LIMIT = 100;
+export const PIN_PREVIEW_MAX_LENGTH = 160;
+
+function countAttachments(raw) {
+  if (Array.isArray(raw)) return raw.length;
+  if (typeof raw !== 'string' || !raw) return 0;
+  try {
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.length : 0;
+  } catch {
+    return 0;
+  }
+}
+
+// Light on purpose: enough that a heading, a list or a link reads as a line of
+// text. Single * and _ stay, they are more often part of a name than emphasis.
+export function buildPinPreview(text, mode = '') {
+  const plain = String(stripRelayPromptContext(String(text || ''), mode) || '')
+    .replace(/```[^\n]*\n?/g, ' ')
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, (_match, alt) => (alt ? `🖼 ${alt}` : '🖼'))
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/^\s{0,3}(?:#{1,6}|>+|[-*+]|\d+[.)])\s+/gm, '')
+    .replace(/\*\*|__|~~|`/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  // By code point, so an emoji at the cut is dropped whole.
+  const points = Array.from(plain);
+  if (points.length <= PIN_PREVIEW_MAX_LENGTH) return plain;
+  return `${points.slice(0, PIN_PREVIEW_MAX_LENGTH - 1).join('').trimEnd()}…`;
+}
+
+export function buildPinList(rows) {
+  return (Array.isArray(rows) ? rows : [])
+    .filter((row) => String(row?.id || '').trim() && row?.pinned_at)
+    .map((row) => ({
+      messageId: String(row.id).trim(),
+      role: String(row.role || '').trim(),
+      preview: buildPinPreview(row.text, row.mode),
+      timestamp: row.timestamp || null,
+      pinnedAt: row.pinned_at,
+      attachmentCount: countAttachments(row.attachments),
+      hiddenFromShares: Number(row.hidden_from_shares || 0) === 1,
+    }));
+}

package/server/services/oar-cli-helpers.mjs

@@ -1,5 +1,5 @@
 /**
- * Pure helpers behind `oar setup` and `oar doctor` — everything here is
+ * Pure helpers behind the `oar` command line — everything here is
  * deterministic and unit-testable; the interactive glue stays in bin/oar.js.
  */
 
@@ -41,6 +41,135 @@ export function relayUrl({ config, lanAddress = null } = {}) {
   return `http://${host}:${config?.port || 3333}/?token=${encodeURIComponent(token)}`;
 }
 
+/**
+ * What `oar setup` and `oar url` print about the relay's address. `qrUrl` is
+ * set only for an address a phone can reach: the LAN address when LAN access
+ * is on, and never one that is internal to WSL. `tunnelUrl` is the address a
+ * running relay reports for its tunnel, with the token added.
+ */
+export function describeRelayAddress({ config, lanAddress = null, wslNat = false, tunnelBase = '' } = {}) {
+  const lan = config?.localhostOnly === false;
+  const url = relayUrl({ config: { ...config, localhostOnly: !lan }, lanAddress });
+  const lines = [`[oar] Relay URL: ${url}`];
+  let qrUrl = null;
+  if (!lan) {
+    lines.push('[oar] This machine only. For a phone, switch on LAN access (oar setup --lan) or use a tunnel (README: Remote access).');
+  } else if (!lanAddress) {
+    lines.push('[oar] LAN access is on, but this machine has no network address.');
+  } else if (wslNat) {
+    lines.push('[oar] That address is internal to WSL; other devices cannot reach it. Ways out: a tunnel (README: Remote access), or WSL\'s mirrored networking (networkingMode=mirrored in .wslconfig).');
+  } else {
+    qrUrl = url;
+  }
+  const base = String(tunnelBase || '').trim().replace(/\/+$/, '');
+  const tunnelUrl = base ? `${base}/?token=${encodeURIComponent(String(config?.authToken || '').trim())}` : null;
+  return { url, lines, qrUrl, tunnelUrl };
+}
+
+const VALUE_OPTIONS = ['--port', '--migrate-from', '--to'];
+const LAUNCHER_FLAGS = ['--install-extension', '--no-install-extension', '--migrate-from'];
+const COMMAND_OPTIONS = { '--setup': 'setup', '--start': 'start', '--stop': 'stop', '--status': 'status' };
+const CLI_COMMANDS = {
+  menu: {},
+  start: {},
+  stop: {},
+  restart: {},
+  status: {},
+  url: {},
+  doctor: {},
+  help: {},
+  version: {},
+  setup: { flags: ['--lan', '--local', '--new-token', '--defaults', '--start'], values: ['--port', '--migrate-from'] },
+  service: { words: ['install', 'remove', 'status'] },
+  update: { flags: ['--beta'], values: ['--to'] },
+  copilot: { flags: ['--install-extension', '--no-install-extension'], values: ['--port', '--migrate-from'], forwards: true },
+};
+
+export function usageText() {
+  return [
+    'Usage: oar [command] [options]',
+    '',
+    '  oar                    Menu in a terminal; status and this text elsewhere',
+    '  oar start              Start the relay in the background',
+    '  oar stop               Stop the relay (waits for running turns)',
+    '  oar restart            Restart the relay (waits for running turns)',
+    '  oar status             Is the relay running, on which port, as a service',
+    '  oar url                Relay URL, with a QR code when a phone can reach it',
+    '  oar setup              Auth token, access and port; asks, or takes',
+    '                         [--port <port>] [--lan | --local] [--new-token] [--defaults] [--start]',
+    '  oar service install | remove | status',
+    '                         Start the relay at login',
+    '  oar copilot [--port <port>] [--install-extension] [--no-install-extension] [-- gh copilot args...]',
+    '                         Relay plus a Copilot terminal session',
+    '  oar doctor             Check the install and the provider CLIs',
+    '  oar update [--beta] [--to <version>]',
+    '  oar help               This text',
+    '  oar --version',
+  ].join('\n');
+}
+
+/**
+ * Reads the command line into `{ command, args }`, or `{ error }` for anything
+ * `oar` does not know, so nothing starts by accident. The command may follow
+ * options (`oar --port 3339 setup`), and `--setup`, `--start`, `--stop` and
+ * `--status` name it too. Without a command the launcher's own flags (or a
+ * `--` part) mean the Copilot session, and nothing at all means the menu.
+ */
+export function parseCliArgs(argv = []) {
+  const all = (Array.isArray(argv) ? argv : []).map((arg) => String(arg));
+  const separator = all.indexOf('--');
+  const head = separator === -1 ? all : all.slice(0, separator);
+  const forwarded = separator === -1 ? [] : all.slice(separator);
+  if (head.includes('--help') || head.includes('-h')) return { command: 'help', args: [] };
+
+  let command = null;
+  let args = [];
+  for (let index = 0; index < head.length; index += 1) {
+    const arg = head[index];
+    if (VALUE_OPTIONS.includes(arg)) {
+      if (index + 1 >= head.length) return { error: `${arg} needs a value.` };
+      args.push(arg, head[index += 1]);
+    } else if (arg.startsWith('-') || command) {
+      args.push(arg);
+    } else {
+      command = arg;
+    }
+  }
+  if (!command) {
+    const named = args.includes('--setup') ? '--setup' : args.find((arg) => COMMAND_OPTIONS[arg]);
+    if (args.includes('--version') || args.includes('-v')) return { command: 'version', args: [] };
+    if (named) {
+      command = COMMAND_OPTIONS[named];
+      args.splice(args.indexOf(named), 1);
+    } else if (forwarded.length || args.some((arg) => LAUNCHER_FLAGS.includes(arg))) {
+      command = 'copilot';
+    } else if (!args.length) {
+      command = 'menu';
+    } else {
+      // An option this command line knows needs its command; any other is unknown.
+      const known = [...VALUE_OPTIONS, '--lan', '--local', '--new-token', '--defaults', '--beta'];
+      return { error: known.includes(args[0]) ? `${args[0]} needs a command.` : `Unknown option: ${args[0]}` };
+    }
+  }
+
+  const spec = Object.hasOwn(CLI_COMMANDS, command) ? CLI_COMMANDS[command] : null;
+  if (!spec) return { error: `Unknown command: ${command}` };
+  if (forwarded.length && !spec.forwards) return { error: `oar ${command} takes no "--" part.` };
+  let words = 0;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const name = arg.startsWith('--') ? arg.split('=')[0] : arg;
+    if (spec.values?.includes(name)) {
+      if (arg === name) index += 1;
+    } else if (spec.words?.includes(arg) && words === 0) {
+      words += 1;
+    } else if (!spec.flags?.includes(arg)) {
+      return { error: arg.startsWith('-') ? `Unknown option for oar ${command}: ${arg}` : `Unexpected argument: ${arg}` };
+    }
+  }
+  return { command, args: [...args, ...forwarded] };
+}
+
 /**
  * A systemd *user* unit for the relay server. The launcher is not used here —
  * the service runs server.js directly with the same env the launcher would set,
@@ -102,7 +231,7 @@ export function buildServicePath({ nodeBin, envPath = '', homeDir = '' } = {}) {
  * accept the flag and run the scripts as before. `npm-install-scripts.test.mjs`
  * holds this list to the lockfile.
  */
-export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['better-sqlite3', 'cloudflared', 'koffi']);
+export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['better-sqlite3', 'koffi']);
 export const NPM_ALLOW_SCRIPTS_ARG = `--allow-scripts=${NPM_INSTALL_SCRIPT_PACKAGES.join(',')}`;
 
 /**
@@ -155,6 +284,8 @@ export function renderDoctorReport({
   dbPath,
   dbSizeBytes,
   probes = [],
+  warnings = [],
+  tunnel = '',
 }) {
   const yesNo = (v) => (v ? 'yes' : 'no');
   const lines = [
@@ -167,13 +298,17 @@ export function renderDoctorReport({
   if (config) {
     lines.push(`  port          : ${config.port ?? 3333} (localhostOnly: ${yesNo(config.localhostOnly !== false)})`);
     lines.push(`  auth token    : ${String(config.authToken || '').trim() ? 'set' : 'MISSING'}`);
-    const tunnel = config.cloudflaredTunnel || {};
-    lines.push(`  tunnel        : ${tunnel.enabled === true || tunnel.mode === 'managed' ? 'managed' : 'disabled'}`);
+    // `tunnel` is the caller's finding (describeConfiguredTunnel: is the tunnel
+    // on, and is there a cloudflared to run it); without one, the config's word.
+    const tunnelConfig = config.cloudflaredTunnel || {};
+    const configured = tunnelConfig.enabled === true || tunnelConfig.mode === 'managed' ? 'managed' : 'disabled';
+    lines.push(`  tunnel        : ${tunnel || configured}`);
   }
   lines.push(`  database      : ${dbSizeBytes !== null ? `${dbPath} (${(dbSizeBytes / 1048576).toFixed(1)} MB)` : `${dbPath} (not created yet)`}`);
   lines.push('  provider CLIs :');
   for (const probe of probes) {
     lines.push(`    ${probe.id.padEnd(14)}: ${probe.ok ? probe.version || 'installed' : 'not found'}`);
   }
+  for (const warning of warnings) lines.push(`  warning       : ${warning}`);
   return lines.join('\n');
 }