rechrome 1.25.0 → 1.27.0

package/rechrome.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env bun
-import { readListeners, writeListeners, listenerAddress, isLoopback, normalizePrefix, serviceUrl, type Listener } from "./listeners.js";
+import { readListeners, writeListeners, listenerAddress, isLoopback, normalizePrefix, serviceUrl, allowProfiles, denyProfiles, rotateListenerKey, setPublicUrl, type Listener } from "./listeners.js";
 
 import { file } from "bun";
 import yargs from "yargs";
 import { readExtensionTokenFromProfile } from "./extension-token.js";
 import { randomBytes } from "crypto";
-import { mkdirSync, appendFileSync, existsSync, realpathSync, accessSync, cpSync, unlinkSync, readFileSync, readdirSync, constants as fsConstants } from "fs";
+import { mkdirSync, appendFileSync, existsSync, realpathSync, accessSync, cpSync, unlinkSync, readFileSync, readdirSync, renameSync, rmdirSync, constants as fsConstants } from "fs";
 import { hostname, homedir, networkInterfaces } from "os";
 import { isIPv4 } from "net";
 import { join, basename, dirname } from "path";
@@ -16,14 +16,16 @@ import { oxmgrInstallCommand, pickDaemonManager, type DaemonManager } from "./da
 
 export const ENV_KEY = "RECHROME_URL";
 export const DEFAULT_PORT = 13775;
-export const RECH_DIR = join(import.meta.dir, ".rech");
-export const LOG_DIR = join(RECH_DIR, "logs");
-
 // Home dir: HOME on POSIX, USERPROFILE on Windows (handled by os.homedir()).
 export const HOME = homedir();
 
-const RECH_HOME_DIR = join(HOME, ".rechrome");
-const TOKENS_FILE = join(RECH_HOME_DIR, "profiles.yaml");
+// All rechrome state (registry, listeners, extension, logs, daemon output) lives in
+// ~/.rechrome, never next to the code: a bunx/npx install dir is a disposable cache.
+export const RECH_DIR = join(HOME, ".rechrome");
+export const LOG_DIR = join(RECH_DIR, "logs");
+// Before the rename, logs and daemon output lived in <install dir>/.rech.
+export const LEGACY_RECH_DIR = join(import.meta.dir, ".rech");
+const TOKENS_FILE = join(RECH_DIR, "profiles.yaml");
 
 type TokenEntry = { extensionId: string; token: string; profileDir: string; userDataDir?: string; loadExtension?: string };
 
@@ -38,7 +40,7 @@ function validateTokenRegistry(value: unknown): Record<string, TokenEntry> {
   return value as Record<string, TokenEntry>;
 }
 
