browser-cdp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Majestic Labs
+
+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,106 @@
+# browser-cdp
+
+Browser automation via Chrome DevTools Protocol. Control Chrome, Brave, Comet, or Edge using your real browser - same fingerprint, real cookies, no automation detection.
+
+## Install
+
+```bash
+npm install -g browser-cdp
+```
+
+## Usage
+
+```bash
+# Start browser with CDP enabled
+browser-cdp start [browser] [--profile] [--port=PORT]
+
+# Navigate to URL
+browser-cdp nav <url> [--new]
+
+# Execute JavaScript in page
+browser-cdp eval '<code>'
+
+# Take screenshot
+browser-cdp screenshot
+
+# Interactive element picker
+browser-cdp pick '<message>'
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DEBUG_PORT` | CDP debugging port | `9222` |
+| `BROWSER` | Browser to use (chrome, brave, comet, edge) | `chrome` |
+| `BROWSER_PATH` | Custom browser executable path | (auto-detect) |
+
+## Examples
+
+```bash
+# Start Brave with your profile
+browser-cdp start brave --profile
+
+# Start Chrome on custom port
+DEBUG_PORT=9333 browser-cdp start
+
+# Navigate and search
+browser-cdp nav https://google.com
+browser-cdp eval 'document.querySelector("textarea").value = "hello"'
+
+# Take screenshot
+browser-cdp screenshot
+# Returns: /tmp/screenshot-2024-01-01T12-00-00.png
+
+# Pick elements interactively
+browser-cdp pick "Select the login button"
+```
+
+## Pre-started Browser
+
+If you already have a browser running with CDP enabled, the CLI will connect to it:
+
+```bash
+# Add to ~/.zshrc
+alias brave-debug='/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222'
+
+# Start browser manually
+brave-debug
+
+# CLI detects and connects
+browser-cdp start  # "Browser already running on :9222"
+browser-cdp nav https://example.com
+```
+
+## Supported Browsers
+
+| Browser | Command | Profile Support |
+|---------|---------|-----------------|
+| Chrome | `chrome` (default) | Yes |
+| Brave | `brave` | Yes |
+| Comet | `comet` | No |
+| Edge | `edge` | Yes |
+
+## Platform Support
+
+Works on **macOS** and **Linux**. Browser paths auto-detected per platform.
+
+| Platform | Chrome Path | Config Path |
+|----------|-------------|-------------|
+| macOS | `/Applications/Google Chrome.app/...` | `~/Library/Application Support/Google/Chrome/` |
+| Linux | `/usr/bin/google-chrome` | `~/.config/google-chrome/` |
+
+Use `BROWSER_PATH` env var to override if your browser is installed elsewhere.
+
+## Why Real Browser?
+
+| Aspect | browser-cdp | Playwright Test Mode |
+|--------|-------------|---------------------|
+| Browser | Your installed Chrome/Brave/etc | Bundled Chromium |
+| Profile | Can use real cookies/logins | Fresh test profile |
+| Detection | Not detectable as automation | Automation flags present |
+| Use case | Real-world testing, scraping | Isolated E2E tests |
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+const commands = {
+  start: "./start.js",
+  nav: "./nav.js",
+  eval: "./eval.js",
+  screenshot: "./screenshot.js",
+  pick: "./pick.js",
+};
+
+function printUsage() {
+  console.log("browser-cdp - Browser automation via Chrome DevTools Protocol");
+  console.log("");
+  console.log("Usage: browser-cdp <command> [options]");
+  console.log("");
+  console.log("Commands:");
+  console.log("  start [browser]     Start browser with CDP enabled");
+  console.log("  nav <url>           Navigate to URL");
+  console.log("  eval '<code>'       Evaluate JavaScript in page");
+  console.log("  screenshot          Take screenshot of current page");
+  console.log("  pick '<message>'    Interactive element picker");
+  console.log("");
+  console.log("Environment:");
+  console.log("  DEBUG_PORT          CDP port (default: 9222)");
+  console.log("  BROWSER             Browser to use (chrome, brave, comet, edge)");
+  console.log("  BROWSER_PATH        Custom browser executable path");
+  console.log("");
+  console.log("Examples:");
+  console.log("  browser-cdp start brave --profile");
+  console.log("  browser-cdp nav https://google.com");
+  console.log("  browser-cdp eval 'document.title'");
+  console.log("  browser-cdp screenshot");
+  process.exit(0);
+}
+
+if (!command || command === "--help" || command === "-h") {
+  printUsage();
+}
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.log(`Available: ${Object.keys(commands).join(", ")}`);
+  process.exit(1);
+}
+
+// Re-run with the specific command script
+process.argv = [process.argv[0], commands[command], ...args];
+await import(commands[command]);

