rechrome 1.6.0 → 1.8.0

package/rech.js

@@ -2,7 +2,7 @@
 
 import { file } from "bun";
 import { randomBytes } from "crypto";
-import { mkdirSync, appendFileSync, existsSync } from "fs";
+import { mkdirSync, appendFileSync, existsSync, realpathSync, accessSync, constants as fsConstants } from "fs";
 import { hostname } from "os";
 import { join, basename, dirname } from "path";
 
@@ -11,33 +11,58 @@ export const DEFAULT_PORT = 13775;
 export const RECH_DIR = join(import.meta.dir, ".rech");
 export const LOG_DIR = join(RECH_DIR, "logs");
 
-const envFile = join(import.meta.dir, ".env.local");
+const RECH_HOME_DIR = join(process.env.HOME!, ".rech");
+const TOKENS_FILE = join(RECH_HOME_DIR, "tokens.json");
+
+type TokenEntry = { extensionId: string; token: string; profileDir: string; userDataDir?: string };
+
+async function readTokenRegistry(): Promise<Record<string, TokenEntry>> {
+  const raw = await file(TOKENS_FILE).text().catch(() => "{}");
+  try { return JSON.parse(raw); } catch { return {}; }
+}
+
+async function saveTokenEntry(profileEmail: string, entry: TokenEntry): Promise<void> {
+  mkdirSync(RECH_HOME_DIR, { recursive: true });
+  const registry = await readTokenRegistry();
+  registry[profileEmail] = entry;
+  await Bun.write(TOKENS_FILE, JSON.stringify(registry, null, 2) + "\n");
+}
 
