@oar-sh/oar 0.9.7 → 0.9.9

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,9 +1,10 @@
 /**
- * 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.
  */
 
 import { randomBytes } from 'node:crypto';
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
@@ -40,12 +41,141 @@ 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,
  * so a `gh copilot` session is not tied to the unit's lifetime.
  */
-export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, logDir }) {
+export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, logDir, pathEnv = '' }) {
   // systemd units are Linux-only, so the path inside the unit is always
   // posix-joined — host-platform path.join would write backslashes when this
   // template is exercised on Windows (tests; the CLI never writes it there).
@@ -59,6 +189,10 @@ export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, lo
     `Environment=COPILOT_WEB_RELAY_CONFIG=${configPath}`,
     `Environment=COPILOT_WEB_RELAY_DATA_DIR=${dataDir}`,
     `Environment=COPILOT_WEB_RELAY_LOG_DIR=${logDir}`,
+    // A user service starts with systemd's bare PATH: without this line the
+    // relay's sessions find neither the provider CLIs in ~/.local/bin nor, on
+    // an install with a private Node, `node` and `npm` themselves.
+    ...(pathEnv ? [`Environment="PATH=${escapeSystemdValue(pathEnv)}"`] : []),
     'Restart=on-failure',
     'RestartSec=5',
     '',
@@ -68,6 +202,67 @@ export function buildSystemdUnit({ nodeBin, packageRoot, configPath, dataDir, lo
   ].join('\n');
 }
 
+// Inside a quoted systemd assignment a backslash and a quote need escaping,
+// and `%` opens a specifier.
+function escapeSystemdValue(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
+}
+
+/**
+ * The PATH a relay service gets: the PATH `oar setup` ran with (the user's
+ * shell, so their tools), with two directories added when they are not on it:
+ * `~/.local/bin`, where the provider CLIs install themselves and which a
+ * shell only picks up once it exists, and the directory of the Node that runs
+ * the relay.
+ */
+export function buildServicePath({ nodeBin, envPath = '', homeDir = '' } = {}) {
+  const entries = String(envPath || '').split(':').filter(Boolean);
+  const localBin = homeDir ? path.posix.join(String(homeDir), '.local', 'bin') : '';
+  if (localBin && !entries.includes(localBin)) entries.unshift(localBin);
+  const nodeDir = nodeBin ? path.posix.dirname(String(nodeBin)) : '';
+  if (nodeDir && !entries.includes(nodeDir)) entries.push(nodeDir);
+  return entries.join(':');
+}
+
+/**
+ * The dependencies whose install scripts OAR needs (they fetch or build a
+ * native binary). npm 12 runs no install script it was not told to allow, and
+ * a global install has no package.json of its own to say so; npm 10 and 11
+ * 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', 'koffi']);
+export const NPM_ALLOW_SCRIPTS_ARG = `--allow-scripts=${NPM_INSTALL_SCRIPT_PACKAGES.join(',')}`;
+
+/**
+ * How to run `npm install -g` so the update lands in the install that is
+ * running. Away from Windows: the npm that belongs to this Node (a relay
+ * service or a private Node has no `npm` on PATH, and a version manager may
+ * put another Node's there), this Node first on the child's PATH because npm
+ * is a `node` script, and the prefix this package sits in, so an install made
+ * with `--prefix` is updated in place.
+ */
+export function resolveNpmInvocation({
+  execPath = process.execPath,
+  packageRoot = '',
+  platform = process.platform,
+  env = process.env,
+  existsImpl = fs.existsSync,
+} = {}) {
+  if (platform === 'win32') return { command: 'npm.cmd', prefixArgs: [], env: { ...env } };
+  const nodeDir = path.posix.dirname(String(execPath || ''));
+  const beside = path.posix.join(nodeDir, 'npm');
+  const command = nodeDir && existsImpl(beside) ? beside : 'npm';
+  const envPath = String(env?.PATH || '');
+  const childPath = envPath.split(':')[0] === nodeDir ? envPath : [nodeDir, envPath].filter(Boolean).join(':');
+  const suffix = '/lib/node_modules/@oar-sh/oar';
+  const root = String(packageRoot || '').replace(/\/+$/, '');
+  const prefixArgs = root.endsWith(suffix) && root.length > suffix.length
+    ? ['--prefix', root.slice(0, -suffix.length)]
+    : [];
+  return { command, prefixArgs, env: { ...env, PATH: childPath } };
+}
+
 /**
  * Provider CLIs `oar doctor` probes, with the args that answer fast. Cursor is
  * deliberately absent: the relay drives it through the bundled @cursor/sdk npm
@@ -89,6 +284,8 @@ export function renderDoctorReport({
   dbPath,
   dbSizeBytes,
   probes = [],
+  warnings = [],
+  tunnel = '',
 }) {
   const yesNo = (v) => (v ? 'yes' : 'no');
   const lines = [
@@ -101,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');
 }

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

@@ -0,0 +1,240 @@
+/**
+ * The terminal side of `oar`: line prompts and the menu. Everything reads
+ * from and writes to the stream pair it is given, so tests drive it with
+ * fake streams.
+ */
+
+import readline from 'node:readline';
+
+/** Ctrl+C (or a closed input) in a prompt or in the menu; `oar` exits 130 on it, without a message. */
+export class PromptAborted extends Error {
+  constructor() {
+    super('Aborted');
+    this.code = 'OAR_PROMPT_ABORTED';
+  }
+}
+
+export function askLine(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve, reject) => {
+    let rl;
+    try {
+      rl = readline.createInterface({ input, output, terminal: Boolean(input.isTTY) });
+    } catch {
+      // A terminal that refuses raw mode still reads whole lines.
+      rl = readline.createInterface({ input, output, terminal: false });
+    }
+    let settled = false;
+    const abort = () => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      output.write('\n');
+      reject(new PromptAborted());
+    };
+    rl.once('SIGINT', abort);
+    rl.once('close', abort);
+    rl.question(question, (answer) => {
+      settled = true;
+      rl.close();
+      resolve(String(answer).trim());
+    });
+  });
+}
+
+export async function askYesNo(question, { defaultYes = false, input, output } = {}) {
+  const answer = (await askLine(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `, { input, output })).toLowerCase();
+  return answer ? answer === 'y' || answer === 'yes' : defaultYes;
+}
+
+export function createPrompter({ input = process.stdin, output = process.stdout } = {}) {
+  return {
+    line: (question) => askLine(question, { input, output }),
+    yesNo: (question, options = {}) => askYesNo(question, { ...options, input, output }),
+  };
+}
+
+export const MENU_ENTRIES = Object.freeze([
+  { id: 'start', label: 'Start' },
+  { id: 'stop', label: 'Stop' },
+  { id: 'restart', label: 'Restart' },
+  { id: 'url', label: 'Show URL and QR code' },
+  { id: 'setup', label: 'Settings' },
+  { id: 'service', label: 'Install or remove the service' },
+  { id: 'update', label: 'Update' },
+  { id: 'doctor', label: 'Doctor' },
+  { id: 'copilot', label: 'Copilot session' },
+  { id: 'quit', label: 'Quit' },
+]);
+
+const RELAY_TEXT = {
+  running: 'relay running',
+  stopped: 'relay stopped',
+  taken: 'relay not reachable (its port is held by another program, or by a relay with other settings)',
+  unconfigured: 'not set up yet (choose Settings)',
+};
+const SERVICE_TEXT = {
+  active: 'installed, running',
+  installed: 'installed',
+  none: 'not installed',
+  unavailable: 'not available here',
+};
+
+export function menuUsesColor({ env = process.env, output = process.stdout } = {}) {
+  return Boolean(output?.isTTY) && !String(env?.NO_COLOR || '');
+}
+
+/** The menu as lines of text: the status header, then the entries, the selected one marked. */
+export function renderMenu({ status = {}, selected = 0, color = false } = {}) {
+  const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const relay = RELAY_TEXT[status.relay] || RELAY_TEXT.stopped;
+  const lines = [
+    `${paint(1, `OAR ${status.version || ''}`.trim())} · ${paint(status.relay === 'running' ? 32 : 31, relay)}`,
+  ];
+  if (status.url) lines.push(`  URL      ${status.url}`);
+  if (status.port) lines.push(`  Port     ${status.port}`);
+  if (status.access) lines.push(`  Access   ${status.access === 'lan' ? 'LAN' : 'this machine only'}`);
+  if (SERVICE_TEXT[status.service]) lines.push(`  Service  ${SERVICE_TEXT[status.service]}`);
+  for (const warning of status.warnings || []) lines.push(paint(33, `  ! ${warning}`));
+  lines.push('');
+  MENU_ENTRIES.forEach((entry, index) => {
+    const key = entry.id === 'quit' ? 'q' : String(index + 1);
+    const text = `${index === selected ? '>' : ' '} ${key}  ${entry.label}`;
+    lines.push(index === selected ? paint(7, text) : text);
+  });
+  lines.push('', 'Arrow keys and Enter, or a digit, to choose; q to quit.');
+  return lines;
+}
+
+/** One chunk of raw input as a menu key: 'up', 'down', 'enter', 'quit', 'interrupt', an entry index, or null. */
+export function readMenuKey(chunk) {
+  const key = String(chunk);
+  if (key === '\x03' || key === '\x04') return 'interrupt';
+  if (key === '\x1b[A' || key === '\x1bOA' || key === 'k') return 'up';
+  if (key === '\x1b[B' || key === '\x1bOB' || key === 'j') return 'down';
+  if (key === '\r' || key === '\n') return 'enter';
+  if (key === 'q' || key === 'Q') return 'quit';
+  if (/^[1-9]$/.test(key)) return Number(key) - 1;
+  return null;
+}
+
+/** Reads raw key presses until `onKey` returns a value; the terminal is back in line mode on every way out. */
+function readKeys({ input, onKey }) {
+  return new Promise((resolve, reject) => {
+    const finish = (settle, value) => {
+      input.removeListener('data', onData);
+      input.removeListener('end', onEnd);
+      try { input.setRawMode(false); } catch {}
+      input.pause();
+      settle(value);
+    };
+    const onEnd = () => finish(reject, new PromptAborted());
+    const onData = (chunk) => {
+      let result;
+      try { result = onKey(readMenuKey(chunk)); } catch (error) { finish(reject, error); return; }
+      if (result !== undefined) finish(resolve, result);
+    };
+    input.on('data', onData);
+    input.once('end', onEnd);
+    try {
+      input.setRawMode(true);
+      input.resume();
+    } catch (error) {
+      finish(reject, error);
+    }
+  });
+}
+
+/**
+ * Runs the menu until Quit or Ctrl+C. `loadStatus()` returns the header's
+ * status before each drawing; `actions[id](status)` runs an entry and may
+ * return `{ exit: true }` to leave the menu. An input without raw mode gets
+ * the same list with a numbered prompt.
+ */
+export async function runMenu({
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+  loadStatus = async () => ({}),
+  actions = {},
+} = {}) {
+  const color = menuUsesColor({ env, output });
+  let rawMode = typeof input.setRawMode === 'function';
+  let selected = 0;
+  const draw = (status) => {
+    output.write(`${output.isTTY ? '\x1b[2J\x1b[H' : ''}${renderMenu({ status, selected, color }).join('\n')}\n`);
+  };
+  const pickByKey = (status) => readKeys({
+    input,
+    onKey: (key) => {
+      if (key === 'interrupt') throw new PromptAborted();
+      if (key === 'quit') return MENU_ENTRIES.length - 1;
+      if (key === 'enter') return selected;
+      if (typeof key === 'number') {
+        selected = key;
+        return selected;
+      }
+      if (key === 'up' || key === 'down') {
+        selected = (selected + (key === 'up' ? MENU_ENTRIES.length - 1 : 1)) % MENU_ENTRIES.length;
+        draw(status);
+      }
+      return undefined;
+    },
+  });
+  const pickByNumber = async () => {
+    for (;;) {
+      const answer = (await askLine('Choose (1-9, q): ', { input, output })).toLowerCase();
+      if (answer === 'q') return MENU_ENTRIES.length - 1;
+      if (/^[1-9]$/.test(answer)) return Number(answer) - 1;
+    }
+  };
+
+  try {
+    for (;;) {
+      const status = await loadStatus();
+      draw(status);
+      let choice;
+      try {
+        choice = rawMode ? await pickByKey(status) : await pickByNumber();
+      } catch (error) {
+        if (error instanceof PromptAborted || !rawMode) throw error;
+        // The terminal refused raw mode.
+        rawMode = false;
+        choice = await pickByNumber();
+      }
+      selected = choice;
+      const entry = MENU_ENTRIES[choice];
+      if (entry.id === 'quit') return { code: 0, reason: 'menu-quit' };
+      output.write('\n');
+      let result = null;
+      try {
+        result = await actions[entry.id]?.(status);
+      } catch (error) {
+        // Ctrl+C inside an entry (a setup question) leaves that entry, not
+        // the menu.
+        if (error instanceof PromptAborted) {
+          output.write('\n');
+          continue;
+        }
+        output.write(`[oar] ${error?.message || error}\n`);
+      }
+      if (result?.exit) return { code: result.code ?? 0, reason: 'menu-exit' };
+      output.write('\n');
+      if (rawMode) {
+        output.write('Press a key to go back to the menu. ');
+        await readKeys({
+          input,
+          onKey: (key) => {
+            if (key === 'interrupt') throw new PromptAborted();
+            return true;
+          },
+        });
+      } else {
+        await askLine('Press Enter to go back to the menu. ', { input, output });
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof PromptAborted)) throw error;
+    output.write('\n');
+    return { code: 130, reason: 'interrupted' };
+  }
+}

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

@@ -0,0 +1,129 @@
+/**
+ * What `oar` needs to know about WSL. A distro in WSL's default (NAT)
+ * networking has its own network namespace: a port a Windows program listens
+ * on looks free inside the distro, and a Windows browser's `localhost:<port>`
+ * then reaches the Windows program, not the relay in the distro. Windows is
+ * asked through interop; every failure means "unknown" and is treated like a
+ * plain Linux host.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const INTEROP_TIMEOUT_MS = 4000;
+// WSL's own localhost forwarders listen on Windows for every port a distro
+// listens on, so they stand for the distro's program, not for a Windows one.
+const WSL_FORWARDER_RE = /^wsl(relay|host)\.exe$/i;
+
+export function isWsl({ env = process.env, platform = process.platform, readFileImpl = fs.readFileSync } = {}) {
+  if (platform !== 'linux') return false;
+  if (String(env?.WSL_DISTRO_NAME || env?.WSL_INTEROP || '').trim()) return true;
+  try {
+    return /microsoft|wsl/i.test(String(readFileImpl('/proc/sys/kernel/osrelease', 'utf8')));
+  } catch {
+    return false;
+  }
+}
+
+/** The Windows system folder as the distro sees it: `[automount] root` of /etc/wsl.conf, else /mnt/. */
+export function windowsSystemDir({ readFileImpl = fs.readFileSync } = {}) {
+  let root = '/mnt/';
+  try {
+    let section = '';
+    for (const raw of String(readFileImpl('/etc/wsl.conf', 'utf8')).split(/\r?\n/)) {
+      const line = raw.trim();
+      const header = line.match(/^\[(.+)\]$/);
+      if (header) section = header[1].trim().toLowerCase();
+      const pair = section === 'automount' && line.match(/^root\s*=\s*(.+)$/i);
+      if (pair) root = pair[1].trim().replace(/^["']|["']$/g, '') || root;
+    }
+  } catch {
+    // No wsl.conf: the default mount root.
+  }
+  return path.posix.join(root, 'c', 'Windows', 'System32');
+}
+
+function runWindowsTool(name, args, { spawnSyncImpl = spawnSync, readFileImpl = fs.readFileSync } = {}) {
+  try {
+    const result = spawnSyncImpl(path.posix.join(windowsSystemDir({ readFileImpl }), name), args, {
+      encoding: 'utf8',
+      timeout: INTEROP_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return result && !result.error && result.status === 0 ? String(result.stdout || '') : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Listening TCP ports in `netstat -ano` output, each with the process ids
+ * that hold it. Windows prints the state word in the system language, so a
+ * listener is recognised by its shape instead: a TCP row whose remote address
+ * is the all-zero one (`0.0.0.0:0` or `[::]:0`). Only listeners a browser's
+ * `localhost` reaches count: the loopback and the any-address ones.
+ */
+export function parseNetstatListeners(text) {
+  const listeners = new Map();
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const row = line.match(/^\s*TCP\s+(\S+):(\d+)\s+(?:0\.0\.0\.0|\[::\]):0\s+.*?(\d+)\s*$/);
+    if (!row || !['0.0.0.0', '127.0.0.1', '[::]', '[::1]'].includes(row[1])) continue;
+    const port = Number(row[2]);
+    const pids = listeners.get(port) || [];
+    if (!pids.includes(Number(row[3]))) pids.push(Number(row[3]));
+    listeners.set(port, pids);
+  }
+  return listeners;
+}
+
+/** Port → process ids of the Windows listeners, or null when Windows cannot be asked. */
+export function windowsListeningPorts(options = {}) {
+  const output = runWindowsTool('netstat.exe', ['-ano'], options);
+  return output === null ? null : parseNetstatListeners(output);
+}
+
+function windowsProcessName(pid, options) {
+  const output = runWindowsTool('tasklist.exe', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], options);
+  return output?.match(/^"([^"]+)"/m)?.[1] || '';
+}
+
+/**
+ * A function `(port) => name | null`: the Windows program that holds the port,
+ * or null when none does, when this is not WSL, or when Windows cannot be
+ * asked. The listener list is read once, on the first call.
+ */
+export function createWindowsPortCheck(options = {}) {
+  if (!isWsl(options)) return () => null;
+  let listeners;
+  return (port) => {
+    if (listeners === undefined) listeners = windowsListeningPorts(options);
+    for (const pid of listeners?.get(Number(port)) || []) {
+      const name = windowsProcessName(pid, options);
+      if (!WSL_FORWARDER_RE.test(name)) return name || 'a Windows program';
+    }
+    return null;
+  };
+}
+
+/**
+ * True in a WSL distro whose network is its own (NAT): its LAN address is
+ * internal to WSL. Mirrored networking shares the addresses of Windows.
+ */
+export function isWslNat(options = {}) {
+  if (!isWsl(options)) return false;
+  try {
+    const result = (options.spawnSyncImpl || spawnSync)('wslinfo', ['--networking-mode'], {
+      encoding: 'utf8',
+      timeout: INTEROP_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return String(result?.stdout || '').trim().toLowerCase() !== 'mirrored';
+  } catch {
+    return true;
+  }
+}
+
+export function windowsPortWarning(port, holder) {
+  return `Windows holds port ${port} (${holder}): a browser on Windows reaches that program, not this relay. Pick another port: oar setup --port N`;
+}