-export async function writeTokenRegistry(registry: Record<string, TokenEntry>, directory = RECH_HOME_DIR): Promise<void> {
+export async function writeTokenRegistry(registry: Record<string, TokenEntry>, directory = RECH_DIR): Promise<void> {
   validateTokenRegistry(registry);
   await mkdir(directory, { recursive: true });
   const path = join(directory, "profiles.yaml");
@@ -51,7 +53,7 @@ export async function writeTokenRegistry(registry: Record<string, TokenEntry>, d
   }
 }
 
-export async function readTokenRegistry(directory = RECH_HOME_DIR): Promise<Record<string, TokenEntry>> {
+export async function readTokenRegistry(directory = RECH_DIR): Promise<Record<string, TokenEntry>> {
   const path = join(directory, "profiles.yaml");
   let raw: string;
   try { raw = await readFile(path, "utf8"); }
@@ -74,7 +76,7 @@ export async function readTokenRegistry(directory = RECH_HOME_DIR): Promise<Reco
 }
 
 async function saveTokenEntry(profileEmail: string, entry: TokenEntry): Promise<void> {
-  mkdirSync(RECH_HOME_DIR, { recursive: true });
+  mkdirSync(RECH_DIR, { recursive: true });
   const registry = await readTokenRegistry();
   registry[profileEmail] = entry;
   await writeTokenRegistry(registry);
@@ -241,6 +243,31 @@ export function log(msg: string) {
   appendFileSync(logFile, line);
 }
 
+/**
+ * Move logs and daemon output from the legacy <install dir>/.rech into RECH_DIR, entry by
+ * entry. An entry already present in RECH_DIR is kept and the legacy copy left in place,
+ * so nothing is overwritten. Best effort: a cross-device rename just leaves the old copy.
+ */
+export function migrateLegacyDataDir(legacy = LEGACY_RECH_DIR, target = RECH_DIR): string[] {
+  const moved: string[] = [];
+  if (!existsSync(legacy)) return moved;
+  mkdirSync(target, { recursive: true });
+  if (realpathSync(legacy) === realpathSync(target)) return moved;
+  for (const sub of ["logs", "output"]) {
+    const from = join(legacy, sub);
+    if (!existsSync(from)) continue;
+    mkdirSync(join(target, sub), { recursive: true });
+    for (const entry of readdirSync(from)) {
+      const to = join(target, sub, entry);
+      if (existsSync(to)) continue;
+      try { renameSync(join(from, entry), to); moved.push(`${sub}/${entry}`); } catch { /* keep the legacy copy */ }
+    }
+  }
+  // Remove only directories left empty (the unused tls/ included); rmdir refuses non-empty ones.
+  for (const dir of ["logs", "output", "tls", ""]) { try { rmdirSync(join(legacy, dir)); } catch { /* not empty */ } }
+  return moved;
+}
+
 export function parseUrl(raw: string) {
   const u = new URL(raw);
   const fragment = new URLSearchParams(u.hash.slice(1).replace(/^\?/, ""));
@@ -368,8 +395,8 @@ export async function detectTailscaleServe(port: number, prefix: string): Promis
   return { dnsName, routeUrl: findTailscaleServeRoute(dnsName, serveStatus, port, prefix) };
 }
 
-/** Remote connection URL for a Serve route, carrying the listener key and profile like the local one. */
-export function tailscaleConnectionUrl(routeUrl: string, localUrl: string): string {
+/** The same connection (key and profile) at another base URL, e.g. where a proxy exposes the listener. */
+export function rebaseConnectionUrl(routeUrl: string, localUrl: string): string {
   const local = new URL(localUrl);
   const remote = new URL(routeUrl);
   remote.username = parseUrl(localUrl).key;
@@ -482,7 +509,15 @@ export function deriveIdentity(opts: {
   return { key, label };
 }
 
-async function getClientIdentity(): Promise<{ key: string; label: string; profile?: string }> {
+/**
+ * A project's own rechrome folder: <root>/.rechrome, where root is the same one the session
+ * key uses (the worktree root, submodules rolled up), or cwd in `cwd` mode / outside git.
+ */
+export function projectDataDir(opts: { mode: string; cwd: string; root?: string | null }): string {
+  return join(opts.mode === "cwd" ? opts.cwd : opts.root || opts.cwd, ".rechrome");
+}
+
+async function getClientIdentity(): Promise<{ key: string; label: string; dataDir: string; profile?: string }> {
   const cwd = realpathSafe(process.cwd());
   const mode = (process.env.RECH_IDENTITY || "worktree").toLowerCase();
   let root: string | null = null;
@@ -508,7 +543,7 @@ async function getClientIdentity(): Promise<{ key: string; label: string; profil
     if (remoteUrl) remote = normalizeRemote(remoteUrl);
   }
 
-  return deriveIdentity({ mode, cwd, host: hostname(), root, remote, branch });
+  return { ...deriveIdentity({ mode, cwd, host: hostname(), root, remote, branch }), dataDir: projectDataDir({ mode, cwd, root }) };
 }
 
 // Profile precedence: an explicit `?profile=` in RECHROME_URL is authoritative; the
@@ -862,16 +897,22 @@ export function profileConnectionUri(profile: string, configuredUrl: string | un
   return result.toString();
 }
 
-async function printProfileUri(selector?: string, listener?: string): Promise<void> {
+async function printProfileUri(selector?: string, listener?: string, opts: { local?: boolean; save?: boolean } = {}): Promise<void> {
   const url = process.env[ENV_KEY];
   selector ??= url ? parseUrl(url).profileDirectory : undefined;
-  if (!selector) throw new Error("Specify a profile: rech profile <name> --print-uri");
+  if (!selector) throw new Error("Specify a profile: rech url <profile>");
   const registry = await readTokenRegistry();
   const cache = await readChromeProfileCache();
   // A configured remote profile may not exist in this machine's local registry.
   const profile = url && parseUrl(url).profileDirectory === selector && !listener
     ? selector : (await resolveGlobalProfile(registry, cache, selector)).email;
-  console.log(profileConnectionUri(profile, url, (await readListeners())?.listeners ?? [], listener));
+  const listeners = (await readListeners())?.listeners ?? [];
+  let uri = profileConnectionUri(profile, url, listeners, listener);
+  // Prefer where a proxy exposes the listener, when it has been recorded.
+  const publicUrl = listeners.find(l => l.key === parseUrl(uri).key)?.publicUrl;
+  if (publicUrl && !opts.local) uri = rebaseConnectionUrl(publicUrl, uri);
+  console.log(uri);
+  if (opts.save) console.error(`Saved RECHROME_URL to ${await saveProjectUrl(uri)}`);
 }
 
 export function sandboxConnectionWarning(env: Record<string, string | undefined> = process.env): string | null {
@@ -902,7 +943,8 @@ async function callServe(
   const res = await fetch(serviceUrl(url, "run"), {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ args, identity, env }),
+    // dataDir is a client-local path; the daemon (possibly remote) only needs the session identity.
+    body: JSON.stringify({ args, identity: { key: identity.key, label: identity.label, profile: identity.profile }, env }),
     signal: AbortSignal.timeout(70_000),
   }).catch(async (e) => {
     if (throwOnFailure) throw new Error("Cannot reach the rechrome daemon. Check that it is running.");
@@ -948,6 +990,31 @@ export function normalizeCommandArgs(args: string[]): string[] {
 // --profile at/after the subcommand belongs to the forwarded CLI (e.g. playwright-cli's own
 // `open --profile <dir>`, a user-data-dir path) and must pass through untouched. Throws on a
 // missing value; accepts multiple occurrences (last one wins).
+/**
+ * `rech [--profile X] [--isolate] pw <args>` forwards <args> to playwright-cli verbatim, so
+ * `rech pw --version` or `rech pw status` reach playwright instead of rech. `--` works the
+ * same after a rech flag (`rech --profile X -- status`); a bare leading `--` cannot, because
+ * Bun consumes the `--` right after the script path. The separator counts only when
+ * everything before it is a rech global flag; otherwise it belongs to the playwright command
+ * (`rech open -- x`). Returns its index, or -1.
+ */
+export function rechSeparatorIndex(args: string[]): number {
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--" || a === "pw" || a === "playwright") return i;
+    if (a === "--profile") { i++; continue; }
+    if (a.startsWith("--profile=") || a === "--isolate" || a === "--isolated") continue;
+    return -1;
+  }
+  return -1;
+}
+
+/** rechrome's own version, from the package.json shipped next to this file. */
+export function rechromeVersion(): string {
+  try { return JSON.parse(readFileSync(join(import.meta.dir, "package.json"), "utf8")).version ?? "unknown"; }
+  catch { return "unknown"; }
+}
+
 export function extractGlobalProfileArg(args: string[]): { args: string[]; selector?: string } {
   const rest = [...args];
   let selector: string | undefined;
@@ -1018,9 +1085,11 @@ async function run(url: string, args: string[], overrideEnv?: Record<string, str
   if (stdout) process.stdout.write(stdout);
 
   if (files?.length) {
-    const dlDir = join(process.cwd(), ".playwright-cli-multi-tab");
+    // Saved files belong to the project: <project>/.rechrome/output. The folder also holds
+    // .env.local (secrets), so it is git-ignored as a whole when first created.
+    const dlDir = join(identity.dataDir, "output");
     mkdirSync(dlDir, { recursive: true });
-    const gitignorePath = join(dlDir, ".gitignore");
+    const gitignorePath = join(identity.dataDir, ".gitignore");
     if (!existsSync(gitignorePath)) await Bun.write(gitignorePath, "*\n");
     for (const name of files) {
       const fileRes = await fetch(serviceUrl(url, `files/${name}`), {
@@ -1467,7 +1536,7 @@ async function daemonUninstall(): Promise<void> {
 // locate the binary and launch it detached (singleton via a pidfile).
 // `rech tray hide` / the menu "Hide" item both kill the process;
 // `rech tray show` starts a fresh one.
-const TRAY_PID_FILE = join(RECH_HOME_DIR, "tray.pid");
+const TRAY_PID_FILE = join(RECH_DIR, "tray.pid");
 
 // A desktop GUI must be present. Linux needs an X11/Wayland display; a headless
 // box (SSH, CI, container) has neither, so the tray is skipped. macOS/Windows
@@ -1729,7 +1798,7 @@ async function provisionProfile(name: string, opts: { headed?: boolean } = {}):
     process.exit(1);
   }
   const dist = await ensureExtensionDistInstalled();
-  const userDataDir = join(RECH_HOME_DIR, "profiles", name);
+  const userDataDir = join(RECH_DIR, "profiles", name);
   const token = randomBytes(32).toString("base64url");
 
   console.log(`\n[1/3] Provisioning managed profile "${name}"`);
@@ -1811,17 +1880,123 @@ async function removeListener(name: string): Promise<void> {
   console.log("Listener removed from configuration; daemon reloads automatically.");
 }
 
-async function addListener(name: string, opts: { listen: string; profile: string[]; port?: number; prefix?: string }): Promise<void> {
-  const config = await requireListeners();
+async function resolveProfileKeys(selectors: string[]): Promise<string[]> {
   const registry = await readTokenRegistry(), cache = await readChromeProfileCache();
   const profiles: string[] = [];
-  for (const selector of opts.profile) profiles.push((await resolveGlobalProfile(registry, cache, selector)).email);
+  for (const selector of selectors) profiles.push((await resolveGlobalProfile(registry, cache, selector)).email);
+  return [...new Set(profiles)];
+}
+
+/** Next steps after exposing a listener: proxy it, record where, share. Plain text, so any shell works. */
+export function listenerNextSteps(listener: Listener, profile?: string): string[] {
+  const prefix = normalizePrefix(listener.prefix);
+  const mount = prefix === "/" ? "" : prefix.slice(0, -1);
+  return [
+    `Expose it through any reverse proxy on port ${listener.port}${mount ? ` (mount ${mount}; stripping it is fine)` : ""}, e.g.:`,
+    `  tailscale serve --bg${mount ? ` --set-path=${mount}` : ""} ${listener.port}`,
+    `Then record where it is reachable and print the URL to share:`,
+    `  rech listener set ${listener.name} --public-url https://<your-host>${prefix}`,
+    `  rech url ${profile ? JSON.stringify(profile) : "<profile>"} --listener ${listener.name}`,
+  ];
+}
+
+async function addListener(name: string, opts: { listen: string; profile: string[]; port?: number; prefix?: string }): Promise<void> {
+  const config = await requireListeners();
+  const profiles = await resolveProfileKeys(opts.profile);
   const host = chooseListenAddress(await detectListenChoices(), opts.listen);
   const port = opts.port ?? DEFAULT_PORT;
-  if (config.listeners.some(l => l.name === name)) throw new Error("Listener name already exists; edit listeners.json to change its allowlist");
-  config.listeners.push({ name, host, port, prefix: normalizePrefix(opts.prefix), key: randomBytes(24).toString("base64url"), profiles: [...new Set(profiles)] });
+  if (config.listeners.some(l => l.name === name)) throw new Error(`Listener "${name}" already exists; change its profiles with rech listener allow|deny ${name} <profile>`);
+  const listener: Listener = { name, host, port, prefix: normalizePrefix(opts.prefix), key: randomBytes(24).toString("base64url"), profiles };
+  config.listeners.push(listener);
   await writeListeners(config);
   console.log(`Listener saved for ${host}:${port}; daemon reloads automatically. Credentials are in ~/.rechrome/listeners.json (keep private).`);
+  if (isLoopback(host)) for (const line of listenerNextSteps(listener, profiles[0])) console.log(line);
+}
+
+function findListener(config: { listeners: Listener[] }, name?: string): Listener {
+  if (name) {
+    const listener = config.listeners.find(l => l.name === name);
+    if (!listener) throw new Error(`Unknown listener "${name}". See rech listener ls.`);
+    return listener;
+  }
+  const scoped = config.listeners.filter(l => l.profiles !== "*");
+  if (scoped.length !== 1) throw new Error(`Name a listener: ${config.listeners.map(l => l.name).join(", ")}`);
+  return scoped[0];
+}
+
+async function listenerPort(name?: string): Promise<void> {
+  console.log(findListener(await requireListeners(), name).port);
+}
+
+async function allowListener(name: string, selectors: string[]): Promise<void> {
+  const config = await requireListeners();
+  const added = allowProfiles(config, name, await resolveProfileKeys(selectors));
+  await writeListeners(config);
+  console.log(added.length ? `Allowed on ${name}: ${added.join(", ")}` : `Already allowed on ${name}; nothing changed.`);
+}
+
+async function denyListener(name: string, selectors: string[]): Promise<void> {
+  const config = await requireListeners();
+  // Accept raw registry keys too, so a profile that no longer resolves can still be removed.
+  const keys = [...selectors, ...await resolveProfileKeys(selectors).catch(() => [] as string[])];
+  const removed = denyProfiles(config, name, keys);
+  await writeListeners(config);
+  console.log(removed.length ? `Removed from ${name}: ${removed.join(", ")}` : `Not on ${name}; nothing changed.`);
+}
+
+async function rotateKey(name: string): Promise<void> {
+  const config = await requireListeners();
+  rotateListenerKey(config, name);
+  await writeListeners(config);
+  console.log(`New key for ${name}; URLs carrying the old key stop working now. Print new ones with: rech url <profile> --listener ${name}`);
+}
+
+async function setListener(name: string, opts: { publicUrl?: string; clearPublicUrl?: boolean }): Promise<void> {
+  const config = await requireListeners();
+  const listener = setPublicUrl(config, name, opts.clearPublicUrl ? null : opts.publicUrl ?? null);
+  await writeListeners(config);
+  console.log(listener.publicUrl ? `${name} is reachable at ${listener.publicUrl}` : `${name}: public URL cleared`);
+}
+
+const hideKey = (url: string) => url.replace(/([#&?]key=)[^&]*/, "$1…");
+
+async function urlList(): Promise<void> {
+  const config = await requireListeners();
+  const rows = [["LISTENER", "PROFILE", "LOCAL", "PUBLIC"]];
+  for (const l of config.listeners) {
+    const local = `http://${listenerAddress(l)}${normalizePrefix(l.prefix)}`;
+    for (const profile of l.profiles === "*" ? ["(all profiles)"] : l.profiles) rows.push([l.name, profile, local, l.publicUrl ?? "-"]);
+  }
+  const widths = rows[0].map((_, i) => Math.max(...rows.map(r => r[i].length)));
+  for (const r of rows) console.log(r.map((c, i) => c.padEnd(widths[i])).join("  ").trimEnd());
+  console.log(`\nPrint a full URL (contains the secret key): rech url <profile> --listener <name>`);
+}
+
+/** Write RECHROME_URL to this project's .rechrome/.env.local (the folder git-ignores itself). */
+async function saveProjectUrl(url: string): Promise<string> {
+  const { dataDir } = await getClientIdentity();
+  mkdirSync(dataDir, { recursive: true });
+  const gitignore = join(dataDir, ".gitignore");
+  if (!existsSync(gitignore)) await Bun.write(gitignore, "*\n");
+  const envPath = join(dataDir, ".env.local");
+  const lines = (await file(envPath).text().catch(() => "")).split("\n").filter(l => l.trim() && !l.startsWith(`${ENV_KEY}=`));
+  await writeFile(envPath, [...lines, `${ENV_KEY}=${url}`, ""].join("\n"), { mode: 0o600 });
+  await chmod(envPath, 0o600);
+  return envPath;
+}
+
+async function connect(url: string): Promise<void> {
+  const parsed = parseUrl(url);
+  if (!parsed.key) throw new Error("That URL has no key (#key=…). Ask the host for the full URL from: rech url <profile>");
+  const response = await fetch(serviceUrl(url, "ping"), { headers: { Authorization: `Bearer ${parsed.key}` }, signal: AbortSignal.timeout(5000) })
+    .catch(error => { throw new Error(`Could not reach ${serviceUrl(url)}: ${error instanceof Error ? error.message : error}`); });
+  if (response.status === 401) throw new Error("The daemon rejected this key; ask the host for a fresh URL (keys change on rech listener rotate-key).");
+  if (!response.ok) throw new Error(`${serviceUrl(url, "ping")} answered ${response.status}; is the proxy pointing at the listener?`);
+  const body = await response.json().catch(() => ({})) as { listener?: string; profiles?: string[] | "*" };
+  if (parsed.profileDirectory && Array.isArray(body.profiles) && !body.profiles.includes(parsed.profileDirectory))
+    throw new Error(`Connected, but listener "${body.listener}" does not allow profile "${parsed.profileDirectory}".`);
+  const saved = await saveProjectUrl(url);
+  console.log(`Connected to ${serviceUrl(url)}${body.listener ? ` (listener ${body.listener})` : ""}. Saved RECHROME_URL to ${saved}`);
 }
 
 export function detectSetupAgent(env: Record<string, string | undefined> = process.env): "Codex" | "Claude Code" | null {
@@ -2141,10 +2316,10 @@ async function setup(opts: SetupOptions = {}): Promise<void> {
     const serve = await detectTailscaleServe(exposure.port, prefix);
     if (serve.routeUrl) {
       console.log(`      Tailscale Serve route found: ${serve.routeUrl} → ${protocol}://${listenerAddress(exposure)}${prefix.slice(0, -1)}`);
-      console.log(`      Remote RECHROME_URL (secret; for other tailnet machines):\n        ${tailscaleConnectionUrl(serve.routeUrl, rechUrl.toString())}`);
+      console.log(`      Remote RECHROME_URL (secret; for other tailnet machines):\n        ${rebaseConnectionUrl(serve.routeUrl, rechUrl.toString())}`);
     } else {
       console.log(`      Tailscale Serve command (run separately): tailscale serve --bg --https=443 --set-path=${prefix.slice(0, -1)} ${protocol}://${listenerAddress(exposure)}${prefix.slice(0, -1)}`);
-      if (serve.dnsName) console.log(`      Then remote clients can use:\n        ${tailscaleConnectionUrl(`https://${serve.dnsName}${prefix}`, rechUrl.toString())}`);
+      if (serve.dnsName) console.log(`      Then remote clients can use:\n        ${rebaseConnectionUrl(`https://${serve.dnsName}${prefix}`, rechUrl.toString())}`);
       else console.log(`      For remote clients, use https://<your-machine-tailnet-name>${prefix} with this listener's bearer key and profile query.`);
     }
     console.log(`      The URL saved below is the local loopback one.`);
@@ -2228,7 +2403,6 @@ async function status(): Promise<void> {
     console.log(`serve:    not configured (run \`rech setup\`)`);
     return;
   }
-  const { host, port, protocol } = parseUrl(url);
   const parsed = parseUrl(url);
   const ping = await fetch(serviceUrl(url), { signal: AbortSignal.timeout(2000) }).catch(() => null);
   // Resolve the daemon's actual bind from its authenticated /ping (cross-platform; lsof is
@@ -2237,11 +2411,11 @@ async function status(): Promise<void> {
     ? await fetch(serviceUrl(url, "ping"), {
         headers: { Authorization: `Bearer ${parsed.key}` },
         signal: AbortSignal.timeout(2000),
-      }).then(r => (r.ok ? r.json() : null)).catch(() => null) as { bind?: string; degraded?: boolean; consecutiveTimeouts?: number } | null
+      }).then(r => (r.ok ? r.json() : null)).catch(() => null) as { bind?: string; listener?: string; degraded?: boolean; consecutiveTimeouts?: number } | null
     : null;
-  const bind = pingBody?.bind;
-  const listenAddr = bind ? `${bind}:${port}` : `${host}:${port}`;
-  console.log(`serve:    ${ping ? `running  ${protocol}://${listenAddr}` : "not running"}`);
+  // Show the URL this client connects to; through a proxy, the daemon's bind is on another port.
+  const details = [pingBody?.listener && `listener ${pingBody.listener}`, pingBody?.bind && `bind ${pingBody.bind}`].filter(Boolean).join(", ");
+  console.log(`serve:    ${ping ? `running  ${serviceUrl(url)}${details ? `  (${details})` : ""}` : "not running"}`);
   // daemonManager().id — there is no PM_BIN constant. Referencing one threw a
   // ReferenceError that took down the whole of `rech status`, so the one command
   // that reports "the relay is wedged" died exactly when the relay was wedged,
@@ -2305,12 +2479,26 @@ Usage:
   rech uninstall               Remove the serve daemon and clear config
   rech serve                   Start the serve server manually (foreground)
   rech listener [ls|add|remove]  Manage daemon listener addresses and allowed profiles
+  rech listener allow|deny <name> <profile...>
+                               Add or remove profiles on an existing listener
+  rech listener port [name]    Print a listener's port, for a reverse-proxy command
+  rech listener set <name> --public-url <url>
+                               Record where a proxy exposes the listener (rech url uses it)
+  rech listener rotate-key <name>
+                               New key for a listener; URLs with the old key stop working
   rech profile [ls|list]
                                List Chrome + managed test profiles and connection status
-  rech profile [name] --print-uri [--listener <name>]
-                               Print a connection URI (includes the daemon key).
-                               Uses RECHROME_URL, or an explicitly selected local listener.
+  rech url [profile] [--listener <name>] [--local] [--save]
+                               Print a connection URL (includes the secret key): the public
+                               URL when one is set, else the listener address. --save also
+                               writes it to this project's .rechrome/.env.local.
+                               \`rech profile [name] --print-uri\` is an alias.
+  rech url ls                  List every listener × profile URL (keys hidden)
+  rech connect <url>           Check a shared URL answers, then save it for this project
   rech <playwright-args...>    Run Playwright CLI command (requires ${ENV_KEY})
+  rech pw <playwright-args...> Forward verbatim to playwright-cli, even when a name clashes
+                               with rech's own (rech pw --version, rech pw status)
+  rech --version               rechrome's version
   rech --isolate <args...>     Run in a throwaway session (sugar for -s=<random>) so a
                                fragile single-shot flow (OAuth/login) never shares tabs
                                with the worktree's default session
@@ -2340,7 +2528,14 @@ export type RechHandlers = {
   addListener(name: string, opts: { listen: string; profile: string[]; port?: number; prefix?: string }): Promise<void>;
   removeListener(name: string): Promise<void>;
   listProfiles(): Promise<void>;
-  printProfileUri(selector?: string, listener?: string): Promise<void>;
+  printProfileUri(selector?: string, listener?: string, opts?: { local?: boolean; save?: boolean }): Promise<void>;
+  urlList(): Promise<void>;
+  connect(url: string): Promise<void>;
+  listenerPort(name?: string): Promise<void>;
+  allowListener(name: string, profiles: string[]): Promise<void>;
+  denyListener(name: string, profiles: string[]): Promise<void>;
+  rotateKey(name: string): Promise<void>;
+  setListener(name: string, opts: { publicUrl?: string; clearPublicUrl?: boolean }): Promise<void>;
   setup(opts: SetupOptions): Promise<void>;
   tray(action?: string): Promise<void>;
   provisionProfile(name: string, opts: { headed: boolean; experimental: boolean }): Promise<void>;
@@ -2348,7 +2543,7 @@ export type RechHandlers = {
 };
 
 /** Commands rech handles itself; anything else is forwarded verbatim to playwright-cli. */
-export const RECH_COMMANDS = new Set(["serve", "status", "listener", "listeners", "profile", "profiles", "setup", "tray", "provision-profile", "uninstall"]);
+export const RECH_COMMANDS = new Set(["serve", "status", "listener", "listeners", "profile", "profiles", "url", "urls", "connect", "setup", "tray", "provision-profile", "uninstall"]);
 
 const portOption = { type: "number", requiresArg: true, describe: "Listener port (1-65535)" } as const;
 
@@ -2369,13 +2564,40 @@ export function rechCli(argv: string[], handlers: RechHandlers) {
         a => handlers.addListener(a.name, { listen: a.listen, profile: a.profile, port: a.port, prefix: a.prefix }))
       .command("remove <name>", "Remove a listener", y => y.positional("name", { type: "string", demandOption: true }),
         a => handlers.removeListener(a.name))
+      .command("port [name]", "Print a listener's port (for a proxy command)", y => y.positional("name", { type: "string" }),
+        a => handlers.listenerPort(a.name))
+      .command("allow <name> <profiles..>", "Allow more profiles on a listener", y => y
+        .positional("name", { type: "string", demandOption: true }).positional("profiles", { type: "string", array: true, demandOption: true }),
+        a => handlers.allowListener(a.name, a.profiles))
+      .command("deny <name> <profiles..>", "Remove profiles from a listener", y => y
+        .positional("name", { type: "string", demandOption: true }).positional("profiles", { type: "string", array: true, demandOption: true }),
+        a => handlers.denyListener(a.name, a.profiles))
+      .command("rotate-key <name>", "Give a listener a new key (old URLs stop working)", y => y.positional("name", { type: "string", demandOption: true }),
+        a => handlers.rotateKey(a.name))
+      .command("set <name>", "Record where a reverse proxy exposes a listener", y => y
+        .positional("name", { type: "string", demandOption: true })
+        .option("public-url", { type: "string", requiresArg: true, describe: "e.g. https://host.example.js.net/rechrome/" })
+        .option("clear-public-url", { type: "boolean", conflicts: "public-url" })
+        .check(a => a.publicUrl !== undefined || a.clearPublicUrl ? true : "Pass --public-url <url> or --clear-public-url"),
+        a => handlers.setListener(a.name, { publicUrl: a.publicUrl, clearPublicUrl: a.clearPublicUrl }))
       .demandCommand(1).strict())
+    .command(["url [profile]", "urls [profile]"], "Print a profile's connection URL (contains a secret key); `url ls` lists them", y => y
+      .positional("profile", { type: "string", describe: "Profile (email, name or folder); ls/list lists all listeners' URLs" })
+      .option("listener", { type: "string", requiresArg: true, describe: "Listener to build the URL for" })
+      .option("local", { type: "boolean", describe: "Print the direct listener address even when a public URL is set" })
+      .option("save", { type: "boolean", describe: "Also save it as RECHROME_URL in this project's .rechrome/.env.local" }),
+      a => ["ls", "list"].includes(a.profile ?? "") && !a.listener && !a.save
+        ? handlers.urlList()
+        : handlers.printProfileUri(a.profile, a.listener, { local: a.local, save: a.save }))
+    .command("connect <url>", "Check a shared connection URL and save it for this project", y => y
+      .positional("url", { type: "string", demandOption: true }),
+      a => handlers.connect(a.url))
     .command(["profile [name]", "profiles [name]"], "List profiles, or print a profile's connection URI", y => y
       .positional("name", { type: "string", describe: "Profile (email, name or folder); ls/list lists all" })
       .option("print-uri", { type: "boolean", describe: "Print the profile's connection URI (contains a secret key)" })
       .option("listener", { type: "string", requiresArg: true, implies: "print-uri", describe: "Listener to build the URI for" }),
       a => {
-        if (a.printUri) return handlers.printProfileUri(a.name, a.listener);
+        if (a.printUri) return handlers.printProfileUri(a.name, a.listener); // alias of `rech url`
         if (a.name === undefined || ["ls", "list"].includes(a.name)) return handlers.listProfiles();
         throw new Error("Usage: rech profile [ls|list] | rech profile [name] --print-uri. Create, rename, and delete are not implemented.");
       })
@@ -2412,6 +2634,7 @@ if (import.meta.main) {
       serve: async () => { const { serve } = await import("./serve.js"); serve(); }, // long-lived; watcher intentionally kept alive
       status,
       listListeners, addListener, removeListener, listProfiles, printProfileUri,
+      urlList, connect, listenerPort, allowListener, denyListener, rotateKey, setListener,
       setup: async (opts) => {
         await setup(opts); // setup closes envWatcher itself before printing Done
         // Auto-start the tray (best-effort, silent on headless / missing binary).
@@ -2440,6 +2663,9 @@ if (import.meta.main) {
     } finally {
       if (cmd !== "serve") envWatcher?.close();
     }
+  } else if (cmd === "--version") {
+    console.log(rechromeVersion()); // playwright-cli's own: rech pw --version
+    envWatcher?.close();
   } else if (cmd === "help" || cmd === "--help" || cmd === "-h" || args.length === 0) {
     printHelp();
     envWatcher?.close();
@@ -2454,6 +2680,10 @@ if (import.meta.main) {
     // the leading-flags-only rule that protects the forwarded CLI's own --profile).
     let profileSelector: string | undefined;
     let overrideEnv: Record<string, string> | undefined;
+    // Everything after rech's `pw` (or `--`) goes to playwright-cli untouched; only the flags before it are rech's.
+    const separator = rechSeparatorIndex(args);
+    const forwarded = separator === -1 ? [] : args.slice(separator + 1);
+    if (separator !== -1) args = args.slice(0, separator);
     try {
       const extracted = extractGlobalProfileArg(args);
       profileSelector = extracted.selector;
@@ -2493,6 +2723,7 @@ if (import.meta.main) {
       args.splice(isolateIdx, 1);
       args.push(`-s=iso-${randomBytes(8).toString("hex")}`);
     }
+    args = [...forwarded, ...args];
     await run(url, args, overrideEnv);
     envWatcher?.close();
   }