cdpilot 0.1.0

package/LICENSE

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

@@ -0,0 +1,283 @@
+# browserctl
+
+> Zero-dependency browser automation from your terminal. One command, full control.
+
+[![npm version](https://img.shields.io/npm/v/browserctl.svg)](https://www.npmjs.com/package/browserctl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+<!-- Demo GIF will be added after first release -->
+
+## Quick Start
+
+```bash
+npx browserctl launch    # Start browser with CDP
+npx browserctl go https://example.com
+npx browserctl shot      # Take screenshot
+```
+
+No config files. No boilerplate. Just `npx` and go.
+
+## Why browserctl?
+
+AI agents and developers need browser control that **just works**:
+
+- **Zero config** — `npx browserctl launch` starts an isolated browser session
+- **Zero dependency** — No Puppeteer, no Playwright, no Selenium. Pure CDP over HTTP
+- **40+ commands** — Navigate, click, type, screenshot, network, console, accessibility, and more
+- **AI-agent friendly** — Designed for Claude, GPT, Gemini, and any LLM tool-use workflow
+- **Isolated sessions** — Your personal browser stays untouched. browserctl runs in its own profile
+- **Privacy-first** — Everything runs locally. No data leaves your machine
+
+### Why Brave?
+
+browserctl uses [Brave Browser](https://brave.com) as its engine. Here's why:
+
+| Feature | Brave | Chrome | Why it matters |
+|---------|-------|--------|---------------|
+| **Built-in ad blocker** | Shields (native) | Extension needed | Pages load faster, less noise in DOM |
+| **Tracker blocking** | Default on | Manual config | Cleaner network logs for debugging |
+| **Fingerprint protection** | Native | None | Better privacy for automated sessions |
+| **Chromium-based** | Full CDP support | Full CDP support | Same DevTools Protocol, same power |
+| **Open source** | Yes (MPL 2.0) | Chromium yes, Chrome no | Transparent, auditable |
+| **Resource usage** | Lower memory | Higher memory | Better for running alongside your work |
+
+**TL;DR:** Brave = Chrome's power + built-in privacy + less bloat. Perfect for automation.
+
+> browserctl also works with Chrome and Chromium as fallback. Brave is recommended, not required.
+
+## Installation
+
+```bash
+# Use directly (no install needed)
+npx browserctl <command>
+
+# Or install globally
+npm i -g browserctl
+```
+
+**Requirements:** Node.js 18+ and one of: Brave Browser, Google Chrome, or Chromium.
+
+### First-time setup
+
+```bash
+npx browserctl setup     # Auto-detect browser, create isolated profile
+npx browserctl launch    # Start browser with CDP enabled
+npx browserctl status    # Check connection
+```
+
+## Commands
+
+### Navigation & Content
+
+```bash
+browserctl go <url>              # Navigate to URL
+browserctl content               # Get page text content
+browserctl html                  # Get page HTML
+browserctl shot [file]           # Take screenshot (PNG)
+browserctl pdf [file]            # Save page as PDF
+```
+
+### Interaction
+
+```bash
+browserctl click <selector>      # Click element
+browserctl type <selector> <text># Type into input
+browserctl fill <selector> <val> # Set input value (React-compatible)
+browserctl submit <form>         # Submit form
+browserctl hover <selector>      # Hover element
+browserctl keys <combo>          # Keyboard shortcut (ctrl+a, enter, etc.)
+browserctl scroll-to <selector>  # Scroll element into view
+browserctl drag <from> <to>      # Drag and drop
+```
+
+### Debugging
+
+```bash
+browserctl console [url]         # Capture console logs
+browserctl network [url]         # Monitor network requests
+browserctl debug [url]           # Full diagnostic (console+network+perf+shot)
+browserctl perf                  # Performance metrics
+browserctl eval <js>             # Execute JavaScript
+```
+
+### Tab Management
+
+```bash
+browserctl tabs                  # List open tabs
+browserctl new-tab [url]         # Open new tab
+browserctl switch-tab <id>       # Switch to tab
+browserctl close-tab [id]        # Close tab
+browserctl close                 # Close active tab
+```
+
+### Network Control
+
+```bash
+browserctl throttle slow3g       # Simulate slow 3G
+browserctl throttle fast3g       # Simulate fast 3G
+browserctl throttle offline      # Go offline
+browserctl throttle off          # Back to normal
+browserctl proxy <url>           # Set proxy
+browserctl proxy off             # Remove proxy
+```
+
+### Request Interception
+
+```bash
+browserctl intercept block <pattern>                    # Block requests
+browserctl intercept mock <pattern> <json-file>         # Mock responses
+browserctl intercept headers <pattern> <header:value>   # Add headers
+browserctl intercept list                               # List active rules
+browserctl intercept clear                              # Clear all rules
+```
+
+### Device Emulation
+
+```bash
+browserctl emulate iphone        # iPhone emulation
+browserctl emulate ipad          # iPad emulation
+browserctl emulate android       # Android emulation
+browserctl emulate reset         # Back to desktop
+```
+
+### Geolocation
+
+```bash
+browserctl geo istanbul          # Set location to Istanbul
+browserctl geo london            # Set location to London
+browserctl geo 41.01 28.97       # Custom coordinates
+browserctl geo off               # Remove override
+```
+
+### Accessibility
+
+```bash
+browserctl a11y                  # Full accessibility tree
+browserctl a11y summary          # Quick summary
+browserctl a11y find <role>      # Find elements by ARIA role
+```
+
+### Session Management
+
+```bash
+browserctl session               # Current session info
+browserctl sessions              # List all sessions
+browserctl session-close [id]    # Close session
+```
+
+### Advanced
+
+```bash
+browserctl cookies [domain]      # List cookies
+browserctl storage               # localStorage contents
+browserctl upload <sel> <file>   # Upload file to input
+browserctl multi-eval <js>       # Execute JS in all tabs
+browserctl headless [on|off]     # Toggle headless mode
+browserctl frame list            # List iframes
+browserctl dialog auto-accept    # Auto-accept dialogs
+browserctl permission grant geo  # Grant geolocation
+```
+
+## Use with AI Agents
+
+browserctl is designed to be called by AI agents as a tool:
+
+### Claude Code (MCP)
+
+```json
+{
+  "mcpServers": {
+    "browserctl": {
+      "command": "npx",
+      "args": ["browserctl", "mcp"]
+    }
+  }
+}
+```
+
+### Any LLM (tool-use)
+
+```json
+{
+  "name": "browser",
+  "description": "Control a browser via CDP",
+  "parameters": {
+    "command": "go https://example.com"
+  }
+}
+```
+
+### Python (subprocess)
+
+```python
+import subprocess
+result = subprocess.run(["npx", "browserctl", "go", url], capture_output=True, text=True)
+print(result.stdout)
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CDP_PORT` | `9222` | CDP debugging port |
+| `CHROME_BIN` | Auto-detect | Browser binary path |
+| `BROWSERCTL_PROFILE` | `~/.browserctl/profile` | Isolated browser profile |
+| `BROWSER_SESSION` | Auto | Session identifier |
+
+## How It Works
+
+```
+┌─────────────┐     HTTP/WebSocket      ┌──────────────┐
+│  browserctl │ ◄──────────────────────► │ Brave/Chrome │
+│   (CLI)     │    Chrome DevTools       │  (CDP mode)  │
+└─────────────┘     Protocol             └──────────────┘
+       │                                        │
+       │  Zero dependencies                     │  Isolated profile
+       │  Pure HTTP + WebSocket                 │  Separate from your
+       │  ~2500 lines, single file              │  personal browser
+       └────────────────────────────────────────┘
+```
+
+**No Puppeteer. No Playwright. No Selenium.** Just direct CDP communication.
+
+## Comparison
+
+| Feature | browserctl | Puppeteer | Playwright | Selenium |
+|---------|-----------|-----------|------------|----------|
+| Install size | **~50KB** | 400MB+ | 200MB+ | 100MB+ |
+| Dependencies | **0** | 50+ | 30+ | Java + drivers |
+| Setup time | **instant** | minutes | minutes | painful |
+| AI-agent ready | **yes** | manual | manual | manual |
+| Browser download | **no** | yes (Chromium) | yes (3 browsers) | no |
+| CLI-first | **yes** | no (library) | no (library) | no |
+| MCP support | **yes** | no | no | no |
+
+## Monetization / Pro (Coming Soon)
+
+browserctl CLI is and will always be **free and open source** (MIT).
+
+Future paid offerings:
+- **browserctl cloud** — Remote browser instances, no local browser needed
+- **Team dashboard** — Shared sessions, audit logs, usage analytics
+- **Priority support** — Direct help for enterprise integrations
+
+## Contributing
+
+```bash
+git clone https://github.com/user/browserctl.git
+cd browserctl
+npm install
+npm test
+```
+
+PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+## License
+
+MIT — do whatever you want.
+
+---
+
+<p align="center">
+  Built with the <a href="https://github.com/nicedoc/browserctl">browserctl</a> mindset: one tool, one job, done right.
+</p>

package/bin/browserctl.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+
+/**
+ * browserctl — Zero-dependency browser automation CLI
+ * Entry point: detects Python, finds browser, delegates to browserctl.py
+ */
+
+const { execSync, spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, '..', 'src', 'browserctl.py');
+const VERSION = require('../package.json').version;
+
+// ── Browser Detection ──
+
+function findBrowser() {
+  // User override
+  if (process.env.CHROME_BIN) {
+    if (fs.existsSync(process.env.CHROME_BIN)) return process.env.CHROME_BIN;
+  }
+
+  const platform = os.platform();
+  const candidates = [];
+
+  if (platform === 'darwin') {
+    candidates.push(
+      '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    );
+  } else if (platform === 'linux') {
+    candidates.push(
+      'brave-browser',
+      'brave',
+      'google-chrome',
+      'google-chrome-stable',
+      'chromium-browser',
+      'chromium',
+    );
+  } else if (platform === 'win32') {
+    const programFiles = process.env['PROGRAMFILES'] || 'C:\\Program Files';
+    const programFilesX86 = process.env['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)';
+    const localAppData = process.env.LOCALAPPDATA || '';
+    candidates.push(
+      path.join(programFiles, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
+      path.join(programFilesX86, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
+      path.join(localAppData, 'BraveSoftware', 'Brave-Browser', 'Application', 'brave.exe'),
+      path.join(programFiles, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      path.join(programFilesX86, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      path.join(localAppData, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    );
+  }
+
+  for (const bin of candidates) {
+    if (bin.startsWith('/') || bin.includes('\\')) {
+      if (fs.existsSync(bin)) return bin;
+    } else {
+      try {
+        execSync(`which ${bin} 2>/dev/null`, { stdio: 'pipe' });
+        return bin;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// ── Python Detection ──
+
+function findPython() {
+  for (const cmd of ['python3', 'python']) {
+    try {
+      const ver = execSync(`${cmd} --version 2>&1`, { stdio: 'pipe' }).toString().trim();
+      const match = ver.match(/(\d+)\.(\d+)/);
+      if (match && parseInt(match[1]) >= 3 && parseInt(match[2]) >= 8) {
+        return cmd;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+// ── Setup Command ──
+
+function runSetup() {
+  const browser = findBrowser();
+  const profileDir = process.env.BROWSERCTL_PROFILE
+    || path.join(os.homedir(), '.browserctl', 'profile');
+  const port = process.env.CDP_PORT || '9222';
+
+  console.log('\n  browserctl setup\n');
+  console.log(`  Browser:  ${browser || '❌ Not found'}`);
+  console.log(`  Profile:  ${profileDir}`);
+  console.log(`  CDP Port: ${port}`);
+  console.log(`  Python:   ${findPython() || '❌ Not found'}`);
+
+  if (!browser) {
+    console.log('\n  ❌ No compatible browser found.');
+    console.log('  Install Brave (recommended): https://brave.com/download/');
+    console.log('  Or Google Chrome: https://www.google.com/chrome/\n');
+    process.exit(1);
+  }
+
+  if (!findPython()) {
+    console.log('\n  ❌ Python 3.8+ not found.');
+    console.log('  Install: https://www.python.org/downloads/\n');
+    process.exit(1);
+  }
+
+  // Create profile directory
+  if (!fs.existsSync(profileDir)) {
+    fs.mkdirSync(profileDir, { recursive: true });
+    console.log(`\n  ✓ Created profile: ${profileDir}`);
+  } else {
+    console.log(`\n  ✓ Profile exists: ${profileDir}`);
+  }
+
+  console.log('  ✓ Setup complete! Run: browserctl launch\n');
+}
+
+// ── Status Command ──
+
+function runStatus() {
+  const port = process.env.CDP_PORT || '9222';
+  console.log(`\n  browserctl status (port ${port})\n`);
+
+  try {
+    const http = require('http');
+    const req = http.get(`http://127.0.0.1:${port}/json/version`, { timeout: 2000 }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => data += chunk);
+      res.on('end', () => {
+        try {
+          const info = JSON.parse(data);
+          console.log(`  ✓ Connected`);
+          console.log(`  Browser: ${info.Browser || 'Unknown'}`);
+          console.log(`  Protocol: ${info['Protocol-Version'] || 'Unknown'}`);
+          console.log(`  WebSocket: ${info.webSocketDebuggerUrl || 'N/A'}\n`);
+        } catch {
+          console.log('  ✓ CDP responding but version info unavailable\n');
+        }
+      });
+    });
+    req.on('error', () => {
+      console.log('  ❌ No browser connected on this port.');
+      console.log('  Run: browserctl launch\n');
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      console.log('  ❌ Connection timeout.');
+      console.log('  Run: browserctl launch\n');
+    });
+  } catch {
+    console.log('  ❌ Could not check status.\n');
+  }
+}
+
+// ── Version ──
+
+function showVersion() {
+  console.log(`browserctl v${VERSION}`);
+}
+
+// ── Help ──
+
+function showHelp() {
+  console.log(`
+  browserctl v${VERSION} — Zero-dependency browser automation
+
+  USAGE
+    browserctl <command> [args]
+
+  SETUP
+    setup              Auto-detect browser, create isolated profile
+    launch             Start browser with CDP enabled
+    status             Check browser connection
+    stop               Stop browser
+
+  NAVIGATION
+    go <url>           Navigate to URL
+    content            Get page text content
+    html               Get page HTML
+    shot [file]        Take screenshot
+    pdf [file]         Save page as PDF
+
+  INTERACTION
+    click <sel>        Click element
+    type <sel> <text>  Type into input
+    fill <sel> <val>   Set input value (React-compatible)
+    submit <form>      Submit form
+    hover <sel>        Hover element
+    keys <combo>       Keyboard shortcut
+
+  DEBUGGING
+    console [url]      Capture console logs
+    network [url]      Monitor network requests
+    debug [url]        Full diagnostic
+    eval <js>          Execute JavaScript
+
+  TABS
+    tabs               List open tabs
+    new-tab [url]      Open new tab
+    close-tab [id]     Close tab
+
+  More: https://github.com/user/browserctl#commands
+`);
+}
+
+// ── Main ──
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (cmd === '--version' || cmd === '-v') {
+  showVersion();
+  process.exit(0);
+}
+
+if (cmd === 'setup') {
+  runSetup();
+  process.exit(0);
+}
+
+if (cmd === 'status') {
+  runStatus();
+  // Don't exit immediately — let http callback complete
+} else {
+  // Delegate to Python
+  const python = findPython();
+  if (!python) {
+    console.error('Error: Python 3.8+ required. Install: https://www.python.org/downloads/');
+    process.exit(1);
+  }
+
+  const browser = findBrowser();
+  const profileDir = process.env.BROWSERCTL_PROFILE
+    || path.join(os.homedir(), '.browserctl', 'profile');
+  const port = process.env.CDP_PORT || '9222';
+
+  const env = {
+    ...process.env,
+    CDP_PORT: port,
+    BROWSERCTL_PROFILE: profileDir,
+  };
+
+  if (browser && !process.env.CHROME_BIN) {
+    env.CHROME_BIN = browser;
+  }
+
+  const child = spawn(python, [SCRIPT, ...args], {
+    stdio: 'inherit',
+    env,
+  });
+
+  child.on('close', (code) => {
+    process.exit(code || 0);
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "cdpilot",
+  "version": "0.1.0",
+  "description": "Zero-dependency browser automation from your terminal. One command, full control.",
+  "bin": {
+    "bctl": "./bin/browserctl.js",
+    "browserctl": "./bin/browserctl.js"
+  },
+  "scripts": {
+    "test": "node test/test.js",
+    "start": "node bin/browserctl.js"
+  },
+  "keywords": [
+    "browser",
+    "automation",
+    "cdp",
+    "chrome-devtools-protocol",
+    "cli",
+    "devtools",
+    "headless",
+    "screenshot",
+    "testing",
+    "web-scraping",
+    "ai-agent",
+    "mcp",
+    "claude",
+    "brave"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/browserctl"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}