@tiens.nguyen/gu-cli 1.0.833 → 1.0.835

package/README.md

@@ -57,6 +57,7 @@ server. After picking, `gu doctor` shows the URL and model that are actually in
 | `/model`, `/agent-model`, `/embed-model` | switch models (see above) |
 | `/context-window [tokens\|auto]` | tell gu how big the coding model's context is (hosted models cannot be probed) |
 | `/doctor` | check every configured model answers, especially the embedder |
+| `/browser [allow\|forget\|install\|cleanup]` | the agent's web browser (UI tests): it asks before first use, then works in your Chrome through the gu extension or, with nothing installed, in gu's own Chrome window; `allow`/`forget` stop or restart the question for this folder; guide: [browser-extension/README.md](browser-extension/README.md) |
 | `/tokens` | break down the last prompt sent to the coding model — how much of it was RAG |
 | `/prices [update]` | price and cache tables, and what the last turn and this session cost |
 | `/rag` | where this folder's RAG knowledge base lives: local, cloud, or both |

package/browser-bridge.mjs

@@ -0,0 +1,335 @@
+#!/usr/bin/env node
+// The browser bridge (task #363, GitHub #144): the gu Chrome extension holds a WebSocket to this
+// process, and the agent's browser tool (a new Python process every turn) sends it commands over
+// HTTP. The bridge outlives a turn so the extension stays connected between them.
+//
+// Local only, and only for the two who should use it:
+//   • it listens on 127.0.0.1 and refuses a Host header that is not 127.0.0.1/localhost
+//     (a web page cannot reach it through DNS rebinding);
+//   • the WebSocket is accepted only from an Origin of chrome-extension:// — a web page cannot
+//     forge that header;
+//   • a command needs the token in ~/.gonext/browser-bridge.json, which only this user can read.
+//
+// No dependency: the WebSocket is the few lines of RFC 6455 a single local client needs.
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, realpathSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { OwnChrome } from "./browser-chrome.mjs";
+
+export const DEFAULT_PORT = 4127;
+const WS_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
+
+export function statePath() {
+  return process.env.GU_BROWSER_STATE || join(homedir(), ".gonext", "browser-bridge.json");
+}
+
+// ── WebSocket frames ────────────────────────────────────────────────────────────────────────
+export function encodeFrame(text, opcode = 1) {
+  const payload = Buffer.isBuffer(text) ? text : Buffer.from(text);
+  const n = payload.length;
+  const head = n < 126 ? Buffer.alloc(2) : n < 65536 ? Buffer.alloc(4) : Buffer.alloc(10);
+  head[0] = 0x80 | opcode;
+  if (n < 126) head[1] = n;
+  else if (n < 65536) {
+    head[1] = 126;
+    head.writeUInt16BE(n, 2);
+  } else {
+    head[1] = 127;
+    head.writeBigUInt64BE(BigInt(n), 2);
+  }
+  return Buffer.concat([head, payload]);
+}
+
+// Pulls whole frames off the front of buf. Returns { frames: [{fin, opcode, payload}], rest }.
+export function decodeFrames(buf) {
+  const frames = [];
+  let off = 0;
+  while (buf.length - off >= 2) {
+    const b0 = buf[off];
+    const b1 = buf[off + 1];
+    let len = b1 & 0x7f;
+    let p = off + 2;
+    if (len === 126) {
+      if (buf.length < p + 2) break;
+      len = buf.readUInt16BE(p);
+      p += 2;
+    } else if (len === 127) {
+      if (buf.length < p + 8) break;
+      len = Number(buf.readBigUInt64BE(p));
+      p += 8;
+    }
+    const masked = (b1 & 0x80) !== 0;
+    const mask = masked ? buf.subarray(p, p + 4) : null;
+    if (masked) p += 4;
+    if (buf.length < p + len) break;
+    const payload = Buffer.from(buf.subarray(p, p + len));
+    if (mask) for (let i = 0; i < payload.length; i++) payload[i] ^= mask[i & 3];
+    frames.push({ fin: (b0 & 0x80) !== 0, opcode: b0 & 0x0f, payload });
+    off = p + len;
+  }
+  return { frames, rest: buf.subarray(off) };
+}
+
+// ── the bridge ──────────────────────────────────────────────────────────────────────────────
+const extId = (origin) => String(origin || "").replace(/^chrome-extension:\/\//, "").replace(/\/$/, "");
+
+// A refused second copy is told why with a close code it backs off on (background.js).
+export const CLOSE_OTHER_COPY = 4001;
+
+export function startBridge({ port = DEFAULT_PORT, token = randomBytes(24).toString("hex"), idleMs = 4 * 3600e3, log = () => {}, ownChrome = null } = {}) {
+  let ext = null; // { socket, version }
+  // gu's own Chrome window (#150): used when the extension is not connected AND the command asks
+  // for it (backend "auto" — the agent sends that only after the user allowed the browser).
+  let own = ownChrome;
+  let nextId = 1;
+  const pending = new Map(); // id → { resolve, timer }
+  const waiters = new Set(); // resolve() when the extension connects
+  let lastUse = Date.now();
+  const refused = new Map(); // extension id → when a second copy was turned away (#148)
+  const sockets = new Set(); // every upgraded socket, so close() can end them all
+
+  const hostOk = (h) => /^(127\.0\.0\.1|localhost)(:\d+)?$/i.test(String(h || ""));
+
+  function dropExtension(sock) {
+    if (!ext || ext.socket !== sock) return;
+    ext = null;
+    for (const [id, p] of pending) {
+      clearTimeout(p.timer);
+      p.resolve({ ok: false, error: "the gu Chrome extension disconnected" });
+      pending.delete(id);
+    }
+  }
+
+  function send(cmd, timeoutMs) {
+    return new Promise((resolve) => {
+      if (!ext) return resolve({ ok: false, error: "not connected", notConnected: true });
+      const id = nextId++;
+      const timer = setTimeout(() => {
+        pending.delete(id);
+        resolve({ ok: false, error: `the browser did not answer in ${Math.round(timeoutMs / 1000)}s` });
+      }, timeoutMs);
+      pending.set(id, { resolve, timer });
+      ext.socket.write(encodeFrame(JSON.stringify({ ...cmd, id })));
+    });
+  }
+
+  async function runOwn(cmd, timeoutMs) {
+    own ??= new OwnChrome({ log });
+    let timer;
+    try {
+      const result = await Promise.race([
+        own.run(cmd),
+        new Promise((_, reject) => (timer = setTimeout(() => reject(new Error(`gu's Chrome window did not answer in ${Math.round(timeoutMs / 1000)}s`)), timeoutMs))),
+      ]);
+      return { ok: true, result, backend: "chrome" };
+    } catch (e) {
+      const error = String(e?.message || e);
+      return { ok: false, error, backend: "chrome", ...(/no Chrome, Chromium/.test(error) ? { noChrome: true } : {}) };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  function waitConnected(ms) {
+    if (ext || ms <= 0) return Promise.resolve(Boolean(ext));
+    return new Promise((resolve) => {
+      const done = (v) => {
+        clearTimeout(t);
+        waiters.delete(done);
+        resolve(v);
+      };
+      const t = setTimeout(() => done(Boolean(ext)), ms);
+      waiters.add(done);
+    });
+  }
+
+  const server = createServer(async (req, res) => {
+    const json = (code, body) => {
+      res.writeHead(code, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    if (!hostOk(req.headers.host) || req.headers.origin) return json(403, { error: "forbidden" });
+    if (req.headers.authorization !== `Bearer ${token}`) return json(401, { error: "bad token" });
+    lastUse = Date.now();
+    const url = new URL(req.url, "http://127.0.0.1");
+    if (req.method === "GET" && url.pathname === "/status") {
+      const waitMs = Math.min(Number(url.searchParams.get("wait_ms")) || 0, 60000);
+      await waitConnected(waitMs);
+      const since = Date.now() - 5 * 60e3;
+      return json(200, {
+        connected: Boolean(ext),
+        version: ext?.version || null,
+        id: ext ? extId(ext.origin) : null,
+        installType: ext?.installType || null,
+        ownChrome: Boolean(own?.running),
+        refused: [...refused].filter(([, at]) => at > since).map(([id, at]) => ({ id, at })),
+        pid: process.pid,
+      });
+    }
+    if (req.method === "POST" && url.pathname === "/cmd") {
+      let body = "";
+      for await (const c of req) body += c;
+      let cmd;
+      try {
+        cmd = JSON.parse(body);
+      } catch {
+        return json(400, { error: "bad json" });
+      }
+      const timeoutMs = Math.min(Math.max(Number(cmd.timeout_ms) || 60000, 1000), 120000);
+      const backend = cmd.backend || "extension";
+      delete cmd.timeout_ms;
+      delete cmd.backend;
+      if (ext || backend !== "auto" || ["status", "uninstall_self"].includes(cmd.action)) {
+        const r = await send(cmd, timeoutMs);
+        return json(r.notConnected ? 503 : 200, { ...r, backend: "extension" });
+      }
+      return json(200, await runOwn(cmd, timeoutMs));
+    }
+    json(404, { error: "not found" });
+  });
+
+  server.on("upgrade", (req, socket) => {
+    const origin = String(req.headers.origin || "");
+    const key = req.headers["sec-websocket-key"];
+    if (!hostOk(req.headers.host) || !origin.startsWith("chrome-extension://") || !key || new URL(req.url, "http://x").pathname !== "/extension") {
+      socket.end("HTTP/1.1 403 Forbidden\r\n\r\n");
+      return;
+    }
+    socket.setNoDelay(true);
+    sockets.add(socket);
+    socket.on("close", () => sockets.delete(socket));
+    const accept = createHash("sha1").update(key + WS_GUID).digest("base64");
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    // ONE EXTENSION AT A TIME (#148). The same one reconnecting (Chrome restarted its worker)
+    // replaces the old socket. A DIFFERENT one — a developer copy next to the store copy — is
+    // turned away: with "newest wins" the two took the connection from each other every 3 s.
+    if (ext && !ext.socket.destroyed && ext.origin !== origin) {
+      refused.set(extId(origin), Date.now());
+      log(`refused a second gu extension (${extId(origin)}) — ${extId(ext.origin)} is connected`);
+      const reason = Buffer.from("another gu extension is connected");
+      const code = Buffer.alloc(2);
+      code.writeUInt16BE(CLOSE_OTHER_COPY);
+      socket.end(encodeFrame(Buffer.concat([code, reason]), 8));
+      setTimeout(() => socket.destroy(), 1000).unref();
+      return;
+    }
+    if (ext) ext.socket.destroy();
+    ext = { socket, version: null, installType: null, origin };
+    log(`extension connected (${origin})`);
+    let buf = Buffer.alloc(0);
+    let parts = [];
+    socket.on("data", (chunk) => {
+      buf = Buffer.concat([buf, chunk]);
+      const { frames, rest } = decodeFrames(buf);
+      buf = Buffer.from(rest);
+      for (const f of frames) {
+        if (f.opcode === 8) {
+          socket.end(encodeFrame("", 8));
+          return;
+        }
+        if (f.opcode === 9) {
+          socket.write(encodeFrame(f.payload.toString(), 10));
+          continue;
+        }
+        if (f.opcode === 10) continue;
+        parts.push(f.payload);
+        if (!f.fin) continue;
+        const text = Buffer.concat(parts).toString("utf8");
+        parts = [];
+        let msg;
+        try {
+          msg = JSON.parse(text);
+        } catch {
+          continue;
+        }
+        if (msg.type === "hello") {
+          if (ext?.socket === socket) {
+            ext.version = msg.version || "?";
+            ext.installType = msg.installType || null;
+          }
+          for (const w of [...waiters]) w(true);
+        } else if (msg.id !== undefined && pending.has(msg.id)) {
+          const p = pending.get(msg.id);
+          pending.delete(msg.id);
+          clearTimeout(p.timer);
+          p.resolve(msg.ok ? { ok: true, result: msg.result } : { ok: false, error: msg.error || "failed" });
+        }
+      }
+    });
+    socket.on("close", () => dropExtension(socket));
+    socket.on("error", () => dropExtension(socket));
+  });
+
+  const idle = setInterval(() => {
+    if (Date.now() - lastUse > idleMs) {
+      log("idle — exiting");
+      server.close();
+      clearInterval(idle);
+      for (const so of sockets) so.destroy();
+      server.emit("idle-exit");
+    }
+  }, Math.min(idleMs, 60000));
+  idle.unref();
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      resolve({
+        server,
+        port: server.address().port,
+        token,
+        connected: () => Boolean(ext),
+        close: () => {
+          clearInterval(idle);
+          for (const so of sockets) so.destroy();
+          server.closeAllConnections?.();
+          return new Promise((r) => server.close(() => r()));
+        },
+      });
+    });
+  });
+}
+
+// ── run as a program: gu starts it on demand, detached ──────────────────────────────────────
+async function main() {
+  const path = statePath();
+  const port = process.env.GU_BROWSER_PORT !== undefined ? Number(process.env.GU_BROWSER_PORT) : DEFAULT_PORT;
+  const log = (m) => process.stderr.write(`[gu-browser-bridge] ${m}\n`);
+  let b;
+  try {
+    b = await startBridge({ port, log });
+  } catch (e) {
+    log(`cannot listen on 127.0.0.1:${port}: ${e.code || e.message}`);
+    process.exit(3);
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify({ port: b.port, token: b.token, pid: process.pid, started: Date.now() / 1000 }), { mode: 0o600 });
+  log(`listening on 127.0.0.1:${b.port}`);
+  const cleanup = () => {
+    try {
+      if (JSON.parse(readFileSync(path, "utf8")).pid === process.pid) unlinkSync(path);
+    } catch {
+      /* gone */
+    }
+  };
+  b.server.on("idle-exit", () => {
+    cleanup();
+    process.exit(0);
+  });
+  for (const sig of ["SIGTERM", "SIGINT"]) process.on(sig, () => {
+    cleanup();
+    process.exit(0);
+  });
+}
+
+const isMain = (() => {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main();

package/browser-command.mjs

@@ -0,0 +1,310 @@
+// /browser (task #363, GitHub #144): is the gu Chrome extension connected, and how to install it.
+//
+// The extension is loaded from a FIXED folder, ~/.gonext/browser-extension, not from the npm
+// package: an update moves the package and Chrome would lose an unpacked extension loaded there.
+// The files are copied there (again after an update) every time this runs, as the agent does.
+import { spawn } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, openSync, closeSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sameProcess } from "./proc-identity.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const EXT_SRC = join(HERE, "browser-extension");
+export const EXT_FILES = ["manifest.json", "background.js", "actions.js", "popup.html", "popup.js", "icons/icon16.png", "icons/icon48.png", "icons/icon128.png"];
+
+const dataDir = () => join(homedir(), ".gonext");
+export const extensionDir = () => process.env.GU_BROWSER_EXT_DIR || join(dataDir(), "browser-extension");
+const statePath = () => process.env.GU_BROWSER_STATE || join(dataDir(), "browser-bridge.json");
+
+export function installExtensionFiles(src = EXT_SRC, dst = extensionDir()) {
+  mkdirSync(join(dst, "icons"), { recursive: true });
+  for (const n of EXT_FILES) {
+    const from = join(src, n);
+    const to = join(dst, n);
+    if (!existsSync(to) || !readFileSync(to).equals(readFileSync(from))) copyFileSync(from, to);
+  }
+  return dst;
+}
+
+function readState() {
+  try {
+    const st = JSON.parse(readFileSync(statePath(), "utf8"));
+    return st.port && st.token ? st : null;
+  } catch {
+    return null;
+  }
+}
+
+async function status(st, waitMs = 0) {
+  const r = await fetch(`http://127.0.0.1:${st.port}/status?wait_ms=${waitMs}`, {
+    headers: { authorization: `Bearer ${st.token}` },
+    signal: AbortSignal.timeout(waitMs + 3000),
+  });
+  return r.json();
+}
+
+// → { running, connected, version }. Starts the bridge when it is not running, so an extension
+// installed a moment from now has something to connect to.
+export async function bridgeStatus({ start = true, waitMs = 1500 } = {}) {
+  let st = readState();
+  try {
+    if (st) return { running: true, ...(await status(st, waitMs)) };
+  } catch {
+    /* stale state file */
+  }
+  if (!start) return { running: false, connected: false };
+  mkdirSync(dataDir(), { recursive: true });
+  const log = openSync(join(dataDir(), "browser-bridge.log"), "a");
+  spawn(process.execPath, [join(HERE, "browser-bridge.mjs")], { detached: true, stdio: ["ignore", log, log] }).unref();
+  closeSync(log);
+  const end = Date.now() + 5000;
+  while (Date.now() < end) {
+    await new Promise((r) => setTimeout(r, 150));
+    st = readState();
+    if (!st) continue;
+    try {
+      return { running: true, ...(await status(st, waitMs)) };
+    } catch {
+      /* not listening yet */
+    }
+  }
+  return { running: false, connected: false };
+}
+
+// The Chrome Web Store page of the gu extension, once published (#149/#150). Empty until then.
+export const STORE_URL = process.env.GU_BROWSER_STORE_URL || "";
+
+// "Always allow the browser in this folder" (#150) — the agent reads the same file
+// (gu_browser.allowed_in) before it asks.
+const allowPath = () => join(dirname(statePath()), "browser-allow.json");
+const real = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+};
+export function allowedIn(folder) {
+  try {
+    return (JSON.parse(readFileSync(allowPath(), "utf8")).folders || []).includes(real(folder));
+  } catch {
+    return false;
+  }
+}
+export function allowIn(folder, allow = true) {
+  let folders = [];
+  try {
+    folders = JSON.parse(readFileSync(allowPath(), "utf8")).folders || [];
+  } catch {
+    /* none yet */
+  }
+  const f = real(folder);
+  folders = [...folders.filter((x) => x !== f), ...(allow ? [f] : [])];
+  mkdirSync(dirname(allowPath()), { recursive: true });
+  writeFileSync(allowPath(), JSON.stringify({ folders }, null, 2));
+}
+
+export function browserReport({ connected, version, installType, refused = [] }, { allowed = false } = {}) {
+  // Two copies installed (the store one next to a developer one): the bridge kept one (#148).
+  const twoCopies = refused.length
+    ? [`⚠ A second gu extension (${refused.map((r) => r.id).join(", ")}) tried to connect and was`,
+      "⚠ turned away — two copies are installed. Keep one: /browser cleanup removes",
+      "⚠ the developer (unpacked) copy."]
+    : [];
+  const here = allowed
+    ? "In this folder it may, without asking (/browser forget to undo)."
+    : "In this folder it asks first (/browser allow to stop asking).";
+  if (connected) {
+    const kind = installType === "development" ? ", developer — loaded unpacked" : installType === "normal" ? ", Chrome Web Store" : "";
+    return [
+      `✓ The gu Chrome extension is connected (v${version}${kind}).`,
+      "The agent uses your Chrome, in its own tabs (the \"gu\" tab group) and tabs",
+      "you share from the extension's icon → Let gu use this tab.",
+      here,
+      ...twoCopies,
+    ];
+  }
+  return [
+    "Nothing to install. When the agent needs a browser it asks you first, then",
+    "opens gu's own Chrome window (a separate profile — not signed in to your",
+    "accounts) and works in it with a real mouse and keyboard.",
+    STORE_URL
+      ? `To let it use YOUR Chrome (your logins, a tab you share): ${STORE_URL}`
+      : "To let it use YOUR Chrome (your logins, a tab you share): /browser install",
+    here,
+    ...twoCopies,
+  ];
+}
+
+// /browser install — the extension, for the user's own Chrome. The store page when there is one;
+// until then the developer way (Developer mode → Load unpacked).
+export function installSteps(folder, platform = process.platform) {
+  if (STORE_URL) {
+    return [`Open ${STORE_URL} in Chrome and click "Add to Chrome".`, "Then type /browser — it should say connected."];
+  }
+  const pick = platform === "darwin"
+    ? ["     In the file dialog press ⌘⇧G, paste the folder (it is on your", "     clipboard) and press Enter."]
+    : ["     In the file dialog type or paste the folder (it starts with a dot,", "     so it is hidden)."];
+  return [
+    "The gu extension is not on the Chrome Web Store yet, so it is added the",
+    "developer way (you do not need it — gu's own window works without):",
+    "  1. Open Chrome and go to chrome://extensions",
+    "  2. Turn on Developer mode (top right)",
+    "  3. Click \"Load unpacked\" and choose this folder:",
+    `       ${folder}`,
+    ...pick,
+    "  4. Type /browser — it should say connected.",
+  ];
+}
+
+// macOS: open Chrome's extensions page. → whether it was opened.
+export function openExtensionsPage(platform = process.platform) {
+  // GU_NO_OPEN_APPS: the terminal tests, which must not open the real Chrome of whoever runs them.
+  if (platform !== "darwin" || process.env.GU_NO_OPEN_APPS || !existsSync("/Applications/Google Chrome.app")) return false;
+  try {
+    spawn("open", ["-a", "Google Chrome", "chrome://extensions"], { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// macOS: put the folder on the clipboard and open the extensions page, so step 3 is a paste.
+export function helpInstall(folder, platform = process.platform) {
+  if (platform !== "darwin" || process.env.GU_NO_OPEN_APPS) return false;
+  try {
+    const cp = spawn("pbcopy", [], { stdio: ["pipe", "ignore", "ignore"] });
+    cp.stdin.end(folder);
+  } catch {
+    /* best effort */
+  }
+  return openExtensionsPage(platform);
+}
+
+// ── the developer install, and cleaning it up (#145: #146 detect, #147 /browser cleanup) ──────
+const seenPath = () => join(dirname(statePath()), "browser-extension-seen");
+const logPath = () => join(dataDir(), "browser-bridge.log");
+
+// Where each Chromium browser keeps its profiles. Read only — gu never writes a browser's files.
+export function browserRoots(home = homedir(), platform = process.platform, env = process.env) {
+  const named = (list) => list.map(([browser, dir]) => ({ browser, dir }));
+  if (platform === "darwin") {
+    const a = join(home, "Library", "Application Support");
+    return named([["Chrome", join(a, "Google", "Chrome")], ["Chrome Beta", join(a, "Google", "Chrome Beta")],
+      ["Chrome Canary", join(a, "Google", "Chrome Canary")], ["Chromium", join(a, "Chromium")],
+      ["Edge", join(a, "Microsoft Edge")], ["Brave", join(a, "BraveSoftware", "Brave-Browser")]]);
+  }
+  if (platform === "win32") {
+    const l = env.LOCALAPPDATA || join(home, "AppData", "Local");
+    return named([["Chrome", join(l, "Google", "Chrome", "User Data")], ["Chrome Beta", join(l, "Google", "Chrome Beta", "User Data")],
+      ["Chrome Canary", join(l, "Google", "Chrome SxS", "User Data")], ["Chromium", join(l, "Chromium", "User Data")],
+      ["Edge", join(l, "Microsoft", "Edge", "User Data")], ["Brave", join(l, "BraveSoftware", "Brave-Browser", "User Data")]]);
+  }
+  const c = env.XDG_CONFIG_HOME || join(home, ".config");
+  return named([["Chrome", join(c, "google-chrome")], ["Chrome Beta", join(c, "google-chrome-beta")],
+    ["Chromium", join(c, "chromium")], ["Edge", join(c, "microsoft-edge")], ["Brave", join(c, "BraveSoftware", "Brave-Browser")]]);
+}
+
+const UNPACKED = new Set([4, 8]); // Chrome's Manifest::Location: UNPACKED (Load unpacked), COMMAND_LINE (--load-extension)
+
+function isGuExtension(path, entry, extDir) {
+  if (entry?.manifest?.name === "gu browser") return true;
+  if (path === extDir) return true; // the folder may already be deleted
+  try {
+    if (realpathSync(path) === realpathSync(extDir)) return true;
+  } catch {
+    /* one of them is gone */
+  }
+  try {
+    return JSON.parse(readFileSync(join(path, "manifest.json"), "utf8")).name === "gu browser";
+  } catch {
+    return false;
+  }
+}
+
+// → [{browser, profile, id, path}] for every profile with gu's extension loaded UNPACKED. A store
+// install is not listed — that is the one to keep.
+export function findDevInstalls({ roots = browserRoots(), extDir = extensionDir() } = {}) {
+  const found = [];
+  for (const { browser, dir } of roots) {
+    let profiles = [];
+    try {
+      profiles = readdirSync(dir).filter((p) => p === "Default" || /^Profile \d+$/.test(p));
+    } catch {
+      continue;
+    }
+    for (const profile of profiles) {
+      const seen = new Set();
+      for (const file of ["Secure Preferences", "Preferences"]) {
+        let settings;
+        try {
+          settings = JSON.parse(readFileSync(join(dir, profile, file), "utf8"))?.extensions?.settings || {};
+        } catch {
+          continue;
+        }
+        for (const [id, e] of Object.entries(settings)) {
+          if (seen.has(id) || !e || !UNPACKED.has(e.location) || typeof e.path !== "string") continue;
+          const path = isAbsolute(e.path) ? e.path : join(dir, profile, "Extensions", e.path);
+          if (!isGuExtension(path, e, extDir)) continue;
+          seen.add(id);
+          found.push({ browser, profile, id, path });
+        }
+      }
+    }
+  }
+  return found;
+}
+
+// gu's own leftovers of the developer install, in ~/.gonext.
+export function localLeftovers() {
+  return [extensionDir(), statePath(), seenPath(), logPath()].filter((p) => existsSync(p));
+}
+
+export async function bridgeCommand(cmd, timeoutMs = 15000) {
+  const st = readState();
+  if (!st) return { ok: false, error: "the bridge is not running" };
+  try {
+    const r = await fetch(`http://127.0.0.1:${st.port}/cmd`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${st.token}`, "content-type": "application/json" },
+      body: JSON.stringify({ ...cmd, timeout_ms: timeoutMs }),
+      signal: AbortSignal.timeout(timeoutMs + 3000),
+    });
+    return await r.json();
+  } catch (e) {
+    return { ok: false, error: String(e.message || e) };
+  }
+}
+
+/**
+ * Stop the bridge the state file names — only while that pid is still the bridge (#373, GitHub #154).
+ * The state outlives a bridge that crashed or a reboot; its pid may be someone else's by then. The
+ * bridge records `started` once it listens, so its process began at most a minute before that.
+ */
+export function stopBridge({ startOf } = {}) {
+  const st = readState();
+  if (!st?.pid) return false;
+  if (sameProcess(st.pid, st.started, { before: 60, after: 2, ...(startOf ? { startOf } : {}) }) !== "same") return false;
+  try {
+    process.kill(st.pid, "SIGTERM");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Deletes gu's files of the developer install. → the paths removed.
+export function removeLocalFiles() {
+  const gone = [];
+  for (const p of localLeftovers()) {
+    try {
+      rmSync(p, { recursive: true, force: true });
+      gone.push(p);
+    } catch {
+      /* reported by the rescan */
+    }
+  }
+  return gone;
+}