replica-bridge 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,14 @@
-# Temporary Holding Version
+# replica-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lets the ChatReplica iPhone app use Codex on this computer. Needs Codex installed and signed in (`codex login`).
+
+    npx replica-bridge
+
+The first run sets this computer up with the relay, shows a QR code to scan in the app (远程 › 添加连接 › 配对新设备),
+then offers to keep running in the background and start at login (macOS launchd, Linux systemd, Windows Task
+Scheduler), so the terminal can be closed. Run it again for the status.
+
+    npx replica-bridge pair         pair another phone
+    npx replica-bridge uninstall    stop and remove the background service
+
+`npx replica-bridge --help` lists the other commands.

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "replica-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Lets the ChatReplica iPhone app use Codex on this computer through a relay, end-to-end encrypted.",
+  "type": "module",
+  "bin": {
+    "replica-bridge": "src/bridge/main.js"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "dependencies": {
+    "qrcode": "1.5.4",
+    "ws": "8.18.3"
+  },
+  "license": "UNLICENSED"
+}

package/src/bridge/command.js

@@ -0,0 +1,28 @@
+// Running Codex, npm and the service managers the same way on macOS, Linux and Windows.
+import { spawn, spawnSync } from "node:child_process";
+                                                                                       
+
+/** One argument as cmd.exe reads it. */
+export function quoteForCmd(arg        )         {
+  return /^[\w\-.:\\/=@]+$/.test(arg) ? arg : `"${arg.replace(/"/g, '""')}"`;
+}
+
+/**
+ * On Windows npm installs commands such as codex as `codex.cmd`, which Node runs only through cmd.exe
+ * (spawn without a shell fails with EINVAL or ENOENT), so the command line goes through the shell there.
+ */
+export function spawnCommand(command        , args          , options               = {})               {
+  if (process.platform !== "win32") return spawn(command, args, options);
+  return spawn([command, ...args].map(quoteForCmd).join(" "), [], { ...options, shell: true, windowsHide: true });
+}
+
+export function spawnCommandSync(command        , args          , options                   = {}) {
+  if (process.platform !== "win32") return spawnSync(command, args, options);
+  return spawnSync([command, ...args].map(quoteForCmd).join(" "), [], { ...options, shell: true, windowsHide: true });
+}
+
+/** Stops a command from spawnCommand; on Windows that is cmd.exe, so the whole tree goes (taskkill /T). */
+export function killCommand(child              ) {
+  if (process.platform === "win32" && child.pid && child.exitCode === null) spawnSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+  else child.kill();
+}

package/src/bridge/enroll.js

@@ -0,0 +1,39 @@
+// First run: make this computer's key pair and enroll it, anonymously, with a relay.
+import fs from "node:fs";
+import os from "node:os";
+import { b64url, generateKeyPair } from "../protocol.js";
+import { relayRequest } from "../http.js";
+import { defaultEnvPath, loadRelayConfig } from "../relay/config.js";
+import { loadState, saveState } from "./state.js";
+                                              
+
+/** The project's public relay, which the app also signs in to by default (Sources/Core/RelayPairing.swift). */
+export const PUBLIC_RELAY = "https://agens.office-cli.onl";
+
+/** With no --relay: REPLICA_RELAY, else the relay on this machine over loopback, else the public relay. */
+export function defaultRelayURL()         {
+  if (process.env.REPLICA_RELAY) return process.env.REPLICA_RELAY;
+  return fs.existsSync(defaultEnvPath()) ? `http://127.0.0.1:${loadRelayConfig().port}` : PUBLIC_RELAY;
+}
+
+export async function enroll(relay        , options                                          = {})                       {
+  const keys = generateKeyPair();
+  const hostName = options.name ?? os.hostname();
+  const { hostId, hostToken } = await relayRequest                                       (relay, "POST", "/v1/hosts/enroll", { body: { publicKey: b64url(keys.publicKey), name: hostName } });
+  const state              = { relay, publicRelay: options.publicRelay, hostId, hostToken, hostName, hostPrivateKey: b64url(keys.privateKey), hostPublicKey: b64url(keys.publicKey), devices: [] };
+  saveState(state);
+  return state;
+}
+
+/** The saved state, enrolling first if this computer never has. */
+export async function ensureEnrolled(relay                    , say                        , name         )                       {
+  try {
+    return loadState();
+  } catch (error) {
+    if (!/not set up yet/.test((error         ).message)) throw error;
+  }
+  const url = relay ?? defaultRelayURL();
+  const state = await enroll(url, { name });
+  say(`Set up ${state.hostName} with ${url} (${state.hostId}).`);
+  return state;
+}

