cdpilot 0.1.2 → 0.2.1

package/README.md

@@ -3,9 +3,15 @@
 > Zero-dependency browser automation from your terminal. One command, full control.
 
 [![npm version](https://img.shields.io/npm/v/cdpilot.svg)](https://www.npmjs.com/package/cdpilot)
+[![npm downloads](https://img.shields.io/npm/dm/cdpilot.svg)](https://www.npmjs.com/package/cdpilot)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-339933)](https://nodejs.org)
+[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![cdpilot MCP server](https://glama.ai/mcp/servers/mehmetnadir/cdpilot/badge)](https://glama.ai/mcp/servers/mehmetnadir/cdpilot)
 
-<!-- Demo GIF will be added after first release -->
+<div align="center">
+  <img src="cdpilot-demo.gif" alt="cdpilot demo" width="600" />
+</div>
 
 ## Quick Start
 
@@ -26,6 +32,9 @@ AI agents and developers need browser control that **just works**:
 - **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. cdpilot runs in its own profile
+- **Visual feedback** — Green glow overlay, cursor visualization, click ripples, and keystroke display keep you informed during automation
+- **Multi-project isolation** — Each project gets its own browser instance and port automatically, no conflicts
+- **AI control warning** — Red toast notification appears when you hover during active automation
 - **Privacy-first** — Everything runs locally. No data leaves your machine
 
 ### Why Brave?
@@ -271,6 +280,41 @@ Future paid offerings:
 
 Found a vulnerability? Please email the maintainer directly instead of opening a public issue.
 
+## Roadmap
+
+The only browser MCP with built-in test assertions. Here's what we've shipped and what's next:
+
+### Shipped
+
+- [x] 60+ CLI commands (navigate, click, fill, screenshot, PDF, console, network...)
+- [x] MCP server for AI agent integration (Claude Code, Cursor, etc.)
+- [x] **10 built-in test assertions** — assert, assert-url, assert-title, assert-count, assert-value, assert-attr, assert-visible/hidden, wait-for, check (batch), screenshot-diff
+- [x] **Accessibility tree snapshot** (`a11y-snapshot`) — structured data with @ref references, 500x fewer tokens than screenshots
+- [x] **Token-efficient screenshots** — element-level crop (13x smaller), JPEG quality control, format selection
+- [x] **Vision fallback** (`describe`) — a11y + screenshot + text in one call
+- [x] **Annotated screenshots** — @N badge overlays on interactive elements
+- [x] **Auto-wait** — MutationObserver-based, 5s automatic element waiting
+- [x] **Batch commands** — pipe JSON arrays via stdin for multi-step automation
+- [x] Visual feedback system (persistent green glow, cursor, ripples, keystroke display)
+- [x] AI control warning toast (red warning when user interacts during automation)
+- [x] Multi-project browser isolation (each project gets its own port + profile)
+- [x] Pre-flight wizard (auto-installs dependencies on first run)
+- [x] Persistent MCP glow (stays on during entire AI session, like Claude's orange glow)
+- [x] DevExtension system (native JS injection without browser store)
+
+### Coming Soon
+
+- [ ] **iframe & Shadow DOM** support — interact with elements inside iframes and shadow roots
+- [ ] **Session recording & replay** — record browser sessions and replay them deterministically
+- [ ] **Stealth mode** *(Pro)* — human-like mouse/typing, anti-fingerprint, CAPTCHA solving
+- [ ] **cdpilot Cloud** — hosted browser sessions API, REST + WebSocket MCP endpoint
+- [ ] **Chrome Extension** — use cdpilot from any browser without CLI
+- [ ] **Performance audit** — Core Web Vitals (LCP, CLS, INP) via CDP Performance domain
+- [ ] **WCAG accessibility audit** — automated a11y compliance reporting
+- [ ] **Claude Code Skill mode** — run as a `.claude/skills/` skill in addition to MCP
+
+Have an idea? [Open an issue](https://github.com/mehmetnadir/cdpilot/issues) or submit a PR!
+
 ## Contributing
 
 ```bash

package/bin/cdpilot.js

@@ -85,14 +85,13 @@ function findPython() {
 
 function runSetup() {
   const browser = findBrowser();
-  const profileDir = process.env.CDPILOT_PROFILE
-    || path.join(os.homedir(), '.cdpilot', 'profile');
-  const port = process.env.CDP_PORT || '9222';
+  const config = resolveProjectConfig();
 
   console.log('\n  cdpilot setup\n');
   console.log(`  Browser:  ${browser || '❌ Not found'}`);
-  console.log(`  Profile:  ${profileDir}`);
-  console.log(`  CDP Port: ${port}`);
+  console.log(`  Profile:  ${config.profileDir}`);
+  console.log(`  CDP Port: ${config.port === '0' ? 'auto' : config.port}`);
+  console.log(`  Project:  ${config.projectId || 'manual mode'}`);
   console.log(`  Python:   ${findPython() || '❌ Not found'}`);
 
   if (!browser) {
@@ -109,21 +108,97 @@ function runSetup() {
   }
 
   // Create profile directory
-  if (!fs.existsSync(profileDir)) {
-    fs.mkdirSync(profileDir, { recursive: true });
-    console.log(`\n  ✓ Created profile: ${profileDir}`);
+  if (!fs.existsSync(config.profileDir)) {
+    fs.mkdirSync(config.profileDir, { recursive: true });
+    console.log(`\n  ✓ Created profile: ${config.profileDir}`);
   } else {
-    console.log(`\n  ✓ Profile exists: ${profileDir}`);
+    console.log(`\n  ✓ Profile exists: ${config.profileDir}`);
   }
 
   console.log('  ✓ Setup complete! Run: cdpilot launch\n');
 }
 
+// ── Pre-flight Check (runs on first launch) ──
+
+function checkWebsockets(python) {
+  try {
+    execSync(`${python} -c "import websockets"`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function preflight() {
+  const markerFile = path.join(os.homedir(), '.cdpilot', '.preflight-done');
+
+  // Skip if already passed (not first run) and all deps present
+  const python = findPython();
+  const browser = findBrowser();
+  if (fs.existsSync(markerFile) && python && browser && checkWebsockets(python)) {
+    return; // All good, skip silently
+  }
+
+  console.log(`\n  cdpilot v${VERSION} — Pre-flight Check`);
+  console.log('  ' + '─'.repeat(35) + '\n');
+
+  // 1. Python
+  if (python) {
+    const ver = execSync(`${python} --version 2>&1`, { stdio: 'pipe' }).toString().trim();
+    console.log(`  ✓ ${ver}`);
+  } else {
+    console.log('  ✗ Python 3.8+ not found');
+    console.log('    → Install: https://www.python.org/downloads/\n');
+    process.exit(1);
+  }
+
+  // 2. websockets
+  if (checkWebsockets(python)) {
+    console.log('  ✓ websockets');
+  } else {
+    console.log('  ✗ websockets — installing...');
+    try {
+      execSync(`${python} -m pip install websockets --quiet --disable-pip-version-check`, { stdio: 'pipe' });
+      if (checkWebsockets(python)) {
+        console.log('  ✓ websockets (installed)');
+      } else {
+        console.log('  ✗ websockets install failed');
+        console.log('    → Run manually: pip install websockets\n');
+        process.exit(1);
+      }
+    } catch {
+      console.log('  ✗ websockets auto-install failed');
+      console.log('    → Run manually: pip install websockets\n');
+      process.exit(1);
+    }
+  }
+
+  // 3. Browser
+  if (browser) {
+    const name = path.basename(browser).replace(/\.exe$/i, '');
+    console.log(`  ✓ ${name} (${browser})`);
+  } else {
+    console.log('  ✗ No compatible browser found');
+    console.log('    → Install Brave (recommended): https://brave.com/download/');
+    console.log('    → Or Chrome: https://www.google.com/chrome/\n');
+    process.exit(1);
+  }
+
+  // Mark as done
+  const dir = path.dirname(markerFile);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(markerFile, new Date().toISOString());
+
+  console.log('\n  Ready!\n');
+}
+
 // ── Status Command ──
 
 function runStatus() {
-  const port = process.env.CDP_PORT || '9222';
-  console.log(`\n  cdpilot status (port ${port})\n`);
+  const config = resolveProjectConfig();
+  const port = config.port === '0' ? '9222' : config.port;
+  const projLabel = config.projectId ? ` [${config.projectId}]` : '';
+  console.log(`\n  cdpilot status (port ${port})${projLabel}\n`);
 
   try {
     const http = require('http');
@@ -162,6 +237,52 @@ function showVersion() {
   console.log(`cdpilot v${VERSION}`);
 }
 
+// ── Project-Based Multi-Instance ──
+
+function getProjectId() {
+  const cwd = process.cwd();
+  const dirName = path.basename(cwd).replace(/[^a-zA-Z0-9-]/g, '').slice(0, 20);
+  const crypto = require('crypto');
+  const hash = crypto.createHash('md5').update(cwd).digest('hex').slice(0, 6);
+  return dirName ? `${dirName}-${hash}` : hash;
+}
+
+function resolveProjectConfig() {
+  const envPort = process.env.CDP_PORT;
+  const envProfile = process.env.CDPILOT_PROFILE;
+
+  // Full manual override
+  if (envPort && envProfile) {
+    return { port: envPort, profileDir: envProfile, projectId: null };
+  }
+
+  const projectId = getProjectId();
+  const registryFile = path.join(os.homedir(), '.cdpilot', 'registry.json');
+  const defaultProfile = path.join(os.homedir(), '.cdpilot', 'projects', projectId, 'profile');
+
+  let registry = {};
+  try {
+    const data = JSON.parse(fs.readFileSync(registryFile, 'utf-8'));
+    registry = data.projects || {};
+  } catch {}
+
+  const info = registry[projectId];
+  if (info) {
+    return {
+      port: envPort || String(info.port || 9222),
+      profileDir: envProfile || info.profile_dir || defaultProfile,
+      projectId,
+    };
+  }
+
+  // New project: let Python allocate port (pass 0 for auto)
+  return {
+    port: envPort || '0',
+    profileDir: envProfile || defaultProfile,
+    projectId,
+  };
+}
+
 // ── Help ──
 
 function showHelp() {
@@ -203,6 +324,11 @@ function showHelp() {
     new-tab [url]      Open new tab
     close-tab [id]     Close tab
 
+  PROJECTS
+    projects           List all project browser instances
+    project-stop <id>  Stop a specific project's browser
+    stop-all           Stop all browser instances
+
   AI AGENT
     mcp                Start MCP server (stdin/stdout JSON-RPC)
 
@@ -234,6 +360,11 @@ if (cmd === 'status') {
   runStatus();
   // Don't exit immediately — let http callback complete
 } else {
+  // Pre-flight check on first run or 'launch' command
+  if (cmd === 'launch') {
+    preflight();
+  }
+
   // Delegate to Python
   const python = findPython();
   if (!python) {
@@ -242,16 +373,22 @@ if (cmd === 'status') {
   }
 
   const browser = findBrowser();
-  const profileDir = process.env.CDPILOT_PROFILE
-    || path.join(os.homedir(), '.cdpilot', 'profile');
-  const port = process.env.CDP_PORT || '9222';
+  const config = resolveProjectConfig();
 
   const env = {
     ...process.env,
-    CDP_PORT: port,
-    CDPILOT_PROFILE: profileDir,
+    CDPILOT_PROFILE: config.profileDir,
   };
 
+  // Only pass CDP_PORT if explicitly set or resolved from registry (not 0)
+  if (config.port !== '0') {
+    env.CDP_PORT = config.port;
+  }
+
+  if (config.projectId) {
+    env.CDPILOT_PROJECT_ID = config.projectId;
+  }
+
   if (browser && !process.env.CHROME_BIN) {
     env.CHROME_BIN = browser;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdpilot",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Zero-dependency browser automation from your terminal. One command, full control.",
   "bin": {
     "cdpilot": "./bin/cdpilot.js",
@@ -11,9 +11,12 @@
     "start": "node bin/cdpilot.js"
   },
   "keywords": [
-    "browser", "automation", "cdp", "chrome-devtools-protocol", "cli",
-    "devtools", "headless", "screenshot", "testing", "web-scraping",
-    "ai-agent", "mcp", "claude", "brave"
+    "browser-automation", "cdp", "chrome-devtools-protocol", "cli",
+    "mcp", "ai-agent", "web-scraping", "zero-dependency",
+    "headless-browser", "puppeteer-alternative", "playwright-alternative",
+    "screenshot", "pdf", "automation", "devtools", "browser",
+    "model-context-protocol", "claude", "brave", "testing",
+    "web-testing", "accessibility", "a11y"
   ],
   "author": "Mehmet Nadir",
   "license": "MIT",