rechrome 0.1.0 → 1.1.0

package/.env.example

@@ -10,3 +10,7 @@
 
 # Bind address for the server (default: 127.0.0.1, use 0.0.0.0 for remote access)
 # RECH_HOST=127.0.0.1
+
+# Playwright MCP extension settings (can be set on server or client; client overrides server)
+# PLAYWRIGHT_MCP_EXTENSION_ID=your-extension-id
+# PLAYWRIGHT_MCP_EXTENSION_TOKEN=your-extension-token

package/README.md

@@ -1,4 +1,6 @@
-# rech — Remote Chrome
+# rechrome — Remote Chrome
+
+[![npm](https://img.shields.io/npm/v/rechrome)](https://www.npmjs.com/package/rechrome)
 
 CLI proxy for running [Playwright](https://playwright.dev/) commands on a shared remote browser. Run a server on a machine with a browser, then send commands from any client.
 
@@ -22,14 +24,17 @@ Built on top of [playwright-multi-tab](https://github.com/snomiao/playwright-mul
 ## Install
 
 ```bash
-# Clone and link globally
-git clone https://github.com/snomiao/rech.git
-cd rech
+# From npm
+bunx rechrome --help
+
+# Or clone and link globally
+git clone https://github.com/snomiao/rechrome.git
+cd rechrome
 bun install
 bun link
 ```
 
-Now `rech` is available globally.
+Now `rechrome` (or `rech`) is available globally.
 
 ## Quick start
 
@@ -38,7 +43,7 @@ Now `rech` is available globally.
 On the machine with a browser:
 
 ```bash
-rech serve
+rechrome serve
 ```
 
 This auto-generates a connection URL in `.env.local` (with an auth key).
@@ -51,16 +56,16 @@ Copy the `REMOTE_CHROME_URL` from the server's `.env.local` to the client:
 export REMOTE_CHROME_URL=remote-chrome://YOUR_KEY@server-host:13775
 
 # Open a URL
-rech open https://example.com
+rechrome open https://example.com
 
 # Take a screenshot
-rech screenshot
+rechrome screenshot
 
 # List open tabs
-rech tab-list
+rechrome tab-list
 
 # Any playwright-cli command works
-rech --help
+rechrome --help
 ```
 
 ## Configuration
@@ -73,10 +78,12 @@ cp .env.example .env.local
 
 | Variable | Description | Default |
 |---|---|---|
-| `REMOTE_CHROME_URL` | Connection URL (auto-generated by `rech serve`) | — |
+| `REMOTE_CHROME_URL` | Connection URL (auto-generated by `rechrome serve`) | — |
 | `GEMINI_API_KEY` | Gemini API key for screenshot vision descriptions | — |
 | `PLAYWRIGHT_CLI` | Path to playwright-cli binary (recommended: `playwright-cli-multi-tab` for full multi-tab support) | `playwright-cli` |
 | `RECH_HOST` | Server bind address | `127.0.0.1` |
+| `PLAYWRIGHT_MCP_EXTENSION_ID` | Chrome extension ID (client overrides server) | — |
+| `PLAYWRIGHT_MCP_EXTENSION_TOKEN` | Chrome extension token (client overrides server) | — |
 
 ### Remote access
 
@@ -103,7 +110,7 @@ bun test
 
 ## Related
 
-- [playwright-multi-tab](https://github.com/snomiao/playwright-multi-tab) — the underlying Playwright fork powering rech's multi-tab and multi-session browser control
+- [playwright-multi-tab](https://github.com/snomiao/playwright-multi-tab) — the underlying Playwright fork powering rechrome's multi-tab and multi-session browser control
 
 ## License
 

package/package.json

@@ -1,15 +1,35 @@
-{ 
+{
   "name": "rechrome",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snomiao/rechrome.git"
+  },
   "bin": {
-    "rech": "./rech.ts"
+    "rech": "./rech.js",
+    "rechrome": "./rech.js"
   },
   "scripts": {
     "serve": "bun run rech.ts serve",
-    "test": "bun test"
+    "test": "bun test",
+    "prepublishOnly": "sed 's/\\.ts/\\.js/g' rech.ts > rech.js && sed 's/\\.ts/\\.js/g' serve.ts > serve.js"
   },
   "devDependencies": {
     "@types/bun": "latest"
-  }
+  },
+  "release": {
+    "branches": [
+      "main"
+    ]
+  },
+  "files": [
+    "rech.ts",
+    "rech.js",
+    "serve.ts",
+    "serve.js",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ]
 }

package/rech.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env bun
+
+import { file } from "bun";
+import { randomBytes } from "crypto";
+import { mkdirSync, appendFileSync, existsSync } from "fs";
+import { hostname } from "os";
+import { join, basename } from "path";
+
+export const ENV_KEY = "REMOTE_CHROME_URL";
+export const DEFAULT_PORT = 13775;
+export const RECH_DIR = join(import.meta.dir, ".rech");
+export const LOG_DIR = join(RECH_DIR, "logs");
+
+// Load .env.local from script's directory (works even when invoked from elsewhere)
+const envFile = join(import.meta.dir, ".env.local");
+
+/** Load .env.local into process.env. */
+async function loadEnv() {
+  const envRaw = await file(envFile)
+    .text()
+    .catch(() => "");
+  for (const line of envRaw.split("\n")) {
+    const m = line.match(/^\s*([^#=]+?)\s*=\s*(.*?)\s*$/);
+    if (m) process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+  }
+}
+await loadEnv();
+
+// Watch .env.local for changes and hot-reload
+import { watch } from "node:fs";
+if (existsSync(envFile)) {
+  watch(envFile, async () => {
+    log(".env.local changed, reloading");
+    await loadEnv();
+  });
+}
+
+/** Describe an image using Gemini vision API. Returns description or null on failure. */
+export async function describeImage(imagePath: string): Promise<string | null> {
+  const apiKey = process.env.GEMINI_API_KEY;
+  if (!apiKey) return null;
+  try {
+    const imageData = await file(imagePath).arrayBuffer();
+    const base64 = Buffer.from(imageData).toString("base64");
+    const mimeType = imagePath.endsWith(".png") ? "image/png" : "image/jpeg";
+    const res = await fetch(
+      `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-pro-preview:generateContent?key=${apiKey}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          contents: [
+            {
+              parts: [
+                {
+                  text: "Describe this browser screenshot concisely in 2-3 sentences. Focus on what's visible: page layout, content, any errors or issues.",
+                },
+                { inline_data: { mime_type: mimeType, data: base64 } },
+              ],
+            },
+          ],
+        }),
+      },
+    );
+    if (!res.ok) return null;
+    const json = await res.json();
+    return json.candidates?.[0]?.content?.parts?.[0]?.text?.trim() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export const PASSTHROUGH_ENV_KEYS = [
+  "PLAYWRIGHT_MCP_EXTENSION_ID",
+  "PLAYWRIGHT_MCP_EXTENSION_TOKEN",
+] as const;
+
+export function log(msg: string) {
+  mkdirSync(LOG_DIR, { recursive: true });
+  const ts = new Date().toISOString();
+  const line = `[${ts}] ${msg}\n`;
+  console.error(line.trimEnd());
+  const logFile = join(LOG_DIR, `${ts.slice(0, 10)}.log`);
+  appendFileSync(logFile, line);
+}
+
+export function parseUrl(raw: string) {
+  const u = new URL(raw);
+  return { key: u.username, host: u.hostname, port: parseInt(u.port) || DEFAULT_PORT };
+}
+
+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 = `remote-chrome://${key}@${hostname()}:${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);
+  process.env[ENV_KEY] = url;
+  return url;
+}
+
+export function authCheck(req: Request, key: string): Response | null {
+  const bearer = req.headers.get("authorization")?.replace("Bearer ", "");
+  if (bearer !== key) return new Response("Unauthorized", { status: 401 });
+  return null;
+}
+
+async function getClientIdentity(): Promise<{ gitUrl?: string; hostname?: string; cwd?: string }> {
+  const cwd = process.cwd();
+  try {
+    const remoteProc = Bun.spawn(["git", "remote", "get-url", "origin"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const remoteUrl = (await new Response(remoteProc.stdout).text()).trim();
+    await remoteProc.exited;
+
+    const branchProc = Bun.spawn(["git", "rev-parse", "--abbrev-ref", "HEAD"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const branch = (await new Response(branchProc.stdout).text()).trim();
+    await branchProc.exited;
+
+    if (remoteUrl) {
+      let gitUrl: string;
+      const sshMatch = remoteUrl.match(/^git@([^:]+):(.+?)(?:\.git)?$/);
+      const httpsMatch = remoteUrl.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?$/);
+      if (sshMatch) {
+        gitUrl = `https://${sshMatch[1]}/${sshMatch[2]}`;
+      } else if (httpsMatch) {
+        gitUrl = `https://${httpsMatch[1]}/${httpsMatch[2]}`;
+      } else {
+        gitUrl = remoteUrl.replace(/\.git$/, "");
+      }
+      if (branch) gitUrl += `/tree/${branch}`;
+      // Strip any embedded credentials from the URL
+      try { const u = new URL(gitUrl); u.username = ""; u.password = ""; gitUrl = u.toString(); } catch {}
+      return { gitUrl };
+    }
+  } catch {}
+  return { hostname: hostname(), cwd };
+}
+
+function getClientEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of PASSTHROUGH_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
+async function run(url: string, args: string[]) {
+  const { key, host, port } = parseUrl(url);
+  const identity = await getClientIdentity();
+  console.error(
+    `[rech] connecting to ${host}:${port} (identity: ${identity.gitUrl || `${identity.hostname}:${identity.cwd}`})`,
+  );
+  const res = await fetch(`http://${host}:${port}/run`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
+    body: JSON.stringify({ args, identity, env: getClientEnv() }),
+    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);
+  }
+
+  const { status, stdout, stderr, files, descriptions, existingSession } = (await res.json()) as {
+    status: number;
+    stdout: string;
+    stderr: string;
+    files?: string[];
+    descriptions?: Record<string, string>;
+    existingSession?: boolean;
+  };
+
+  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 (stdout) process.stdout.write(stdout);
+
+  if (files?.length) {
+    const dlDir = join(process.cwd(), ".playwright-cli-multi-tab");
+    mkdirSync(dlDir, { recursive: true });
+    const gitignorePath = join(dlDir, ".gitignore");
+    if (!existsSync(gitignorePath)) await Bun.write(gitignorePath, "*\n");
+    for (const name of files) {
+      const fileRes = await fetch(`http://${host}:${port}/files/${name}`, {
+        headers: { Authorization: `Bearer ${key}` },
+      });
+      if (!fileRes.ok) continue;
+      const dest = join(dlDir, basename(name));
+      await Bun.write(dest, fileRes);
+      console.error(`[rech] downloaded: ${dest}`);
+      if (descriptions?.[name]) {
+        console.error(`[rech] vision: ${descriptions[name]}`);
+      }
+    }
+  }
+
+  process.exit(status);
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+
+  if (args[0] === "serve") {
+    const { serve } = await import("./serve.js");
+    serve();
+  } else {
+    const url = process.env[ENV_KEY];
+    if (!url) {
+      console.error(
+        `Usage:\n  rech serve\n  ${ENV_KEY}=remote-chrome://key@host:${DEFAULT_PORT} rech <playwright-args...>`,
+      );
+      process.exit(1);
+    }
+    run(url, args);
+  }
+}

