rechrome 0.1.0

package/.env.example

@@ -0,0 +1,12 @@
+# Remote Chrome connection URL (auto-generated by `rech serve` if not set)
+# REMOTE_CHROME_URL=remote-chrome://key@host:13775
+
+# Gemini API key for screenshot vision descriptions (optional)
+# GEMINI_API_KEY=your-gemini-api-key
+
+# Custom playwright-cli binary path (default: playwright-cli)
+# For full multi-tab & multi-session support, use playwright-cli-multi-tab:
+# PLAYWRIGHT_CLI=playwright-cli-multi-tab
+
+# Bind address for the server (default: 127.0.0.1, use 0.0.0.0 for remote access)
+# RECH_HOST=127.0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sno
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# rech — Remote Chrome
+
+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.
+
+Built on top of [playwright-multi-tab](https://github.com/snomiao/playwright-multi-tab) — a patched Playwright fork with multi-tab and multi-session browser automation.
+
+## Features
+
+- **Session isolation** — clients are automatically namespaced by git repo or hostname
+- **File transfer** — screenshots and PDFs are automatically downloaded to the client
+- **Vision descriptions** — optional Gemini-powered screenshot descriptions
+- **Hot-reload config** — `.env.local` changes are picked up without restart
+- **Security** — bearer auth, path traversal protection, env allowlisting for child processes
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) ≥ 1.0
+- [playwright-cli](https://www.npmjs.com/package/playwright-cli) (works out of the box)
+
+> **💡 Recommended:** For full multi-tab and multi-session support, install [playwright-multi-tab](https://github.com/snomiao/playwright-multi-tab) and set `PLAYWRIGHT_CLI=playwright-cli-multi-tab` in your `.env.local`.
+
+## Install
+
+```bash
+# Clone and link globally
+git clone https://github.com/snomiao/rech.git
+cd rech
+bun install
+bun link
+```
+
+Now `rech` is available globally.
+
+## Quick start
+
+### 1. Start the server
+
+On the machine with a browser:
+
+```bash
+rech serve
+```
+
+This auto-generates a connection URL in `.env.local` (with an auth key).
+
+### 2. Run commands from a client
+
+Copy the `REMOTE_CHROME_URL` from the server's `.env.local` to the client:
+
+```bash
+export REMOTE_CHROME_URL=remote-chrome://YOUR_KEY@server-host:13775
+
+# Open a URL
+rech open https://example.com
+
+# Take a screenshot
+rech screenshot
+
+# List open tabs
+rech tab-list
+
+# Any playwright-cli command works
+rech --help
+```
+
+## Configuration
+
+Copy `.env.example` to `.env.local` and edit:
+
+```bash
+cp .env.example .env.local
+```
+
+| Variable | Description | Default |
+|---|---|---|
+| `REMOTE_CHROME_URL` | Connection URL (auto-generated by `rech 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` |
+
+### Remote access
+
+By default the server binds to `127.0.0.1` (localhost only). For remote access, either:
+
+- Use an SSH tunnel: `ssh -L 13775:localhost:13775 server-host`
+- Or set `RECH_HOST=0.0.0.0` (⚠️ ensure network is trusted — traffic is plain HTTP)
+
+## Session namespacing
+
+Each client gets an isolated browser session based on:
+
+1. **Git repo URL + branch** (if in a git repo)
+2. **Hostname + working directory** (fallback)
+
+Clients can also pass `-s=name` to create named sub-sessions within their namespace.
+
+## Development
+
+```bash
+bun install
+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
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,15 @@
+{ 
+  "name": "rechrome",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "rech": "./rech.ts"
+  },
+  "scripts": {
+    "serve": "bun run rech.ts serve",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/rech.spec.ts

@@ -0,0 +1,78 @@
+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/rech.ts

@@ -0,0 +1,220 @@
+#!/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";
+
+// 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";
+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");
+
+/** 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 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 };
+}
+
+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 }),
+    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.ts");
+    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/serve.spec.ts

@@ -0,0 +1,50 @@
+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);
+  });
+});

package/serve.ts

@@ -0,0 +1,202 @@
+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";
+
+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 = "";
+      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}`);
+        }
+      }
+
+      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}`);
+        }
+      }
+
+      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 } : {}),
+      };
+      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)`);
+}