-async function loadEnvFile(path: string): Promise<boolean> {
-  const envRaw = await file(path).text().catch(() => "");
-  if (!envRaw) return false;
-  let hasKey = false;
-  for (const line of envRaw.split("\n")) {
-    const m = line.match(/^\s*([^#=]+?)\s*=\s*(.*?)\s*$/);
-    if (m) {
+const envFile = join(import.meta.dir, ".env.local");
+const globalEnvFile = join(process.env.HOME || "~", ".env.local");
+
+// Walk CWD→root loading env files nearest-first; per-key: closest file wins, farther files skip.
+// At each level .rechrome/.env.local is checked before .env.local (rechrome-specific overrides general).
+export async function loadNearestEnv(extraFallbacks: string[] = []) {
+  const seen = new Set<string>();
+  const applyFile = async (path: string) => {
+    const raw = await file(path).text().catch(() => "");
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^\s*([^#=\s][^#=]*?)\s*=\s*(.*?)\s*$/);
+      if (!m || m[1].startsWith("#")) continue;
+      if (seen.has(m[1])) continue;
+      seen.add(m[1]);
       process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
-      if (m[1] === ENV_KEY) hasKey = true;
     }
-  }
-  return hasKey;
-}
+  };
 
-async function loadEnv() {
-  // Walk up from cwd first — project-local .env.local takes priority
   let dir = process.cwd();
+  const dirs: string[] = [];
   while (true) {
-    if (await loadEnvFile(join(dir, ".env.local"))) break;
+    dirs.push(dir);
     const parent = join(dir, "..");
     if (parent === dir) break;
     dir = parent;
   }
-  // Fall back to script dir's .env.local
-  if (!process.env[ENV_KEY]) await loadEnvFile(envFile);
+  for (const d of dirs) {
+    await applyFile(join(d, ".rechrome", ".env.local"));
+    await applyFile(join(d, ".env.local"));
+  }
+  for (const f of extraFallbacks) await applyFile(f);
+}
+
+async function loadEnv() {
+  await loadNearestEnv();
 }
 // Shell-set passthrough vars survive .env.local loading
 const _shellPassthrough: Record<string, string> = {};
@@ -48,12 +73,9 @@ await loadEnv();
 Object.assign(process.env, _shellPassthrough);
 
 import { watch } from "node:fs";
-if (existsSync(envFile)) {
-  watch(envFile, async () => {
-    log(".env.local changed, reloading");
-    await loadEnv();
-  });
-}
+const envWatcher = existsSync(envFile)
+  ? watch(envFile, async () => { log(".env.local changed, reloading"); await loadEnv(); })
+  : null;
 
 
 export const PASSTHROUGH_ENV_KEYS = [
@@ -61,8 +83,14 @@ export const PASSTHROUGH_ENV_KEYS = [
   "PLAYWRIGHT_MCP_EXTENSION_TOKEN",
   "PLAYWRIGHT_MCP_PROFILE_DIRECTORY",
   "PLAYWRIGHT_MCP_USER_DATA_DIR",
+  "PWMCP_TEST_CONNECTION_TIMEOUT",
 ] as const;
 
+function isReadable(p?: string): boolean {
+  if (!p) return false;
+  try { accessSync(p, fsConstants.R_OK); return true; } catch { return false; }
+}
+
 export function log(msg: string) {
   mkdirSync(LOG_DIR, { recursive: true });
   const ts = new Date().toISOString();
@@ -92,13 +120,13 @@ export function parseUrl(raw: string) {
 export async function getOrCreateUrl(): Promise<string> {
   if (process.env[ENV_KEY]) return process.env[ENV_KEY];
   const key = randomBytes(9).toString("base64url"); // 12 chars
-  const url = `http://${key}@${hostname()}:${DEFAULT_PORT}`;
+  const url = `http://${key}@127.0.0.1:${DEFAULT_PORT}`;
   const newLine = `${ENV_KEY}=${url}`;
-  const envRaw = await file(envFile)
-    .text()
-    .catch(() => "");
-  const content = envRaw.trimEnd() ? envRaw.trimEnd() + "\n" + newLine + "\n" : newLine + "\n";
-  Bun.write(envFile, content);
+  // Write to ~/.env.local so it's not shadowed by project .env.local
+  const envRaw = await file(globalEnvFile).text().catch(() => "");
+  const lines = envRaw.trimEnd().split("\n").filter(l => !l.startsWith(`${ENV_KEY}=`));
+  const content = [...lines, newLine, ""].join("\n");
+  Bun.write(globalEnvFile, content);
   process.env[ENV_KEY] = url;
   return url;
 }
@@ -153,19 +181,34 @@ async function getClientIdentity(): Promise<{ gitUrl?: string; hostname?: string
   return { hostname: hostname(), cwd };
 }
 
-function getClientEnv(urlExtras?: { extensionId?: string; extensionToken?: string; profileDirectory?: string; userDataDir?: string }): Record<string, string> {
+async function getClientEnv(urlExtras?: { extensionId?: string; extensionToken?: string; profileDirectory?: string; userDataDir?: string }): Promise<Record<string, string>> {
   const env: Record<string, string> = {};
   for (const key of PASSTHROUGH_ENV_KEYS) {
     if (process.env[key]) env[key] = process.env[key];
   }
   if (urlExtras?.extensionId)
     env["PLAYWRIGHT_MCP_EXTENSION_ID"] = urlExtras.extensionId;
-  if (urlExtras?.extensionToken)
-    env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] = urlExtras.extensionToken;
   if (urlExtras?.profileDirectory)
     env["PLAYWRIGHT_MCP_PROFILE_DIRECTORY"] = urlExtras.profileDirectory;
   if (urlExtras?.userDataDir)
     env["PLAYWRIGHT_MCP_USER_DATA_DIR"] = urlExtras.userDataDir;
+  // Token: shell env wins (explicit override), registry is fallback, URL param is last resort
+  const profileKey = urlExtras?.profileDirectory || process.env.PLAYWRIGHT_MCP_PROFILE_DIRECTORY;
+  if (profileKey) {
+    const registry = await readTokenRegistry();
+    const entry = registry[profileKey];
+    if (entry) {
+      if (!env["PLAYWRIGHT_MCP_EXTENSION_ID"]) env["PLAYWRIGHT_MCP_EXTENSION_ID"] = entry.extensionId;
+      if (!env["PLAYWRIGHT_MCP_USER_DATA_DIR"] && entry.userDataDir) env["PLAYWRIGHT_MCP_USER_DATA_DIR"] = entry.userDataDir;
+      if (!env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"]) {
+        env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] = entry.token;
+      } else if (env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] !== entry.token) {
+        console.error(`[rech] warning: shell PLAYWRIGHT_MCP_EXTENSION_TOKEN differs from registry token for "${profileKey}" — using shell value. Run \`unset PLAYWRIGHT_MCP_EXTENSION_TOKEN\` to use the registry.`);
+      }
+    }
+  }
+  if (!env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] && urlExtras?.extensionToken)
+    env["PLAYWRIGHT_MCP_EXTENSION_TOKEN"] = urlExtras.extensionToken;
   return env;
 }
 
@@ -222,7 +265,12 @@ async function findInstalledExtension(
       const data = JSON.parse(await f.text());
       const settings = data?.extensions?.settings ?? {};
       for (const [extId, info] of Object.entries(settings as Record<string, any>)) {
-        if (info?.path === EXTENSION_DIST_DIR) return { id: extId, profile: prof };
+        if (!info?.path || info.state === 0) continue; // state 0 = explicitly disabled
+        let storedPath = info.path as string;
+        try { storedPath = realpathSync(storedPath); } catch {}
+        let distPath = EXTENSION_DIST_DIR;
+        try { distPath = realpathSync(distPath); } catch {}
+        if (storedPath === distPath) return { id: extId, profile: prof };
       }
     } catch {}
   }
@@ -284,20 +332,44 @@ async function callServe(
   const identity = await getClientIdentity();
   const effectiveProfile = profileDirectory || process.env.PLAYWRIGHT_MCP_PROFILE_DIRECTORY;
   if (effectiveProfile) (identity as any).profile = effectiveProfile;
-  const env = { ...getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir }), ...overrideEnv };
+  const env = { ...(await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir })), ...overrideEnv };
   const res = await fetch(`${protocol}://${host}:${port}/run`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
     body: JSON.stringify({ args, identity, env }),
     signal: AbortSignal.timeout(70_000),
-  }).catch((e) => { console.error(`[rech] ${e.message}`); process.exit(1); });
-  if (res.status === 401) { console.error("Unauthorized: bad key"); process.exit(1); }
+  }).catch(async (e) => {
+    console.error(`[rech] ${e.message}`);
+    const dnsResult = await import("dns/promises").then(m => m.lookup(host)).catch(() => null);
+    if (!dnsResult) {
+      console.error(`[rech] rech-client\n  -x: DNS failed -> ${host}[unknown] -> rech-server[unknown]`);
+    } else {
+      const tcpOk = await new Promise<boolean>(resolve => {
+        import("net").then(({ createConnection }) => {
+          const s = createConnection({ host, port: Number(port), timeout: 3000 });
+          s.on("connect", () => { s.destroy(); resolve(true); });
+          s.on("error", () => resolve(false));
+          s.on("timeout", () => { s.destroy(); resolve(false); });
+        });
+      });
+      if (tcpOk) {
+        console.error(`[rech] rech-client -> ${host}:${port}\n  -x: connection refused -> rech-server[unknown]`);
+      } else {
+        console.error(`[rech] rech-client -> ${host}(${dnsResult.address})\n  -x: port ${port} unreachable -> rech-server[unknown]`);
+      }
+    }
+    process.exit(1);
+  });
+  if (res.status === 401) {
+    console.error(`[rech] rech-client -> rech-server[ok]\n  -x: token rejected -> playwright[unknown]`);
+    process.exit(1);
+  }
   return res.json();
 }
 
 async function run(url: string, args: string[]) {
-  const { host, port, protocol } = parseUrl(url);
-  const effectiveProfile = parseUrl(url).profileDirectory || process.env.PLAYWRIGHT_MCP_PROFILE_DIRECTORY;
+  const { host, port, protocol, extensionId, extensionToken, profileDirectory, userDataDir } = parseUrl(url);
+  const effectiveProfile = profileDirectory || process.env.PLAYWRIGHT_MCP_PROFILE_DIRECTORY;
   const displayProfile = effectiveProfile ? await resolveProfileEmail(effectiveProfile) : undefined;
   const identity = await getClientIdentity();
   const profileSuffix = displayProfile ? ` profile:${displayProfile}` : "";
@@ -305,11 +377,21 @@ async function run(url: string, args: string[]) {
     `[rech] connecting to ${host}:${port} (identity: ${identity.gitUrl || `${identity.hostname}:${identity.cwd}`}${profileSuffix})`,
   );
 
+  const resolvedEnv = await getClientEnv({ extensionId, extensionToken, profileDirectory, userDataDir });
   const { status, stdout, stderr, files, existingSession } = await callServe(url, args);
 
   if (existingSession)
     console.error(`[rech] session already has open tabs — listing existing tabs instead of opening a new window`);
-  if (stderr) process.stderr.write(stderr);
+  if (stderr) {
+    if (stderr.includes('Extension connection timeout')) {
+      const hasToken = !!resolvedEnv["PLAYWRIGHT_MCP_EXTENSION_TOKEN"];
+      const last = hasToken
+        ? `  -x: extension token rejected -> extension[unknown]`
+        : `  -> extension[not installed]  (run: rech setup)`;
+      console.error(`[rech] rech-client -> rech-server[ok] -> playwright[ok]\n${last}`);
+    }
+    process.stderr.write(stderr);
+  }
   if (stdout) process.stdout.write(stdout);
 
   if (files?.length) {
@@ -331,111 +413,370 @@ async function run(url: string, args: string[]) {
   process.exit(status);
 }
 
-async function setup(): Promise<void> {
-  // 1. Require serve to be running
-  const url = process.env[ENV_KEY];
-  if (!url) {
-    console.error(`${ENV_KEY} not set — start the server first:\n  rech serve`);
-    process.exit(1);
+function buildSetupHtml(extDistDir: string, profileDisplay: string): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>rechrome — Extension Setup</title>
+<style>
+  body { font-family: system-ui, sans-serif; max-width: 720px; margin: 40px auto; padding: 0 20px; color: #222; }
+  h1 { color: #1a73e8; }
+  .step { background: #f8f9fa; border-left: 4px solid #1a73e8; padding: 12px 16px; margin: 16px 0; border-radius: 0 8px 8px 0; }
+  .step h3 { margin: 0 0 8px; }
+  code { background: #e8eaed; padding: 2px 6px; border-radius: 4px; font-size: 0.95em; word-break: break-all; }
+  .path { display: flex; align-items: center; gap: 8px; }
+  button { background: #1a73e8; color: white; border: none; padding: 6px 14px; border-radius: 6px; cursor: pointer; font-size: 0.9em; }
+  button:active { background: #1558b0; }
+  .note { color: #666; font-size: 0.9em; }
+</style>
+</head>
+<body>
+<h1>rechrome — Extension Setup</h1>
+<p>Install the multi-tab extension in Chrome profile: <strong>${profileDisplay}</strong></p>
+
+<div class="step">
+  <h3>Step 1 — Open Chrome Extensions</h3>
+  <p>In the Chrome profile <strong>${profileDisplay}</strong>, navigate to:</p>
+  <code>chrome://extensions/</code>
+  <p class="note">Make sure you are in the correct profile (check the avatar in the top-right corner).</p>
+</div>
+
+<div class="step">
+  <h3>Step 2 — Enable Developer Mode</h3>
+  <p>Toggle <strong>Developer mode</strong> on (top-right of the extensions page).</p>
+</div>
+
+<div class="step">
+  <h3>Step 3 — Load the extension</h3>
+  <p>Click <strong>Load unpacked</strong> and select this directory:</p>
+  <div class="path">
+    <code id="extPath">${extDistDir}</code>
+    <button onclick="navigator.clipboard.writeText(document.getElementById('extPath').textContent).then(()=>{this.textContent='Copied!';setTimeout(()=>this.textContent='Copy path',1500)})">Copy path</button>
+  </div>
+</div>
+
+<div class="step">
+  <h3>Step 4 — Return to terminal</h3>
+  <p>Press <strong>Enter</strong> in the terminal to continue setup.</p>
+</div>
+
+<div class="step">
+  <h3>Step 5 — Copy auth token</h3>
+  <p>Click the extension icon in the Chrome toolbar (or open the URL below):</p>
+  <code id="statusUrl">chrome-extension://(detected after install)/status.html</code>
+  <p>The page shows <strong>PLAYWRIGHT_MCP_EXTENSION_TOKEN=...</strong> — paste that into the terminal when prompted.</p>
+</div>
+</body>
+</html>`;
+}
+
+const OXMGR_PROCESS_NAME = "rechrome-serve";
+
+async function runOxmgr(args: string[]): Promise<number> {
+  const proc = Bun.spawn(["bunx", "oxmgr", ...args], { stdout: "inherit", stderr: "inherit" });
+  await proc.exited;
+  return proc.exitCode ?? 1;
+}
+
+async function daemonInstall(serveUrl: string): Promise<void> {
+  const home = process.env.HOME!;
+  const bunBin = Bun.which("bun") ?? process.execPath;
+  const rechScript = import.meta.filename;
+
+  const envArgs: string[] = [
+    "--env", `HOME=${home}`,
+    "--env", `PATH=${process.env.PATH || "/usr/local/bin:/usr/bin:/bin"}`,
+    "--env", `${ENV_KEY}=${serveUrl}`,
+    "--env", `PWMCP_TEST_CONNECTION_TIMEOUT=${process.env.PWMCP_TEST_CONNECTION_TIMEOUT || "30000"}`,
+  ];
+  if (process.env.PLAYWRIGHT_CLI) envArgs.push("--env", `PLAYWRIGHT_CLI=${process.env.PLAYWRIGHT_CLI}`);
+  if (process.env.RECH_HOST) envArgs.push("--env", `RECH_HOST=${process.env.RECH_HOST}`);
+  if (isReadable(process.env.RECH_TLS_CERT)) envArgs.push("--env", `RECH_TLS_CERT=${process.env.RECH_TLS_CERT}`);
+  if (isReadable(process.env.RECH_TLS_KEY)) envArgs.push("--env", `RECH_TLS_KEY=${process.env.RECH_TLS_KEY}`);
+
+  await runOxmgr(["delete", OXMGR_PROCESS_NAME]).catch(() => {});
+  await runOxmgr([
+    "start",
+    "--name", OXMGR_PROCESS_NAME,
+    "--restart", "always",
+    "--cwd", home,
+    ...envArgs,
+    `${bunBin} ${rechScript} serve`,
+  ]);
+  await runOxmgr(["service", "install"]);
+}
+
+async function daemonUninstall(): Promise<void> {
+  await runOxmgr(["delete", OXMGR_PROCESS_NAME]);
+  await runOxmgr(["service", "uninstall"]);
+  console.log(`Removed oxmgr process: ${OXMGR_PROCESS_NAME}`);
+}
+
+async function setup(opts: { profile?: string } = {}): Promise<void> {
+  const { createInterface } = await import("readline");
+  const isTTY = process.stdin.isTTY ?? false;
+  const rl = isTTY ? createInterface({ input: process.stdin, output: process.stdout }) : null;
+  const ask = (q: string, def = "") => {
+    if (!rl) { process.stdout.write(`${q}${def}\n`); return Promise.resolve(def); }
+    return new Promise<string>(r => rl.question(q, r));
+  };
+
+  // [1/4] Daemon
+  console.log("\n[1/4] Setting up serve daemon...");
+  // Clear stale hostname-based URL so we always use 127.0.0.1 locally
+  if (process.env[ENV_KEY]) {
+    try {
+      const u = new URL(process.env[ENV_KEY]);
+      if (!["127.0.0.1", "localhost"].includes(u.hostname)) delete process.env[ENV_KEY];
+    } catch {}
   }
+  const url = await getOrCreateUrl();
   const { host, port, protocol } = parseUrl(url);
-  const ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(3000) }).catch(() => null);
-  if (!ping) {
-    console.error(`rech serve is not running at ${host}:${port}\nStart it with:\n  rech serve`);
-    process.exit(1);
+
+  let ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
+  if (ping) {
+    console.log(`      Already running at ${protocol}://${host}:${port}`);
+    await daemonInstall(url);
+    console.log(`      Updated daemon: ${OXMGR_PROCESS_NAME}`);
+  } else {
+    await daemonInstall(url);
+    console.log(`      Registered daemon: ${OXMGR_PROCESS_NAME}`);
+    process.stdout.write("      Starting");
+    for (let i = 0; i < 15; i++) {
+      await Bun.sleep(1000);
+      ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
+      if (ping) break;
+      process.stdout.write(".");
+    }
+    process.stdout.write("\n");
+    if (!ping) {
+      console.error(`      Failed to start serve at ${host}:${port}`);
+      rl?.close();
+      process.exit(1);
+    }
+    console.log(`      Serve running at ${protocol}://${host}:${port}`);
   }
 
-  // 2. Interactive profile selection
   const cache = await readChromeProfileCache();
-  if (!cache) { console.error("Chrome profiles not found"); process.exit(1); }
-  const profiles = Object.entries(cache);
-  console.log("\nAvailable Chrome profiles:");
-  profiles.forEach(([dir, info], i) =>
-    console.log(`  ${String(i + 1).padStart(2)}.  ${(info.user_name || "(no email)").padEnd(32)}  ${(info.name || "").padEnd(20)}  [${dir}]`)
-  );
-  const { createInterface } = await import("readline");
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise<string>(r => rl.question("\nProfile number: ", r));
-  rl.close();
-  const idx = parseInt(answer.trim()) - 1;
-  if (isNaN(idx) || idx < 0 || idx >= profiles.length) { console.error("Invalid selection"); process.exit(1); }
-  const [profileDir, profileInfoSel] = profiles[idx];
-  const profileEnv = { PLAYWRIGHT_MCP_PROFILE_DIRECTORY: profileDir };
-  const profileDisplay = profileInfoSel.user_name || profileInfoSel.name || profileDir;
+  if (!cache) { console.error("      Chrome profiles not found"); rl?.close(); process.exit(1); }
+  const userDataDir = await findChromeUserDataDir();
 
-  // 3. Discover the extension ID. Unpacked extension IDs are derived from the
-  //    load path, so look up the actual ID from Chrome's Secure Preferences.
-  //    Env override wins if set explicitly.
-  let extId = process.env.PLAYWRIGHT_MCP_EXTENSION_ID;
-  if (!extId) {
-    const found = await findInstalledExtension(profileDir);
-    if (found) extId = found.id;
+  async function pickProfile(exclude: Set<string>): Promise<[string, { user_name?: string; name?: string }] | null> {
+    const available = Object.entries(cache!).filter(([dir]) => !exclude.has(dir));
+    if (!available.length) return null;
+    available.forEach(([dir, info], i) =>
+      console.log(`        ${String(i + 1).padStart(2)}.  ${(info.user_name || "(no email)").padEnd(32)}  ${(info.name || "").padEnd(20)}  [${dir}]`)
+    );
+    if (opts.profile !== undefined) {
+      const num = parseInt(opts.profile);
+      if (!isNaN(num)) return available[num - 1] ?? null;
+      return available.find(([, info]) =>
+        (info.user_name ?? "").toLowerCase().includes(opts.profile!.toLowerCase())
+      ) ?? null;
+    }
+    if (!isTTY) {
+      console.log("      Non-TTY: auto-selecting first profile");
+      return available[0] ?? null;
+    }
+    const answer = await ask("\n      Profile number: ");
+    const idx = parseInt(answer.trim()) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= available.length) return null;
+    return available[idx];
   }
 
-  if (!extId) {
-    printInstallInstructions(profileDisplay);
-    console.error("Opening chrome://extensions/ in the selected profile...");
-    await callServe(url, ["open", "chrome://extensions/"], profileEnv);
-    process.exit(1);
+  async function getExtAndToken(profileDir: string, profileDisplay: string): Promise<{ extId: string; token: string } | null> {
+    // Extension check
+    let extId: string | undefined;
+    while (true) {
+      const found = await findInstalledExtension(profileDir);
+      if (found) { extId = found.id; break; }
+      const setupHtmlPath = join(RECH_HOME_DIR, "setup.html");
+      mkdirSync(RECH_HOME_DIR, { recursive: true });
+      await Bun.write(setupHtmlPath, buildSetupHtml(EXTENSION_DIST_DIR, profileDisplay));
+      console.log(`\n      Extension not found in profile: ${profileDisplay}`);
+      console.log(`      Extension dist: ${EXTENSION_DIST_DIR}`);
+      console.log(`\n      Opening install guide in your browser...`);
+      Bun.spawn(["open", setupHtmlPath], { stdout: "ignore", stderr: "ignore" });
+      await ask("\n      Press Enter after loading the extension to retry...");
+    }
+    console.log(`      Extension found: ${extId}`);
+
+    // Token
+    const statusUrl = `chrome-extension://${extId}/status.html`;
+    console.log(`\n      Get auth token from the extension:`);
+    console.log(`        ${statusUrl}`);
+    Bun.spawn(
+      ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+       `--profile-directory=${profileDir}`, statusUrl],
+      { stdout: "ignore", stderr: "ignore", detached: true },
+    );
+    console.log(`\n      Or click the extension icon in the Chrome toolbar.`);
+    console.log(`      Copy the token shown on the page (PLAYWRIGHT_MCP_EXTENSION_TOKEN=...).\n`);
+    const tokenInput = (await ask("      Paste token: ")).trim();
+    const token = tokenInput.replace(/^.*?=/, "").trim();
+    if (!token || token.length < 20) { console.error("      Invalid token (too short)"); return null; }
+    console.log("      Token accepted");
+    return { extId, token };
   }
 
-  const statusUrl = `chrome-extension://${extId}/status.html`;
-  console.log(`\nOpening ${statusUrl}...`);
-  const openResult = await callServe(url, ["open", statusUrl], profileEnv);
-  if (openResult.status !== 0) { process.stderr.write(openResult.stderr); process.exit(openResult.status); }
-
-  // 4. Read token from extension page localStorage
-  const evalResult = await callServe(url, ["eval", `() => localStorage.getItem('auth-token')`], profileEnv);
-  const tokenMatch = evalResult.stdout.match(/"([A-Za-z0-9_-]{20,})"/);
-  const token = tokenMatch?.[1];
-  if (!token) {
-    printInstallInstructions(profileDisplay);
-    console.error("Tried to read the auth token from the extension's status page but failed.");
-    console.error("This usually means the extension is not loaded in this profile.");
-    process.exit(1);
-  }
+  // [2/4] Primary profile
+  console.log("\n[2/4] Select Chrome profile:");
+  const picked = await pickProfile(new Set());
+  if (!picked) { console.error("      Invalid selection"); rl?.close(); process.exit(1); }
+  const [profileDir, profileInfoSel] = picked;
+  const profileDisplay = profileInfoSel.user_name || profileInfoSel.name || profileDir;
 
-  // 5. Write single RECHROME_URL with all params to ~/.env.local
-  const home = process.env.HOME!;
-  const globalEnvPath = join(home, ".env.local");
+  // [3+4/4] Extension + token for primary profile
+  console.log("\n[3/4] Checking extension...");
+  const primary = await getExtAndToken(profileDir, profileDisplay);
+  if (!primary) { rl?.close(); process.exit(1); }
+  const { extId, token } = primary;
+  const profileEmail = profileInfoSel.user_name || profileDir;
+
+  // Save RECHROME_URL
+  const pwdEnvPath = join(process.cwd(), ".env.local");
+  const pwdRechPath = join(process.cwd(), ".rechrome", ".env.local");
+  const homeEnvPath = join(process.env.HOME!, ".env.local");
+  const saveChoice = (await ask(
+    `\n[4/4] Save RECHROME_URL to:\n  1. ${pwdEnvPath} (current dir) [default]\n  2. ${pwdRechPath} (current dir, rechrome-only)\n  3. ${homeEnvPath} (user home)\n\n  Choice [1]: `
+  )).trim();
+  const globalEnvPath = saveChoice === "3" ? homeEnvPath : saveChoice === "2" ? pwdRechPath : pwdEnvPath;
+  if (saveChoice === "2") mkdirSync(join(process.cwd(), ".rechrome"), { recursive: true });
   const existing = await file(globalEnvPath).text().catch(() => "");
   const rechUrl = new URL(url);
   rechUrl.searchParams.set("extension_id", extId);
   rechUrl.searchParams.set("token", token);
-  // Prefer email for readability, fall back to directory name
-  rechUrl.searchParams.set("profile", profileInfoSel.user_name || profileDir);
-  const userDataDir = await findChromeUserDataDir();
+  rechUrl.searchParams.set("profile", profileEmail);
   if (userDataDir) rechUrl.searchParams.set("user_data_dir", userDataDir);
   const newLine = `RECHROME_URL=${rechUrl.toString()}`;
-  // Remove old separate vars and update RECHROME_URL
   const keysToRemove = ["PLAYWRIGHT_MCP_USER_DATA_DIR", "PLAYWRIGHT_MCP_EXTENSION_ID", "PLAYWRIGHT_MCP_EXTENSION_TOKEN", "PLAYWRIGHT_MCP_PROFILE_DIRECTORY"];
   let lines = existing.trimEnd().split("\n").filter(l => !keysToRemove.some(k => l.startsWith(`${k}=`)));
   const rechIdx = lines.findIndex(l => l.startsWith("RECHROME_URL="));
   if (rechIdx >= 0) lines[rechIdx] = newLine;
   else lines.push(newLine);
   await Bun.write(globalEnvPath, lines.join("\n").trim() + "\n");
-  console.log(`\nSaved to ${globalEnvPath}:\n  ${newLine}`);
-  console.log("\nDone!");
+  console.log(`\nSaved to ${globalEnvPath}`);
+  console.log(`\n  ${newLine}`);
+
+  // Save primary to token registry
+  await saveTokenEntry(profileEmail, { extensionId: extId, token, profileDir, userDataDir: userDataDir ?? undefined });
+
+  // Additional profiles
+  const configured = new Set([profileDir]);
+  while (true) {
+    const more = (await ask("\nAdd another profile? [y/N]: ")).trim().toLowerCase();
+    if (more !== "y" && more !== "yes") break;
+    const remaining = Object.entries(cache!).filter(([dir]) => !configured.has(dir));
+    if (!remaining.length) { console.log("      No more profiles available."); break; }
+    console.log("\n      Select additional profile:");
+    const extra = await pickProfile(configured);
+    if (!extra) { console.log("      Skipped."); continue; }
+    const [extraDir, extraInfo] = extra;
+    const extraDisplay = extraInfo.user_name || extraInfo.name || extraDir;
+    console.log(`\n      Setting up: ${extraDisplay}`);
+    const result = await getExtAndToken(extraDir, extraDisplay);
+    if (!result) { console.log("      Skipped."); continue; }
+    const extraEmail = extraInfo.user_name || extraDir;
+    await saveTokenEntry(extraEmail, { extensionId: result.extId, token: result.token, profileDir: extraDir, userDataDir: userDataDir ?? undefined });
+    configured.add(extraDir);
+    console.log(`      Saved token for ${extraDisplay}`);
+  }
+  rl?.close();
+  envWatcher?.close();
+  console.log(`\nDone! Test with:\n  rech eval "() => document.title"`);
+}
+
+async function status(): Promise<void> {
+  const url = process.env[ENV_KEY];
+  if (!url) {
+    console.log(`serve:    not configured (run \`rech setup\`)`);
+    return;
+  }
+  const { host, port, protocol } = parseUrl(url);
+  const parsed = parseUrl(url);
+  const ping = await fetch(`${protocol}://${host}:${port}/`, { signal: AbortSignal.timeout(2000) }).catch(() => null);
+  // Check actual socket binding via lsof (shows * for 0.0.0.0, or exact IP for loopback-only)
+  const lsofProc = Bun.spawn(["lsof", "-nP", `-iTCP:${port}`, "-sTCP:LISTEN"], { stdout: "pipe", stderr: "ignore" });
+  const lsofOut = await new Response(lsofProc.stdout).text();
+  const listenLine = lsofOut.split("\n").find(l => l.includes(`:${port}`));
+  const listenAddr = listenLine?.match(/TCP\s+(\S+:\d+)/)?.[1] ?? (ping ? `${host}:${port}` : null);
+  console.log(`serve:    ${ping ? `running  ${protocol}://${listenAddr ?? `${host}:${port}`}` : "not running"}`);
+  const oxmgrProc = Bun.spawn(["bunx", "oxmgr", "list"], { stdout: "pipe", stderr: "ignore" });
+  const oxmgrOut = await new Response(oxmgrProc.stdout).text();
+  const daemonRegistered = oxmgrOut.includes(OXMGR_PROCESS_NAME);
+  console.log(`daemon:   ${daemonRegistered ? `oxmgr (${OXMGR_PROCESS_NAME})` : "not installed"}`);
+  const registry = await readTokenRegistry();
+  const entries = Object.entries(registry);
+  if (entries.length) {
+    console.log(`\nprofiles:`);
+    const primaryProfile = parsed.profileDirectory;
+    for (const [email, entry] of entries) {
+      const isPrimary = email === primaryProfile || entry.profileDir === primaryProfile;
+      const marker = isPrimary ? " (primary)" : "";
+      console.log(`  ${email.padEnd(36)}  [${entry.profileDir}]  ext: ${entry.extensionId.slice(0, 8)}…  token: ${entry.token.slice(0, 8)}…${marker}`);
+    }
+  } else if (parsed.profileDirectory) {
+    // Legacy: no registry yet, show from RECHROME_URL
+    const email = await resolveProfileEmail(parsed.profileDirectory).catch(() => parsed.profileDirectory);
+    console.log(`\nprofiles:\n  ${email}  [${parsed.profileDirectory}]  (legacy — re-run \`rech setup\` to register)`);
+  }
+}
+
+function printHelp(): void {
+  console.log(`rechrome (rech) — drive Chrome via Playwright over HTTP
+
+Usage:
+  rech setup                   First-time setup: daemon + Chrome extension + config
+  rech status                  Show current configuration and serve health
+  rech uninstall               Remove the serve daemon and clear config
+  rech serve                   Start the serve server manually (foreground)
+  rech profiles                List Chrome profiles
+  rech <playwright-args...>    Run Playwright CLI command (requires ${ENV_KEY})
+
+Environment:
+  ${ENV_KEY}   Server URL set by \`rech setup\`
+
+Examples:
+  rech setup
+  rech eval "() => document.title"
+  rech open https://example.com
+  rech screenshot`);
 }
 
 if (import.meta.main) {
   const args = process.argv.slice(2);
+  const cmd = args[0]?.toLowerCase();
 
-  if (args[0] === "serve") {
+  if (cmd === "serve") {
     const { serve } = await import("./serve.js");
-    serve();
-  } else if (args[0] === "profiles") {
+    serve(); // long-lived; watcher intentionally kept alive
+  } else if (cmd === "status") {
+    await status();
+    envWatcher?.close();
+  } else if (cmd === "profiles") {
     await listProfiles();
-  } else if (args[0] === "setup") {
-    await setup();
+    envWatcher?.close();
+  } else if (cmd === "setup") {
+    const profileIdx = args.indexOf("--profile");
+    const profile = profileIdx !== -1
+      ? args[profileIdx + 1]
+      : args.find(a => a.startsWith("--profile="))?.slice("--profile=".length);
+    await setup({ profile }); // setup closes envWatcher itself before printing Done
+  } else if (cmd === "uninstall") {
+    await daemonUninstall();
+    envWatcher?.close();
+  } else if (cmd === "help" || cmd === "--help" || cmd === "-h" || args.length === 0) {
+    printHelp();
+    envWatcher?.close();
   } else {
     const url = process.env[ENV_KEY];
     if (!url) {
-      console.error(
-        `Usage:\n  rech serve\n  ${ENV_KEY}=http://key@host:${DEFAULT_PORT}?extension_id=ID&token=TOKEN rech <playwright-args...>\n  ${ENV_KEY}=https://key@host/path?extension_id=ID&token=TOKEN rech <playwright-args...>`,
-      );
+      console.error(`${ENV_KEY} is not set. Run \`rech setup\` to configure.\n`);
+      printHelp();
       process.exit(1);
     }
-    run(url, args);
+    await run(url, args);
+    envWatcher?.close();
   }
 }