package/rech.ts

@@ -6,6 +6,11 @@ import { mkdirSync, appendFileSync, existsSync } from "fs";
 import { hostname } from "os";
 import { join, basename } from "path";
 
+export const ENV_KEY = "REMOTE_CHROME_URL";
+export const DEFAULT_PORT = 13775;
+export const RECH_DIR = join(import.meta.dir, ".rech");
+export const LOG_DIR = join(RECH_DIR, "logs");
+
 // Load .env.local from script's directory (works even when invoked from elsewhere)
 const envFile = join(import.meta.dir, ".env.local");
 
@@ -23,15 +28,12 @@ await loadEnv();
 
 // Watch .env.local for changes and hot-reload
 import { watch } from "node:fs";
-watch(envFile, async () => {
-  log(".env.local changed, reloading");
-  await loadEnv();
-});
-
-export const ENV_KEY = "REMOTE_CHROME_URL";
-export const DEFAULT_PORT = 13775;
-export const RECH_DIR = join(import.meta.dir, ".rech");
-export const LOG_DIR = join(RECH_DIR, "logs");
+if (existsSync(envFile)) {
+  watch(envFile, async () => {
+    log(".env.local changed, reloading");
+    await loadEnv();
+  });
+}
 
 /** Describe an image using Gemini vision API. Returns description or null on failure. */
 export async function describeImage(imagePath: string): Promise<string | null> {
@@ -68,6 +70,11 @@ export async function describeImage(imagePath: string): Promise<string | null> {
   }
 }
 
