opchrm 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenChrome contributors
+
+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

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# OpenChrome
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let your coding agent use the Chrome browser you're already using. OpenChrome connects MCP-compatible agents (OpenCode, Claude Code, Codex, Cursor) to your existing Chrome session — tabs, navigation, snapshots, clicks, typing, console, network, screenshots — so the agent can test and verify its own work.
+
+```text
+Agent --MCP(stdio)--> openchrome-mcp --WS(127.0.0.1:18721)--> daemon <--WS--> Chrome extension --> your tabs
+```
+
+## Install
+
+Requires Node.js 22+ and Chrome.
+
+```bash
+npm install -g opchrm
+opchrm daemon        # start the local bridge (leave running)
+```
+
+Load the extension once: `chrome://extensions` → Developer mode → Load unpacked → select the `extension/` folder from this repo (or unzip `dist/openchrome-extension.zip`).
+
+```bash
+opchrm init          # prints a pairing token
+```
+
+Paste the token into the extension popup → Pair. Verify:
+
+```bash
+opchrm status        # extensionConnected: true
+```
+
+## Use with OpenCode
+
+```json
+{
+  "mcp": {
+    "openchrome": {
+      "type": "local",
+      "command": ["openchrome-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+Then prompt: `Open localhost:3000/signup, fill the form, submit, and tell me whether it works.`
+
+## Tools
+
+14 MCP tools: `browser_status`, `browser_tabs`, `browser_select_tab`, `browser_open`, `browser_snapshot`, `browser_screenshot` (image), `browser_click`, `browser_type`, `browser_press`, `browser_back`, `browser_forward`, `browser_reload`, `browser_console`, `browser_network`.
+
+Snapshots return `[eN]` refs; refs go stale on navigation (`STALE_ELEMENT_REFERENCE` → snapshot again). Sensitive actions (password fields, non-allowlisted sites) return `NEEDS_APPROVAL` — approve in the popup, retry.
+
+## Permissions
+
+Default: `localhost` allowed, unknown sites ask, explicit rules in the popup (Allow/Ask/Deny per pattern). Denied tabs are hidden from the agent. Secrets (cookies, passwords, tokens) are never exposed; URLs are redacted in logs.
+
+## Develop
+
+```bash
+npm install
+npm run build          # typecheck + dist bundles for daemon, MCP server, extension
+npm run daemon         # run daemon from dist
+npm run mcp            # run MCP server from dist (stdio)
+npm run test-app       # deterministic test app on :3000 (/signup, /login, /js-error, /api-error…)
+npm run pack:extension # zip the extension for sideload/store
+```
+
+CLI manual mode (no MCP client needed): `node apps/mcp-server/dist/index.cjs browser_tabs`.
+
+## License
+
+MIT — see LICENSE.

package/apps/daemon/bin/openchrome.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// opc CLI: daemon | init | reset-token | status. Self-contained (no TS imports).
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const cmd = process.argv[2] ?? "help";
+const here = dirname(fileURLToPath(import.meta.url));
+const port = Number(process.env.OPENCHROME_PORT ?? 18721);
+
+function tokenPath() {
+  const dir = process.env.OPENCHROME_CONFIG_DIR ?? join(homedir(), ".openchrome");
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  return join(dir, "token");
+}
+function loadOrCreateToken() {
+  if (process.env.OPENCHROME_TOKEN) return process.env.OPENCHROME_TOKEN;
+  const p = tokenPath();
+  if (existsSync(p)) {
+    const t = readFileSync(p, "utf8").trim();
+    if (t.startsWith("oc_")) return t;
+  }
+  const t = "oc_" + randomBytes(16).toString("hex");
+  writeFileSync(p, t + "\n", { mode: 0o600 });
+  return t;
+}
+
+if (cmd === "daemon") {
+  const dist = join(here, "../dist/index.cjs");
+  const args = process.argv.slice(3);
+  if (existsSync(dist)) {
+    const child = spawn(process.execPath, [dist, ...args], { stdio: "inherit" });
+    child.on("exit", (c) => process.exit(c ?? 0));
+  } else {
+    console.error("dist missing; run `npm run build` first (or use tsx dev: node ./node_modules/tsx/dist/cli.mjs apps/daemon/src/index.ts)");
+    process.exit(1);
+  }
+} else if (cmd === "init") {
+  const token = loadOrCreateToken();
+  console.log(`OpenChrome\n\nDaemon token (paste into extension popup Pairing field):\n  ${token}\n\nDaemon endpoint: ws://127.0.0.1:${port}\n\nNext:\n  1. run: opchrm daemon (or npm run daemon)\n  2. load apps/extension in chrome://extensions (Developer mode)\n  3. paste token into popup -> Pair\n  4. run: opchrm status`);
+} else if (cmd === "reset-token") {
+  const t = "oc_" + randomBytes(16).toString("hex");
+  writeFileSync(tokenPath(), t + "\n", { mode: 0o600 });
+  console.log(t);
+} else if (cmd === "status") {
+  const token = loadOrCreateToken();
+  const { default: WebSocket } = await import("ws").catch(() => ({ default: null }));
+  if (!WebSocket) {
+    // fallback: raw TCP probe won't speak WS; just report daemon port state
+    const net = await import("node:net");
+    const s = net.connect(port, "127.0.0.1");
+    s.on("connect", () => { console.log(JSON.stringify({ daemonPort: port, reachable: true }, null, 2)); process.exit(0); });
+    s.on("error", () => { console.error("daemon not reachable on " + port); process.exit(1); });
+  } else {
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const id = Math.random().toString(36).slice(2);
+    const timer = setTimeout(() => { console.error("COMMAND_TIMEOUT"); process.exit(1); }, 8000);
+    ws.on("open", () => ws.send(JSON.stringify({ id: "reg1", type: "register", token, role: "mcp-shim" })));
+    ws.on("message", (raw) => {
+      const msg = JSON.parse(String(raw));
+      if (msg.id === "reg1" && msg.success) { ws.send(JSON.stringify({ id, type: "command", method: "status.get", params: {} })); return; }
+      if (msg.id === id) {
+        clearTimeout(timer);
+        console.log(JSON.stringify(msg.success ? msg.result : msg.error, null, 2));
+        ws.close();
+        process.exit(msg.success ? 0 : 1);
+      }
+    });
+  }
+} else {
+  console.log(`usage: opchrm <daemon|init|reset-token|status> [--port N]`);
+}