package/src/bridge/install.js

@@ -0,0 +1,253 @@
+// Keeping the bridge running after its terminal closes, the way Codex keeps its app-server: a per-user background
+// service that starts at login and restarts when it fails. macOS: a launchd agent. Linux: a systemd user service.
+// Windows: a Task Scheduler task at logon that runs a hidden script, which restarts the bridge when it exits.
+// The service runs a copy installed under ~/.config/replica-bridge/app, not the npx cache, which npm may clear.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnCommandSync } from "./command.js";
+import { bridgeHome } from "./state.js";
+
+export const PACKAGE_VERSION         = JSON.parse(fs.readFileSync(path.resolve(import.meta.dirname, "../../package.json"), "utf8")).version;
+
+                                                                                                                                  
+
+                              
+                            
+                                                                                                       
+                
+               
+                     
+                                                          
+                    
+                              
+              
+ 
+
+                              
+                                             
+                                                                                   
+                                                                     
+                                                                       
+                                        
+                
+ 
+
+export const serviceLabel = () => process.env.REPLICA_BRIDGE_LABEL ?? "replica-bridge";
+export const logPath = (home = bridgeHome()) => path.join(home, "bridge.log");
+const infoPath = () => path.join(bridgeHome(), "service.json");
+const pidPath = () => path.join(bridgeHome(), "bridge.pid");
+
+const xml = (text        ) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/** systemd unit-file quoting: specifiers (%) doubled, backslashes and quotes escaped. */
+const unitQuote = (text        ) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/%/g, "%%")}"`;
+/** A VBScript string literal. */
+const vbs = (text        ) => `"${text.replace(/"/g, '""')}"`;
+
+/** The service files and the commands that load and unload them; pure, so each platform can be checked anywhere. */
+export function servicePlan(spec             )              {
+  const log = logPath(spec.bridgeHome);
+  switch (spec.platform) {
+    case "darwin": {
+      const label = `com.chatreplica.${spec.label}`;
+      const plist = path.join(spec.home, "Library", "LaunchAgents", `${label}.plist`);
+      const target = `gui/${spec.uid}`;
+      const env = Object.entries(spec.env).map(([k, v]) => `    <key>${xml(k)}</key><string>${xml(v)}</string>`).join("\n");
+      const content = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${xml(label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${spec.program.map((a) => `    <string>${xml(a)}</string>`).join("\n")}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${env}
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>10</integer>
+  <key>ProcessType</key><string>Background</string>
+  <key>StandardOutPath</key><string>${xml(log)}</string>
+  <key>StandardErrorPath</key><string>${xml(log)}</string>
+</dict>
+</plist>
+`;
+      return {
+        files: [{ path: plist, content }],
+        install: [
+          { command: "launchctl", args: ["bootout", `${target}/${label}`], optional: true },
+          { command: "launchctl", args: ["bootstrap", target, plist] },
+        ],
+        uninstall: [{ command: "launchctl", args: ["bootout", `${target}/${label}`], optional: true }],
+        where: `launchd agent ${label} (${plist})`,
+      };
+    }
+    case "linux": {
+      const unit = `${spec.label}.service`;
+      const file = path.join(spec.home, ".config", "systemd", "user", unit);
+      const content = `[Unit]
+Description=replica-bridge: ChatReplica phones use Codex on this computer
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=${spec.program.map(unitQuote).join(" ")}
+Restart=on-failure
+RestartSec=10
+${Object.entries(spec.env).map(([k, v]) => `Environment=${unitQuote(`${k}=${v}`)}`).join("\n")}
+StandardOutput=append:${log}
+StandardError=append:${log}
+
+[Install]
+WantedBy=default.target
+`;
+      return {
+        files: [{ path: file, content }],
+        install: [
+          { command: "systemctl", args: ["--user", "daemon-reload"] },
+          { command: "systemctl", args: ["--user", "enable", unit] },
+          { command: "systemctl", args: ["--user", "restart", unit] },
+        ],
+        uninstall: [
+          { command: "systemctl", args: ["--user", "disable", "--now", unit], optional: true },
+        ],
+        where: `systemd user service ${unit} (${file})`,
+      };
+    }
+    case "win32": {
+      const script = path.join(spec.bridgeHome, "run-bridge.vbs");
+      // wscript shows no window; the loop brings the bridge back ten seconds after it fails. Exit code 0 means another
+      // bridge took this computer over (or it was told to stop), so the loop ends.
+      const content = [
+        `' replica-bridge background service (Task Scheduler task "${spec.label}"). Made by "replica-bridge install".`,
+        `Set shell = CreateObject("WScript.Shell")`,
+        ...Object.entries({ ...spec.env, REPLICA_BRIDGE_LOG: log }).map(([k, v]) => `shell.Environment("Process")(${vbs(k)}) = ${vbs(v)}`),
+        `Do`,
+        `  code = shell.Run(${vbs(spec.program.map((a) => `"${a}"`).join(" "))}, 0, True)`,
+        `  If code = 0 Then Exit Do`,
+        `  WScript.Sleep 10000`,
+        `Loop`,
+        "",
+      ].join("\r\n");
+      return {
+        files: [{ path: script, content }],
+        install: [
+          { command: "schtasks", args: ["/End", "/TN", spec.label], optional: true },
+          { command: "schtasks", args: ["/Create", "/F", "/TN", spec.label, "/SC", "ONLOGON", "/RL", "LIMITED", "/TR", `wscript.exe "${script}"`] },
+          { command: "schtasks", args: ["/Run", "/TN", spec.label] },
+        ],
+        uninstall: [
+          { command: "schtasks", args: ["/End", "/TN", spec.label], optional: true },
+          { command: "schtasks", args: ["/Delete", "/F", "/TN", spec.label], optional: true },
+        ],
+        where: `Task Scheduler task "${spec.label}" (${script})`,
+      };
+    }
+    default:
+      throw new Error(`no background service for ${spec.platform}: keep "replica-bridge start" running yourself`);
+  }
+}
+
+/** What the service passes on: PATH (so it finds codex and node) and the bridge's and Codex's own settings. */
+function serviceEnv()                         {
+  const env                         = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && (key === "PATH" || key === "Path" || /^(CODEX_|REPLICA_|RELAY_ENV$)/.test(key)) && key !== "REPLICA_BRIDGE_LOG") env[key] = value;
+  }
+  env.REPLICA_BRIDGE_SERVICE = "1";
+  return env;
+}
+
+/**
+ * The script the service runs. From npx (inside node_modules) a copy of this version is installed under
+ * ~/.config/replica-bridge/app, since npm may clear its npx cache; from a working copy, the working copy itself.
+ */
+function installedScript(say                        )         {
+  const current = process.argv[1] ? fs.realpathSync(process.argv[1]) : "";
+  if (!current.split(path.sep).includes("node_modules")) return current;
+  const app = path.join(bridgeHome(), "app");
+  const spec = process.env.REPLICA_BRIDGE_PACKAGE ?? `replica-bridge@${PACKAGE_VERSION}`;
+  say(`Installing ${spec} in ${app}…`);
+  fs.mkdirSync(app, { recursive: true });
+  // npx's own npm_* settings (a temporary prefix, for one) must not leak into this install.
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^npm_/i.test(key)));
+  const result = spawnCommandSync("npm", ["install", "--prefix", app, "--no-audit", "--no-fund", "--omit=dev", "--loglevel=error", spec], { stdio: "inherit", env });
+  if (result.status !== 0) throw new Error(`npm install ${spec} failed`);
+  return path.join(app, "node_modules", "replica-bridge", "src", "bridge", "main.js");
+}
+
+function run(steps                        ) {
+  for (const step of steps) {
+    const result = spawnCommandSync(step.command, step.args, { encoding: "utf8" });
+    if (result.status !== 0 && !step.optional) {
+      throw new Error(`${step.command} ${step.args.join(" ")} failed: ${(result.stderr || result.stdout || result.error?.message || "").toString().trim()}`);
+    }
+  }
+}
+
+export function readServiceInfo()                     {
+  try { return JSON.parse(fs.readFileSync(infoPath(), "utf8"))               ; } catch { return null; }
+}
+
+function spec(program          )              {
+  return { platform: process.platform, label: serviceLabel(), home: os.homedir(), bridgeHome: bridgeHome(), program, env: serviceEnv(), uid: os.userInfo().uid };
+}
+
+/** Installs (or replaces) the background service and starts it. `startArgs` are the options `start` keeps. */
+export function installService(startArgs          , say                        )              {
+  servicePlan(spec([])); // fails early on a platform without a service manager
+  stopRunning();
+  const program = [process.execPath, installedScript(say), "start", ...startArgs];
+  const plan = servicePlan(spec(program));
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  for (const file of plan.files) {
+    fs.mkdirSync(path.dirname(file.path), { recursive: true });
+    fs.writeFileSync(file.path, file.content);
+  }
+  run(plan.install);
+  const info              = { platform: process.platform, label: serviceLabel(), version: PACKAGE_VERSION, program, installedAt: new Date().toISOString() };
+  fs.writeFileSync(infoPath(), JSON.stringify(info, null, 2) + "\n");
+  return plan;
+}
+
+export function uninstallService()                     {
+  const info = readServiceInfo();
+  if (!info) return null;
+  const plan = servicePlan({ ...spec(info.program), label: info.label });
+  run(plan.uninstall);
+  stopRunning();
+  for (const file of plan.files) fs.rmSync(file.path, { force: true });
+  if (process.platform === "linux") run([{ command: "systemctl", args: ["--user", "daemon-reload"], optional: true }]);
+  fs.rmSync(infoPath(), { force: true });
+  return plan;
+}
+
+// MARK: The running service's pid, so `status` can tell whether it runs and a second bridge does not start beside it.
+
+export function writePid() {
+  fs.mkdirSync(bridgeHome(), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(pidPath(), String(process.pid));
+}
+
+export function clearPid() {
+  try { if (fs.readFileSync(pidPath(), "utf8").trim() === String(process.pid)) fs.rmSync(pidPath()); } catch { /* gone */ }
+}
+
+/** The background bridge's pid while it runs. */
+export function runningPid()                {
+  let pid        ;
+  try { pid = Number(fs.readFileSync(pidPath(), "utf8").trim()); } catch { return null; }
+  if (!pid || pid === process.pid) return null;
+  try { process.kill(pid, 0); return pid; } catch (error) { return (error                         ).code === "EPERM" ? pid : null; }
+}
+
+/** The service manager stops its own process; on Windows the loop's bridge is left, so it goes by pid. */
+function stopRunning() {
+  const pid = runningPid();
+  if (!pid) return;
+  try { process.kill(pid); } catch { /* already gone */ }
+  fs.rmSync(pidPath(), { force: true });
+}

package/src/bridge/main.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+// replica-bridge: runs on the computer that has Codex. See docs/RELAY.md.
+//   (no command)   what `npx replica-bridge` runs. The first time: set this computer up with the relay, show a QR
+//                  code, and once a phone is paired offer to keep the bridge running in the background (install).
+//                  Later: show the status, updating the background service when this is a newer version.
+//                  [--relay <url>] [--name <name>] [--pair] [--install | --no-install] [--codex <path>]
+//   pair [--relay <url>] [--confirm] [--yes] [--png <file>] [--timeout <seconds>]
+//   install | uninstall | status
+//   start [--codex <path>] [--stream-ttl <seconds>] [--no-login-shell]   the bridge in this terminal
+//   init [--relay <url>] [--public-url <url>] [--name <name>]
+//   config [--public-url <url>]
+//   devices
+//   revoke <deviceId>
+import fs from "node:fs";
+import readline from "node:readline/promises";
+import { parseArgs, format } from "node:util";
+import { relayRequest } from "../http.js";
+import { spawnCommandSync } from "./command.js";
+import { defaultRelayURL, enroll, ensureEnrolled } from "./enroll.js";
+import { PACKAGE_VERSION, clearPid, installService, logPath, readServiceInfo, runningPid, servicePlan, uninstallService, writePid } from "./install.js";
+import { pair, publicRelayURL } from "./pair.js";
+import { BridgeService } from "./service.js";
+import { loadState, saveState } from "./state.js";
+
+// A leading option means no command: `replica-bridge --pair` is the default command with --pair.
+const argv = process.argv.slice(2);
+const [command, ...rest] = argv[0]?.startsWith("-") ? [undefined, ...argv] : argv;
+const { values, positionals } = parseArgs({
+  args: rest,
+  allowPositionals: true,
+  options: {
+    relay: { type: "string" },
+    "public-url": { type: "string" },
+    name: { type: "string" },
+    confirm: { type: "boolean", default: false },
+    yes: { type: "boolean", default: false },
+    png: { type: "string" },
+    timeout: { type: "string", default: "600" },
+    pair: { type: "boolean", default: false },
+    install: { type: "boolean", default: false },
+    "no-install": { type: "boolean", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", short: "v", default: false },
+    codex: { type: "string" },
+    "stream-ttl": { type: "string", default: "1800" },
+    "no-login-shell": { type: "boolean", default: false },
+  },
+});
+
+const usage = `replica-bridge ${PACKAGE_VERSION}: lets the ChatReplica app use Codex on this computer (docs/RELAY.md)
+  npx replica-bridge              the only command most people need: sets up, pairs a phone, keeps running
+                                  in the background; run again for the status
+  npx replica-bridge pair         pair another phone
+  npx replica-bridge uninstall    stop and remove the background service
+Others: status, install, start (in this terminal), init, config, devices, revoke <id>.
+The relay is ${defaultRelayURL()} unless --relay or REPLICA_RELAY says otherwise.`;
+
+// The Windows service has no terminal to write to: its output goes to the log file it names.
+if (process.env.REPLICA_BRIDGE_LOG) {
+  const log = fs.createWriteStream(process.env.REPLICA_BRIDGE_LOG, { flags: "a" });
+  console.log = console.warn = console.error = (...args           ) => { log.write(format(...args) + "\n"); };
+}
+
+/** The options `start` keeps when the background service runs it. */
+function startArgs()           {
+  const args           = [];
+  if (values.codex) args.push("--codex", values.codex);
+  if (values["no-login-shell"]) args.push("--no-login-shell");
+  if (values["stream-ttl"] !== "1800") args.push("--stream-ttl", values["stream-ttl"] );
+  return args;
+}
+
+function startBridge()                {
+  // Exit 0: the background services restart the bridge only when it fails, so the newer bridge keeps the computer.
+  const service = new BridgeService({ codexPath: values.codex, loginShell: !values["no-login-shell"], streamTTLSeconds: Number(values["stream-ttl"]), onReplaced: () => process.exit(0) });
+  service.start();
+  return service;
+}
+
+/** Warns, without stopping, when Codex does not answer the way the bridge will run it (through the login shell). */
+function checkCodex() {
+  const codex = values.codex ?? "codex";
+  const loginShell = process.platform !== "win32" && !values["no-login-shell"] && process.env.SHELL;
+  const result = loginShell
+    ? spawnCommandSync(process.env.SHELL , ["-lic", `"$0" --version`, codex], { encoding: "utf8", timeout: 15_000 })
+    : spawnCommandSync(codex, ["--version"], { encoding: "utf8", timeout: 15_000 });
+  if (result.status === 0) return;
+  console.warn(`Codex did not answer "${codex} --version". Install it (npm install -g @openai/codex) and sign in (codex login); the phone cannot use this computer until then.`);
+}
+
+function serviceSupported()          {
+  try { servicePlan({ platform: process.platform, label: "x", home: "/", bridgeHome: "/", program: [], env: {}, uid: 0 }); return true; } catch { return false; }
+}
+
+async function ask(question        )                   {
+  const prompt = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try { return !/^n(o)?$/i.test((await prompt.question(question)).trim()); } finally { prompt.close(); }
+}
+
+/** --install, --no-install, or ask in a terminal; never without one. */
+async function wantBackground()                   {
+  if (values["no-install"] || !serviceSupported()) return false;
+  if (values.install) return true;
+  if (!process.stdin.isTTY) return false;
+  return ask("Keep it running in the background and start it at login, so you can close this terminal? [Y/n] ");
+}
+
+function install()       {
+  const plan = installService(startArgs(), console.log);
+  console.log(`Running in the background: ${plan.where}. It starts at login and comes back if it stops, so this terminal can be closed.`);
+  console.log(`Log: ${logPath()}. Remove it with "npx replica-bridge uninstall".`);
+  if (process.platform === "linux") console.log(`To keep it running while you are logged out: loginctl enable-linger ${process.env.USER ?? "$USER"}`);
+}
+
+async function pairOrExplain() {
+  try {
+    await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+  } catch (error) {
+    console.error(`replica-bridge: ${(error         ).message}. Pair later with "npx replica-bridge pair".`);
+  }
+}
+
+function status() {
+  let state;
+  try { state = loadState(); } catch { console.log(`Not set up yet: run "npx replica-bridge".`); return; }
+  const info = readServiceInfo();
+  const pid = runningPid();
+  console.log(`${state.hostName} (${state.hostId}), relay ${state.relay}`);
+  console.log(`Owner: ${state.owner ? `${state.owner.login} (${state.owner.provider})` : "none yet"}; paired phones: ${state.devices.map((d) => d.name).join(", ") || "none"}`);
+  if (info) console.log(`Background service ${info.version}: ${pid ? `running (pid ${pid})` : "installed, not running right now"}. Log: ${logPath()}`);
+  else console.log(pid ? `Running (pid ${pid}).` : `Not running: "npx replica-bridge" sets up the background service.`);
+}
+
+async function main() {
+  if (values.version) { console.log(PACKAGE_VERSION); return; }
+  if (values.help || command === "help") { console.log(usage); return; }
+  switch (command) {
+    case undefined:
+    case "up": {
+      const installed = readServiceInfo();
+      if (installed && !values.pair && !values.install) {
+        if (installed.version !== PACKAGE_VERSION) {
+          console.log(`Updating the background service from ${installed.version} to ${PACKAGE_VERSION}.`);
+          install();
+        }
+        status();
+        break;
+      }
+      checkCodex();
+      const state = await ensureEnrolled(values.relay, console.log, values.name);
+      if (installed && !values.install) { await pairOrExplain(); break; } // the background service serves the phone
+      if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()}); stop it first`);
+      let bridge = startBridge();
+      if (values.pair || !state.devices.length) await pairOrExplain();
+      if (loadState().devices.length && await wantBackground()) {
+        // One bridge per computer: the relay keeps only the newest connection for it.
+        bridge.stop();
+        try {
+          install();
+          process.exit(0);
+        } catch (error) {
+          console.error(`replica-bridge: could not set up the background service: ${(error         ).message}`);
+          bridge = startBridge();
+        }
+      }
+      for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
+      console.log(`Running in this terminal: paired phones can use Codex on ${state.hostName} until it closes (Ctrl-C stops it).`);
+      break;
+    }
+    case "install":
+      await ensureEnrolled(values.relay, console.log, values.name);
+      install();
+      break;
+    case "uninstall": {
+      const plan = uninstallService();
+      console.log(plan ? `Removed the background service (${plan.where}). This computer stays paired; "npx replica-bridge" sets it up again.` : "No background service is installed.");
+      break;
+    }
+    case "status":
+      status();
+      break;
+    case "init": {
+      const relay = values.relay ?? defaultRelayURL();
+      const state = await enroll(relay, { name: values.name, publicRelay: values["public-url"] });
+      console.log(`Set up ${state.hostName} as ${state.hostId}. Next: "npx replica-bridge".`);
+      console.log("Nobody owns it yet: the first phone that scans its QR code and is approved here claims it.");
+      break;
+    }
+    case "config": {
+      const state = loadState();
+      if (values["public-url"] !== undefined) state.publicRelay = values["public-url"] || undefined;
+      saveState(state);
+      console.log(`relay ${state.relay}\npublic URL in QR codes ${publicRelayURL(state)}${state.publicRelay ? "" : " (from the relay's env file)"}\nhost ${state.hostName} (${state.hostId})\nowner ${state.owner ? `${state.owner.login} (${state.owner.provider})` : "none yet: pair a phone to claim it"}`);
+      break;
+    }
+    case "pair":
+      await ensureEnrolled(values.relay, console.log, values.name);
+      await pair({ confirm: values.confirm, yes: values.yes, timeoutSeconds: Number(values.timeout), pngPath: values.png });
+      if (!runningPid()) console.log(`Nothing serves this computer right now: run "npx replica-bridge" so the phone can connect.`);
+      break;
+    case "start": {
+      await ensureEnrolled(values.relay, console.log, values.name);
+      const asService = process.env.REPLICA_BRIDGE_SERVICE === "1";
+      if (runningPid()) throw new Error(`a bridge already runs for this computer (pid ${runningPid()})${asService ? "" : '; "npx replica-bridge uninstall" stops the background one'}`);
+      const bridge = startBridge();
+      if (asService) { writePid(); process.on("exit", clearPid); }
+      for (const signal of ["SIGINT", "SIGTERM"]         ) process.on(signal, () => { bridge.stop(); process.exit(0); });
+      break;
+    }
+    case "devices": {
+      const state = loadState();
+      const { owner, devices } = await relayRequest                                                                                                                                                                                   (state.relay, "GET", "/v1/host/devices", { token: state.hostToken });
+      console.log(owner ? `Owner: ${owner.login} (${owner.provider})` : "No owner yet.");
+      if (!devices.length) console.log("No paired phones.");
+      for (const d of devices) console.log(`${d.deviceId}  ${d.name} (${d.login})  paired ${new Date(d.createdAt).toLocaleString()}  ${d.revokedAt ? "removed" : d.online ? "online" : "offline"}`);
+      break;
+    }
+    case "revoke": {
+      const deviceId = positionals[0];
+      if (!deviceId) throw new Error("usage: replica-bridge revoke <deviceId>");
+      const state = loadState();
+      await relayRequest(state.relay, "DELETE", `/v1/host/devices/${encodeURIComponent(deviceId)}`, { token: state.hostToken });
+      state.devices = state.devices.filter((d) => d.deviceId !== deviceId);
+      saveState(state);
+      console.log(`Removed ${deviceId} from this computer.`);
+      break;
+    }
+    default:
+      console.log(usage);
+      process.exitCode = 1;
+  }
+}
+
+main().catch((error) => {
+  console.error(`replica-bridge: ${(error         ).message}`);
+  process.exit(1);
+});