+export const PASSTHROUGH_ENV_KEYS = [
+  "PLAYWRIGHT_MCP_EXTENSION_ID",
+  "PLAYWRIGHT_MCP_EXTENSION_TOKEN",
+] as const;
+
 export function log(msg: string) {
   mkdirSync(LOG_DIR, { recursive: true });
   const ts = new Date().toISOString();
@@ -141,6 +148,14 @@ async function getClientIdentity(): Promise<{ gitUrl?: string; hostname?: string
   return { hostname: hostname(), cwd };
 }
 
+function getClientEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const key of PASSTHROUGH_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  return env;
+}
+
 async function run(url: string, args: string[]) {
   const { key, host, port } = parseUrl(url);
   const identity = await getClientIdentity();
@@ -150,7 +165,7 @@ async function run(url: string, args: string[]) {
   const res = await fetch(`http://${host}:${port}/run`, {
     method: "POST",
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${key}` },
-    body: JSON.stringify({ args, identity }),
+    body: JSON.stringify({ args, identity, env: getClientEnv() }),
     signal: AbortSignal.timeout(70_000),
   }).catch((e) => {
     console.error(`[rech] ${e.message}`);

package/serve.js

@@ -0,0 +1,217 @@
+import { file } from "bun";
+import { createHash } from "crypto";
+import { mkdirSync } from "fs";
+import { join, resolve, relative, isAbsolute } from "path";
+import { log, parseUrl, getOrCreateUrl, authCheck, describeImage, RECH_DIR, PASSTHROUGH_ENV_KEYS } from "./rech.js";
+
+export function isUnderDir(base: string, candidate: string): boolean {
+  const absBase = resolve(base) + "/";
+  const absCandidate = resolve(base, candidate);
+  return absCandidate.startsWith(absBase);
+}
+
+export async function serve() {
+  const url = await getOrCreateUrl();
+  const { key, port } = parseUrl(url);
+
+  const workDir = join(RECH_DIR, "output");
+  mkdirSync(workDir, { recursive: true });
+
+  const listenHost = process.env.RECH_HOST || "127.0.0.1";
+  const server = Bun.serve({
+    hostname: listenHost,
+    port,
+    async fetch(req) {
+      const reqUrl = new URL(req.url);
+
+      // Serve files from output dir
+      if (reqUrl.pathname.startsWith("/files/")) {
+        const denied = authCheck(req, key);
+        if (denied) return denied;
+        const name = decodeURIComponent(reqUrl.pathname.slice(7));
+        if (!isUnderDir(workDir, name)) return new Response("Forbidden", { status: 403 });
+        const resolved = resolve(workDir, name);
+        const f = file(resolved);
+        if (!(await f.exists())) return new Response("Not found", { status: 404 });
+        return new Response(f);
+      }
+
+      if (reqUrl.pathname !== "/run") return new Response("rech server\n");
+      const denied = authCheck(req, key);
+      if (denied) return denied;
+
+      const body = await req.json();
+      let args: string[];
+      let sessionId: string;
+      let clientName = "";
+      let clientEnv: Record<string, string> = {};
+      if (Array.isArray(body)) {
+        args = body;
+        const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
+        sessionId = createHash("sha256").update(clientAddr).digest("hex").slice(0, 12);
+        clientName = clientAddr;
+        log(`session from client IP: ${clientAddr} -> ${sessionId}`);
+      } else {
+        args = body.args;
+        const id = body.identity as
+          | { gitUrl?: string; hostname?: string; cwd?: string }
+          | undefined;
+        const raw = id?.gitUrl || (id?.hostname && id?.cwd ? `${id.hostname}:${id.cwd}` : null);
+        if (raw) {
+          sessionId = createHash("sha256").update(raw).digest("hex").slice(0, 12);
+          clientName = raw;
+          log(`session from identity: ${raw} -> ${sessionId}`);
+        } else {
+          const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
+          sessionId = createHash("sha256").update(clientAddr).digest("hex").slice(0, 12);
+          clientName = clientAddr;
+          log(`session from client IP fallback: ${clientAddr} -> ${sessionId}`);
+        }
+        // Extract allowlisted env vars from client (client overrides server)
+        if (body.env && typeof body.env === "object") {
+          for (const key of PASSTHROUGH_ENV_KEYS) {
+            if (typeof body.env[key] === "string") clientEnv[key] = body.env[key];
+          }
+        }
+      }
+
+      let clientSession = "";
+      const filteredArgs = args.filter((a) => {
+        const m = a.match(/^-s=(.+)$/);
+        if (m) {
+          clientSession = m[1];
+          return false;
+        }
+        return true;
+      });
+      const namespacedSession = clientSession ? `${sessionId}-${clientSession}` : sessionId;
+
+      const bin = process.env.PLAYWRIGHT_CLI || "playwright-cli";
+
+      if (filteredArgs.length === 0) {
+        filteredArgs.push("--help");
+      }
+
+      log(`run: rech ${filteredArgs.join(" ")} (session=${namespacedSession})`);
+
+      // For open commands, check if this session already has tabs open
+      const isOpenCmd = filteredArgs[0] === "open";
+      if (isOpenCmd) {
+        try {
+          const listProc = Bun.spawn([bin, "tab-list", "--extension", `-s=${namespacedSession}`], {
+            cwd: workDir,
+            stdin: "ignore",
+            stdout: "pipe",
+            stderr: "pipe",
+            env: { PATH: process.env.PATH, HOME: process.env.HOME },
+          });
+          const [listStatus, listOut] = await Promise.all([
+            listProc.exited,
+            new Response(listProc.stdout).text(),
+          ]);
+          if (listStatus === 0 && listOut.trim()) {
+            log(`session ${namespacedSession} already has tabs, returning tab-list hint`);
+            return Response.json({
+              status: 0,
+              stdout: listOut,
+              stderr: `[rech] session "${namespacedSession}" already has open tabs:\n`,
+              files: [],
+              existingSession: true,
+            });
+          }
+        } catch (e) {
+          log(`tab-list check failed: ${e}`);
+        }
+      }
+
+      // Merge passthrough env: server .env.local defaults, then client overrides
+      const passthroughEnv: Record<string, string | undefined> = {};
+      for (const key of PASSTHROUGH_ENV_KEYS) {
+        if (process.env[key]) passthroughEnv[key] = process.env[key];
+      }
+      Object.assign(passthroughEnv, clientEnv);
+
+      const childEnv: Record<string, string | undefined> = {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        TMPDIR: process.env.TMPDIR,
+        DISPLAY: process.env.DISPLAY,
+        XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
+        ...(clientName ? { PLAYWRIGHT_MCP_CLIENT_NAME: clientName } : {}),
+        ...passthroughEnv,
+      };
+      const proc = Bun.spawn([bin, ...filteredArgs, "--extension", `-s=${namespacedSession}`], {
+        cwd: workDir,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+        env: childEnv,
+      });
+
+      const TIMEOUT = 60_000;
+      const timeout = new Promise<never>((_, reject) =>
+        setTimeout(() => {
+          proc.kill();
+          reject(new Error("timeout"));
+        }, TIMEOUT),
+      );
+      const [status, stdout, stderr] = await Promise.race([
+        Promise.all([
+          proc.exited,
+          new Response(proc.stdout).text(),
+          new Response(proc.stderr).text(),
+        ]),
+        timeout.then(() => [1, "", ""] as [number, string, string]),
+      ]).catch(
+        () => [1, "", `Command timed out after ${TIMEOUT / 1000}s\n`] as [number, string, string],
+      );
+
+      log(`exit: ${status}${stdout.trim() ? ` | ${stdout.trim().slice(0, 200)}` : ""}`);
+
+      // Detect files mentioned in output
+      const filePattern = /[\w./-]+\.(?:png|jpe?g|pdf|json|yml)\b/gi;
+      const mentionedFiles = [
+        ...new Set(
+          [...stdout.matchAll(filePattern), ...stderr.matchAll(filePattern)].map((m) => m[0]),
+        ),
+      ];
+      const outputFiles: string[] = [];
+      for (const f of mentionedFiles) {
+        if (!isUnderDir(workDir, f)) continue;
+        if (await file(join(workDir, f)).exists()) {
+          outputFiles.push(f);
+        } else {
+          const basename = f.split("/").pop()!;
+          for (const subdir of [".playwright-cli", ".rech-multi-tab"]) {
+            const subpath = join(subdir, basename);
+            if (await file(join(workDir, subpath)).exists()) {
+              outputFiles.push(subpath);
+              break;
+            }
+          }
+        }
+      }
+
+      // Auto-describe screenshot files with Gemini vision
+      const descriptions: Record<string, string> = {};
+      for (const f of outputFiles) {
+        if (/\.(?:png|jpe?g)$/i.test(f)) {
+          const desc = await describeImage(join(workDir, f));
+          if (desc) descriptions[f] = desc;
+        }
+      }
+
+      const rebrand = (s: string) => s.replaceAll("npx playwright-cli", "rech");
+      return Response.json({
+        status,
+        stdout: rebrand(stdout),
+        stderr: rebrand(stderr),
+        files: outputFiles,
+        descriptions,
+      });
+    },
+  });
+
+  log(`serving on http://${server.hostname}:${server.port}`);
+  log(`Connection URL set (use .env.local to view)`);
+}

package/serve.ts

@@ -2,7 +2,7 @@ import { file } from "bun";
 import { createHash } from "crypto";
 import { mkdirSync } from "fs";
 import { join, resolve, relative, isAbsolute } from "path";
-import { log, parseUrl, getOrCreateUrl, authCheck, describeImage, RECH_DIR } from "./rech.ts";
+import { log, parseUrl, getOrCreateUrl, authCheck, describeImage, RECH_DIR, PASSTHROUGH_ENV_KEYS } from "./rech.ts";
 
 export function isUnderDir(base: string, candidate: string): boolean {
   const absBase = resolve(base) + "/";
@@ -44,6 +44,7 @@ export async function serve() {
       let args: string[];
       let sessionId: string;
       let clientName = "";
+      let clientEnv: Record<string, string> = {};
       if (Array.isArray(body)) {
         args = body;
         const clientAddr = `${req.headers.get("x-forwarded-for") || server.requestIP(req)?.address || "unknown"}`;
@@ -66,6 +67,12 @@ export async function serve() {
           clientName = clientAddr;
           log(`session from client IP fallback: ${clientAddr} -> ${sessionId}`);
         }
+        // Extract allowlisted env vars from client (client overrides server)
+        if (body.env && typeof body.env === "object") {
+          for (const key of PASSTHROUGH_ENV_KEYS) {
+            if (typeof body.env[key] === "string") clientEnv[key] = body.env[key];
+          }
+        }
       }
 
       let clientSession = "";
@@ -117,6 +124,13 @@ export async function serve() {
         }
       }
 
+      // Merge passthrough env: server .env.local defaults, then client overrides
+      const passthroughEnv: Record<string, string | undefined> = {};
+      for (const key of PASSTHROUGH_ENV_KEYS) {
+        if (process.env[key]) passthroughEnv[key] = process.env[key];
+      }
+      Object.assign(passthroughEnv, clientEnv);
+
       const childEnv: Record<string, string | undefined> = {
         PATH: process.env.PATH,
         HOME: process.env.HOME,
@@ -124,6 +138,7 @@ export async function serve() {
         DISPLAY: process.env.DISPLAY,
         XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
         ...(clientName ? { PLAYWRIGHT_MCP_CLIENT_NAME: clientName } : {}),
+        ...passthroughEnv,
       };
       const proc = Bun.spawn([bin, ...filteredArgs, "--extension", `-s=${namespacedSession}`], {
         cwd: workDir,

package/rech.spec.ts

@@ -1,78 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { parseUrl, authCheck, describeImage, DEFAULT_PORT, ENV_KEY } from "./rech.ts";
-
-describe("parseUrl", () => {
-  test("parses key, host, and port from a remote-chrome URL", () => {
-    const result = parseUrl("remote-chrome://mykey@example.com:9999");
-    expect(result).toEqual({ key: "mykey", host: "example.com", port: 9999 });
-  });
-
-  test("falls back to DEFAULT_PORT when port is missing", () => {
-    const result = parseUrl("remote-chrome://mykey@example.com");
-    expect(result).toEqual({ key: "mykey", host: "example.com", port: DEFAULT_PORT });
-  });
-
-  test("handles URL-safe base64 characters in key", () => {
-    const result = parseUrl("remote-chrome://ab_c-dEf12@host:8080");
-    expect(result.key).toBe("ab_c-dEf12");
-  });
-
-  test("parses localhost URLs", () => {
-    const result = parseUrl("remote-chrome://k@localhost:13775");
-    expect(result).toEqual({ key: "k", host: "localhost", port: 13775 });
-  });
-});
-
-describe("authCheck", () => {
-  test("returns null for valid bearer token", () => {
-    const req = new Request("http://localhost/run", {
-      headers: { Authorization: "Bearer secret123" },
-    });
-    expect(authCheck(req, "secret123")).toBeNull();
-  });
-
-  test("returns 401 for wrong bearer token", () => {
-    const req = new Request("http://localhost/run", {
-      headers: { Authorization: "Bearer wrong" },
-    });
-    const res = authCheck(req, "secret123");
-    expect(res).not.toBeNull();
-    expect(res!.status).toBe(401);
-  });
-
-  test("returns 401 when no authorization header", () => {
-    const req = new Request("http://localhost/run");
-    const res = authCheck(req, "secret123");
-    expect(res).not.toBeNull();
-    expect(res!.status).toBe(401);
-  });
-
-  test("returns 401 for empty bearer token", () => {
-    const req = new Request("http://localhost/run", {
-      headers: { Authorization: "Bearer " },
-    });
-    const res = authCheck(req, "secret123");
-    expect(res).not.toBeNull();
-    expect(res!.status).toBe(401);
-  });
-});
-
-describe("describeImage", () => {
-  test("returns null when GEMINI_API_KEY is not set", async () => {
-    const original = process.env.GEMINI_API_KEY;
-    delete process.env.GEMINI_API_KEY;
-    const result = await describeImage("/nonexistent/image.png");
-    expect(result).toBeNull();
-    if (original) process.env.GEMINI_API_KEY = original;
-  });
-});
-
-describe("constants", () => {
-  test("ENV_KEY is REMOTE_CHROME_URL", () => {
-    expect(ENV_KEY).toBe("REMOTE_CHROME_URL");
-  });
-
-  test("DEFAULT_PORT is 13775", () => {
-    expect(DEFAULT_PORT).toBe(13775);
-  });
-});

package/serve.spec.ts

@@ -1,50 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { isUnderDir } from "./serve.ts";
-
-describe("isUnderDir", () => {
-  test("allows simple relative file", () => {
-    expect(isUnderDir("/app/output", "file.png")).toBe(true);
-  });
-
-  test("allows nested relative path", () => {
-    expect(isUnderDir("/app/output", "subdir/file.png")).toBe(true);
-  });
-
-  test("blocks simple traversal with ../", () => {
-    expect(isUnderDir("/app/output", "../secret.txt")).toBe(false);
-  });
-
-  test("blocks traversal that shares prefix (output-evil)", () => {
-    expect(isUnderDir("/app/output", "../output-evil/secret.txt")).toBe(false);
-  });
-
-  test("blocks double traversal", () => {
-    expect(isUnderDir("/app/output", "../../etc/passwd")).toBe(false);
-  });
-
-  test("blocks traversal hidden in middle of path", () => {
-    expect(isUnderDir("/app/output", "subdir/../../etc/passwd")).toBe(false);
-  });
-
-  test("allows deeply nested path", () => {
-    expect(isUnderDir("/app/output", "a/b/c/d/file.json")).toBe(true);
-  });
-
-  test("blocks absolute path outside base", () => {
-    expect(isUnderDir("/app/output", "/etc/passwd")).toBe(false);
-  });
-
-  test("blocks dot-only path that resolves to base itself", () => {
-    // "." resolves to base itself, not under it
-    expect(isUnderDir("/app/output", ".")).toBe(false);
-  });
-
-  test("allows path starting with dot component", () => {
-    expect(isUnderDir("/app/output", "./file.png")).toBe(true);
-  });
-
-  test("blocks percent-encoded traversal after decoding", () => {
-    // The caller is responsible for decoding; test the resolved path
-    expect(isUnderDir("/app/output", decodeURIComponent("..%2F..%2Fetc%2Fpasswd"))).toBe(false);
-  });
-});