package/eval.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+
+const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+
+const code = process.argv.slice(2).join(" ");
+if (!code) {
+  console.log("Usage: eval.js 'code'");
+  console.log("\nExamples:");
+  console.log('  eval.js "document.title"');
+  console.log("  eval.js \"document.querySelectorAll('a').length\"");
+  process.exit(1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = pages[pages.length - 1];
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+let result;
+
+try {
+  result = await page.evaluate((c) => {
+    const AsyncFunction = (async () => {}).constructor;
+    return new AsyncFunction(`return (${c})`)();
+  }, code);
+} catch (e) {
+  console.log("Failed to evaluate expression");
+  console.log(`  Expression: ${code}`);
+  console.log(e);
+  process.exit(1);
+}
+
+if (Array.isArray(result)) {
+  for (let i = 0; i < result.length; i++) {
+    if (i > 0) console.log("");
+    for (const [key, value] of Object.entries(result[i])) {
+      console.log(`${key}: ${value}`);
+    }
+  }
+} else if (typeof result === "object" && result !== null) {
+  for (const [key, value] of Object.entries(result)) {
+    console.log(`${key}: ${value}`);
+  }
+} else {
+  console.log(result);
+}
+
+await browser.close();

package/nav.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+
+const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+
+const url = process.argv[2];
+const newTab = process.argv[3] === "--new";
+
+if (!url) {
+  console.log("Usage: nav.js <url> [--new]");
+  console.log("\nExamples:");
+  console.log("  nav.js https://example.com       # Navigate current tab");
+  console.log("  nav.js https://example.com --new # Open in new tab");
+  process.exit(1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0] || await browser.newContext();
+
+if (newTab) {
+  const page = await context.newPage();
+  await page.goto(url, { waitUntil: "domcontentloaded" });
+  console.log("Opened:", url);
+} else {
+  const pages = context.pages();
+  const page = pages[pages.length - 1] || await context.newPage();
+  await page.goto(url, { waitUntil: "domcontentloaded" });
+  console.log("Navigated to:", url);
+}
+
+await browser.close();

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "browser-cdp",
+  "version": "0.1.0",
+  "description": "Browser automation via Chrome DevTools Protocol - control Chrome, Brave, Comet, Edge with real browser profiles",
+  "type": "module",
+  "bin": {
+    "browser-cdp": "./cli.js"
+  },
+  "scripts": {
+    "start": "node cli.js"
+  },
+  "files": [
+    "cli.js",
+    "start.js",
+    "nav.js",
+    "eval.js",
+    "screenshot.js",
+    "pick.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dpaluy/browser-cdp.git"
+  },
+  "homepage": "https://github.com/dpaluy/browser-cdp#readme",
+  "bugs": {
+    "url": "https://github.com/dpaluy/browser-cdp/issues"
+  },
+  "dependencies": {
+    "playwright": "^1.49.0"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "cdp",
+    "chrome",
+    "brave",
+    "playwright",
+    "devtools"
+  ],
+  "author": "Majestic Labs",
+  "license": "MIT"
+}

package/pick.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+
+import { chromium } from "playwright";
+
+const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+
+const message = process.argv.slice(2).join(" ");
+if (!message) {
+  console.log("Usage: pick.js 'message'");
+  console.log("\nExample:");
+  console.log('  pick.js "Click the submit button"');
+  process.exit(1);
+}
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = pages[pages.length - 1];
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+// Inject pick() helper into current page
+await page.evaluate(() => {
+  if (!window.pick) {
+    window.pick = async (message) => {
+      if (!message) {
+        throw new Error("pick() requires a message parameter");
+      }
+      return new Promise((resolve) => {
+        const selections = [];
+        const selectedElements = new Set();
+
+        const overlay = document.createElement("div");
+        overlay.style.cssText =
+          "position:fixed;top:0;left:0;width:100%;height:100%;z-index:2147483647;pointer-events:none";
+
+        const highlight = document.createElement("div");
+        highlight.style.cssText =
+          "position:absolute;border:2px solid #3b82f6;background:rgba(59,130,246,0.1);transition:all 0.1s";
+        overlay.appendChild(highlight);
+
+        const banner = document.createElement("div");
+        banner.style.cssText =
+          "position:fixed;bottom:20px;left:50%;transform:translateX(-50%);background:#1f2937;color:white;padding:12px 24px;border-radius:8px;font:14px sans-serif;box-shadow:0 4px 12px rgba(0,0,0,0.3);pointer-events:auto;z-index:2147483647";
+
+        const updateBanner = () => {
+          banner.textContent = `${message} (${selections.length} selected, Cmd/Ctrl+click to add, Enter to finish, ESC to cancel)`;
+        };
+        updateBanner();
+
+        document.body.append(banner, overlay);
+
+        const cleanup = () => {
+          document.removeEventListener("mousemove", onMove, true);
+          document.removeEventListener("click", onClick, true);
+          document.removeEventListener("keydown", onKey, true);
+          overlay.remove();
+          banner.remove();
+          selectedElements.forEach((el) => {
+            el.style.outline = "";
+          });
+        };
+
+        const onMove = (e) => {
+          const el = document.elementFromPoint(e.clientX, e.clientY);
+          if (!el || overlay.contains(el) || banner.contains(el)) return;
+          const r = el.getBoundingClientRect();
+          highlight.style.cssText = `position:absolute;border:2px solid #3b82f6;background:rgba(59,130,246,0.1);top:${r.top}px;left:${r.left}px;width:${r.width}px;height:${r.height}px`;
+        };
+
+        const buildElementInfo = (el) => {
+          const parents = [];
+          let current = el.parentElement;
+          while (current && current !== document.body) {
+            const parentInfo = current.tagName.toLowerCase();
+            const id = current.id ? `#${current.id}` : "";
+            const cls = current.className
+              ? `.${current.className.trim().split(/\s+/).join(".")}`
+              : "";
+            parents.push(parentInfo + id + cls);
+            current = current.parentElement;
+          }
+
+          return {
+            tag: el.tagName.toLowerCase(),
+            id: el.id || null,
+            class: el.className || null,
+            text: el.textContent?.trim().slice(0, 200) || null,
+            html: el.outerHTML.slice(0, 500),
+            parents: parents.join(" > "),
+          };
+        };
+
+        const onClick = (e) => {
+          if (banner.contains(e.target)) return;
+          e.preventDefault();
+          e.stopPropagation();
+          const el = document.elementFromPoint(e.clientX, e.clientY);
+          if (!el || overlay.contains(el) || banner.contains(el)) return;
+
+          if (e.metaKey || e.ctrlKey) {
+            if (!selectedElements.has(el)) {
+              selectedElements.add(el);
+              el.style.outline = "3px solid #10b981";
+              selections.push(buildElementInfo(el));
+              updateBanner();
+            }
+          } else {
+            cleanup();
+            const info = buildElementInfo(el);
+            resolve(selections.length > 0 ? selections : info);
+          }
+        };
+
+        const onKey = (e) => {
+          if (e.key === "Escape") {
+            e.preventDefault();
+            cleanup();
+            resolve(null);
+          } else if (e.key === "Enter" && selections.length > 0) {
+            e.preventDefault();
+            cleanup();
+            resolve(selections);
+          }
+        };
+
+        document.addEventListener("mousemove", onMove, true);
+        document.addEventListener("click", onClick, true);
+        document.addEventListener("keydown", onKey, true);
+      });
+    };
+  }
+});
+
+const result = await page.evaluate((msg) => window.pick(msg), message);
+
+if (Array.isArray(result)) {
+  for (let i = 0; i < result.length; i++) {
+    if (i > 0) console.log("");
+    for (const [key, value] of Object.entries(result[i])) {
+      console.log(`${key}: ${value}`);
+    }
+  }
+} else if (typeof result === "object" && result !== null) {
+  for (const [key, value] of Object.entries(result)) {
+    console.log(`${key}: ${value}`);
+  }
+} else {
+  console.log(result);
+}
+
+await browser.close();

package/screenshot.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { chromium } from "playwright";
+
+const DEFAULT_PORT = process.env.DEBUG_PORT || 9222;
+
+const browser = await chromium.connectOverCDP(`http://localhost:${DEFAULT_PORT}`);
+const contexts = browser.contexts();
+const context = contexts[0];
+
+if (!context) {
+  console.error("No browser context found");
+  process.exit(1);
+}
+
+const pages = context.pages();
+const page = pages[pages.length - 1];
+
+if (!page) {
+  console.error("No active tab found");
+  process.exit(1);
+}
+
+const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+const filename = `screenshot-${timestamp}.png`;
+const filepath = join(tmpdir(), filename);
+
+await page.screenshot({ path: filepath });
+
+console.log(filepath);
+
+await browser.close();

package/start.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import { spawn, execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { chromium } from "playwright";
+
+const isMac = platform() === "darwin";
+const isLinux = platform() === "linux";
+
+// Browser configurations per platform
+const BROWSERS = {
+  chrome: {
+    name: "Google Chrome",
+    path: isMac
+      ? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+      : "/usr/bin/google-chrome",
+    process: "Google Chrome",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/Google/Chrome/`
+      : `${process.env.HOME}/.config/google-chrome/`,
+  },
+  brave: {
+    name: "Brave",
+    path: isMac
+      ? "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+      : "/usr/bin/brave-browser",
+    process: "Brave Browser",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/BraveSoftware/Brave-Browser/`
+      : `${process.env.HOME}/.config/BraveSoftware/Brave-Browser/`,
+  },
+  comet: {
+    name: "Comet",
+    path: isMac ? "/Applications/Comet.app/Contents/MacOS/Comet" : "/usr/bin/comet",
+    process: "Comet",
+    profileSource: null,
+  },
+  edge: {
+    name: "Microsoft Edge",
+    path: isMac
+      ? "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+      : "/usr/bin/microsoft-edge",
+    process: "Microsoft Edge",
+    profileSource: isMac
+      ? `${process.env.HOME}/Library/Application Support/Microsoft Edge/`
+      : `${process.env.HOME}/.config/microsoft-edge/`,
+  },
+};
+
+const DEFAULT_PORT = 9222;
+
+function printUsage() {
+  console.log("Usage: start.js [browser] [--profile] [--port=PORT]");
+  console.log("\nBrowsers:");
+  console.log("  chrome  - Google Chrome (default)");
+  console.log("  brave   - Brave Browser");
+  console.log("  comet   - Comet Browser");
+  console.log("  edge    - Microsoft Edge");
+  console.log("\nOptions:");
+  console.log("  --profile  Copy your browser profile (cookies, logins)");
+  console.log("  --port=N   Use custom debugging port (default: 9222)");
+  console.log("\nEnvironment variables:");
+  console.log("  BROWSER       Default browser (chrome, brave, comet, edge)");
+  console.log("  BROWSER_PATH  Custom browser executable path");
+  console.log("  DEBUG_PORT    Custom debugging port");
+  console.log("\nExamples:");
+  console.log("  start.js                    # Start Chrome with fresh profile");
+  console.log("  start.js brave --profile    # Start Brave with your profile");
+  console.log("  start.js comet              # Start Comet");
+  console.log("  start.js --port=9333        # Start Chrome on port 9333");
+  process.exit(1);
+}
+
+// Parse arguments
+const args = process.argv.slice(2);
+let browserName = process.env.BROWSER || "chrome";
+let useProfile = false;
+let port = parseInt(process.env.DEBUG_PORT) || DEFAULT_PORT;
+
+for (const arg of args) {
+  if (arg === "--help" || arg === "-h") {
+    printUsage();
+  } else if (arg === "--profile") {
+    useProfile = true;
+  } else if (arg.startsWith("--port=")) {
+    port = parseInt(arg.split("=")[1]);
+  } else if (BROWSERS[arg]) {
+    browserName = arg;
+  } else if (!arg.startsWith("--")) {
+    console.error(`Unknown browser: ${arg}`);
+    console.log(`Available: ${Object.keys(BROWSERS).join(", ")}`);
+    process.exit(1);
+  }
+}
+
+// Resolve browser config
+const browserPath = process.env.BROWSER_PATH || BROWSERS[browserName]?.path;
+const browserConfig = BROWSERS[browserName] || {
+  name: "Custom",
+  path: browserPath,
+  process: null,
+  profileSource: null,
+};
+
+if (!browserPath) {
+  console.error("No browser path specified");
+  printUsage();
+}
+
+if (!existsSync(browserPath)) {
+  console.error(`Browser not found: ${browserPath}`);
+  process.exit(1);
+}
+
+// Check if port is available or has a browser with CDP
+try {
+  const response = await fetch(`http://localhost:${port}/json/version`);
+  if (response.ok) {
+    // CDP endpoint responded - browser already running
+    console.log(`Browser already running on :${port}`);
+    process.exit(0);
+  } else {
+    // Port occupied by non-CDP process
+    console.error(`Error: Port ${port} is in use by another process (not a browser with CDP)`);
+    console.error(`Try a different port: ./start.js --port=9333`);
+    process.exit(1);
+  }
+} catch (err) {
+  if (err.cause?.code === "ECONNREFUSED") {
+    // Port is free, proceed to start browser
+  } else {
+    // Port occupied but not responding to CDP
+    console.error(`Error: Port ${port} is in use by another process`);
+    console.error(`Try a different port: ./start.js --port=9333`);
+    process.exit(1);
+  }
+}
+
+// Setup profile directory
+const cacheBase = isMac
+  ? `${process.env.HOME}/Library/Caches`
+  : `${process.env.HOME}/.cache`;
+const profileDir = `${cacheBase}/browser-cdp/${browserName}`;
+execFileSync("mkdir", ["-p", profileDir], { stdio: "ignore" });
+
+if (useProfile && browserConfig.profileSource) {
+  console.log(`Syncing profile from ${browserConfig.profileSource}...`);
+  try {
+    execFileSync("rsync", ["-a", "--delete", browserConfig.profileSource, `${profileDir}/`], {
+      stdio: "pipe",
+    });
+  } catch {
+    console.warn("Warning: Could not sync profile, using fresh profile");
+  }
+}
+
+// Start browser
+console.log(`Starting ${browserConfig.name} on port ${port}...`);
+
+spawn(browserPath, [`--remote-debugging-port=${port}`, `--user-data-dir=${profileDir}`], {
+  detached: true,
+  stdio: "ignore",
+}).unref();
+
+// Wait for browser to be ready
+let connected = false;
+for (let i = 0; i < 30; i++) {
+  try {
+    const browser = await chromium.connectOverCDP(`http://localhost:${port}`);
+    await browser.close();
+    connected = true;
+    break;
+  } catch {
+    await new Promise((r) => setTimeout(r, 500));
+  }
+}
+
+if (!connected) {
+  console.error(`Failed to connect to ${browserConfig.name} on port ${port}`);
+  process.exit(1);
+}
+
+console.log(
+  `${browserConfig.name} started on :${port}${useProfile ? " with your profile" : ""}`
+);