surfagent 1.0.0 → 1.0.2

package/README.md

@@ -1,4 +1,4 @@
-# webpilot
+# surfagent
 
 A local API that gives AI agents structured page data from your Chrome browser. Instead of guessing selectors or taking screenshots, your agent gets a complete map of every element, form, and link on the page — then acts on it precisely.
 
@@ -6,24 +6,23 @@ A local API that gives AI agents structured page data from your Chrome browser.
 
 ## Quick Start
 
-**1. Install**
 ```bash
-npm install webpilot
-npm install
+npm install -g surfagent
+surfagent start
 ```
 
-**2. Start Chrome with debugging**
-```bash
-./scripts/start-chrome.sh
-```
+That's it. Chrome opens with debug mode, API starts on `http://localhost:3456`. Your agent can start calling it immediately.
+
+### Other commands
 
-**3. Start the API**
 ```bash
-npm run api
+surfagent start     # Start Chrome + API (one command)
+surfagent chrome    # Start Chrome debug session only
+surfagent api       # Start API only (Chrome must be running)
+surfagent health    # Check if everything is running
+surfagent help      # Show all options
 ```
 
-That's it. The API is running on `http://localhost:3456`.
-
 ## Your First Recon
 
 Open any website in Chrome, then:

package/dist/api/act.d.ts

@@ -70,17 +70,6 @@ export declare function readPage(tabPattern: string, options: {
     host?: string;
     selector?: string;
 }): Promise<any>;
-export declare function screenshotTab(tabPattern: string, options: {
-    port?: number;
-    host?: string;
-    selector?: string;
-    clip?: {
-        x: number;
-        y: number;
-        width: number;
-        height: number;
-    };
-}): Promise<string>;
 export interface CaptchaRequest {
     tab: string;
     action: 'detect' | 'read' | 'next' | 'prev' | 'submit' | 'audio' | 'restart';

package/dist/api/act.js

@@ -357,33 +357,6 @@ export async function readPage(tabPattern, options) {
         throw error;
     }
 }
-export async function screenshotTab(tabPattern, options) {
-    const port = options.port || 9222;
-    const host = options.host || 'localhost';
-    const tab = await resolveTab(tabPattern, port, host);
-    const client = await connectToTab(tab.id, port, host);
-    try {
-        // If selector provided, get its bounding rect and use as clip
-        let clip = options.clip;
-        if (options.selector && !clip) {
-            const r = await client.Runtime.evaluate({
-                expression: `(function(){ const el = document.querySelector(${JSON.stringify(options.selector)}); if(!el) return null; const r = el.getBoundingClientRect(); return { x: r.x, y: r.y, width: r.width, height: r.height, scale: 1 } })()`,
-                returnByValue: true
-            });
-            clip = r.result.value;
-        }
-        const params = { format: 'png', fromSurface: true };
-        if (clip)
-            params.clip = { ...clip, scale: 2 }; // 2x for sharper zoom
-        const result = await client.Page.captureScreenshot(params);
-        await client.close();
-        return result.data; // base64 PNG
-    }
-    catch (error) {
-        await client.close();
-        throw error;
-    }
-}
 const CAPTCHA_DETECT_SCRIPT = `
 (function() {
   // Find captcha iframes on the page

package/dist/api/server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import http from 'node:http';
 import { reconUrl, reconTab } from './recon.js';
-import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract, screenshotTab } from './act.js';
+import { fillFields, clickElement, scrollPage, navigatePage, evalInTab, focusTab, readPage, captchaInteract } from './act.js';
 import { getAllTabs } from '../chrome/tabs.js';
 const PORT = parseInt(process.env.API_PORT || '3456', 10);
 const CDP_PORT = parseInt(process.env.CDP_PORT || '9222', 10);
@@ -82,21 +82,6 @@ const server = http.createServer(async (req, res) => {
             const result = await scrollPage(body, { port: CDP_PORT, host: CDP_HOST });
             return json(res, 200, result);
         }
-        // POST /screenshot — capture full page, element, or region at 2x resolution
-        if (path === '/screenshot' && req.method === 'POST') {
-            const body = JSON.parse(await readBody(req));
-            if (!body.tab) {
-                return json(res, 400, { error: 'Provide "tab", optional "selector" or "clip" {x,y,width,height}' });
-            }
-            const data = await screenshotTab(body.tab, { port: CDP_PORT, host: CDP_HOST, selector: body.selector, clip: body.clip });
-            // Return as base64 or save to file
-            if (body.output) {
-                const fs = await import('node:fs');
-                fs.writeFileSync(body.output, Buffer.from(data, 'base64'));
-                return json(res, 200, { success: true, output: body.output });
-            }
-            return json(res, 200, { data });
-        }
         // POST /captcha — detect and interact with captchas
         if (path === '/captcha' && req.method === 'POST') {
             const body = JSON.parse(await readBody(req));

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+import { execSync, spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CDP_PORT = parseInt(process.env.CDP_PORT || '9222', 10);
+const API_PORT = parseInt(process.env.API_PORT || '3456', 10);
+function log(msg) {
+    console.log(`[surfagent] ${msg}`);
+}
+function checkCDP() {
+    return new Promise((resolve) => {
+        const req = http.get(`http://localhost:${CDP_PORT}/json/version`, (res) => {
+            resolve(res.statusCode === 200);
+        });
+        req.on('error', () => resolve(false));
+        req.setTimeout(1000, () => { req.destroy(); resolve(false); });
+    });
+}
+function detectOS() {
+    const platform = process.platform;
+    if (platform === 'darwin')
+        return 'mac';
+    if (platform === 'win32')
+        return 'windows';
+    return 'linux';
+}
+function getChromePath() {
+    const os = detectOS();
+    const paths = {
+        mac: [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+        ],
+        linux: [
+            '/usr/bin/google-chrome',
+            '/usr/bin/google-chrome-stable',
+            '/usr/bin/chromium-browser',
+            '/usr/bin/chromium',
+            '/snap/bin/chromium',
+        ],
+        windows: [
+            'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+            'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+            `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+        ],
+    };
+    for (const p of paths[os] || []) {
+        try {
+            execSync(`test -f "${p}"`, { stdio: 'ignore' });
+            return p;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function startChrome(chromePath) {
+    const userDataDir = process.env.CHROME_USER_DATA_DIR || '/tmp/surfagent-chrome';
+    // Copy cookies from default Chrome profile if available and dir is fresh
+    const os = detectOS();
+    try {
+        execSync(`mkdir -p "${userDataDir}/Default"`, { stdio: 'ignore' });
+        if (os === 'mac') {
+            const defaultProfile = `${process.env.HOME}/Library/Application Support/Google/Chrome/Default`;
+            execSync(`cp "${defaultProfile}/Cookies" "${userDataDir}/Default/" 2>/dev/null || true`, { stdio: 'ignore' });
+        }
+        else if (os === 'linux') {
+            const defaultProfile = `${process.env.HOME}/.config/google-chrome/Default`;
+            execSync(`cp "${defaultProfile}/Cookies" "${userDataDir}/Default/" 2>/dev/null || true`, { stdio: 'ignore' });
+        }
+    }
+    catch { }
+    const args = [
+        `--user-data-dir=${userDataDir}`,
+        `--remote-debugging-port=${CDP_PORT}`,
+        '--disable-save-password-bubble',
+        '--disable-popup-blocking',
+        '--disable-notifications',
+        '--disable-infobars',
+        '--disable-translate',
+        '--disable-features=PasswordManager,AutofillSaveCardBubble,TranslateUI',
+        '--password-store=basic',
+    ];
+    const chrome = spawn(chromePath, args, {
+        detached: true,
+        stdio: 'ignore',
+    });
+    chrome.unref();
+    log(`Chrome started (pid ${chrome.pid}) on port ${CDP_PORT}`);
+}
+async function waitForCDP(maxWait = 10000) {
+    const start = Date.now();
+    while (Date.now() - start < maxWait) {
+        if (await checkCDP())
+            return true;
+        await new Promise(r => setTimeout(r, 500));
+    }
+    return false;
+}
+async function main() {
+    const command = process.argv[2];
+    if (command === 'help' || command === '--help' || command === '-h') {
+        console.log(`
+surfagent — Browser Recon API for AI agents
+
+Usage:
+  surfagent start     Start Chrome + API server
+  surfagent api       Start API only (Chrome must be running)
+  surfagent chrome    Start Chrome debug session only
+  surfagent health    Check if everything is running
+  surfagent help      Show this message
+
+Environment variables:
+  CDP_PORT            Chrome debug port (default: 9222)
+  API_PORT            API server port (default: 3456)
+  CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
+
+After starting, your AI agent can call http://localhost:3456
+Full API docs: https://github.com/AllAboutAI-YT/webpilot#readme
+`);
+        return;
+    }
+    if (command === 'health') {
+        const cdp = await checkCDP();
+        console.log(`Chrome CDP (port ${CDP_PORT}): ${cdp ? 'connected' : 'not running'}`);
+        if (cdp) {
+            try {
+                const res = await fetch(`http://localhost:${API_PORT}/health`);
+                const data = await res.json();
+                console.log(`API (port ${API_PORT}): ${data.status} — ${data.tabCount} tabs`);
+            }
+            catch {
+                console.log(`API (port ${API_PORT}): not running`);
+            }
+        }
+        return;
+    }
+    if (command === 'chrome') {
+        const cdpRunning = await checkCDP();
+        if (cdpRunning) {
+            log(`Chrome already running on port ${CDP_PORT}`);
+            return;
+        }
+        const chromePath = getChromePath();
+        if (!chromePath) {
+            console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+            process.exit(1);
+        }
+        startChrome(chromePath);
+        const connected = await waitForCDP();
+        if (!connected) {
+            console.error('[surfagent] Chrome started but CDP not responding. Check port ' + CDP_PORT);
+            process.exit(1);
+        }
+        log('Chrome ready');
+        return;
+    }
+    if (command === 'api') {
+        const cdpRunning = await checkCDP();
+        if (!cdpRunning) {
+            console.error(`[surfagent] Chrome not running on port ${CDP_PORT}. Run: surfagent chrome`);
+            process.exit(1);
+        }
+        await import('./api/server.js');
+        return;
+    }
+    if (command === 'start' || !command) {
+        log('Starting...');
+        // 1. Check/start Chrome
+        let cdpRunning = await checkCDP();
+        if (cdpRunning) {
+            log(`Chrome already running on port ${CDP_PORT}`);
+        }
+        else {
+            const chromePath = getChromePath();
+            if (!chromePath) {
+                console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+                process.exit(1);
+            }
+            startChrome(chromePath);
+            cdpRunning = await waitForCDP();
+            if (!cdpRunning) {
+                console.error('[surfagent] Chrome failed to start. Try running it manually with --remote-debugging-port=9222');
+                process.exit(1);
+            }
+            log('Chrome ready');
+        }
+        // 2. Start API
+        await import('./api/server.js');
+        return;
+    }
+    console.error(`Unknown command: ${command}. Run: surfagent help`);
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error('[surfagent]', err.message);
+    process.exit(1);
+});

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "surfagent",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Local API that gives AI agents structured page data from Chrome for fast, precise web navigation",
   "main": "dist/api/server.js",
   "type": "module",
+  "bin": {
+    "surfagent": "dist/cli.js"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "api": "node dist/api/server.js"
+    "api": "node dist/api/server.js",
+    "start": "node dist/cli.js start"
   },
   "dependencies": {
     "chrome-remote-interface": "^0.33.0",

package/src/cli.ts

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import { execSync, spawn } from 'node:child_process';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const CDP_PORT = parseInt(process.env.CDP_PORT || '9222', 10);
+const API_PORT = parseInt(process.env.API_PORT || '3456', 10);
+
+function log(msg: string) {
+  console.log(`[surfagent] ${msg}`);
+}
+
+function checkCDP(): Promise<boolean> {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${CDP_PORT}/json/version`, (res) => {
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.setTimeout(1000, () => { req.destroy(); resolve(false); });
+  });
+}
+
+function detectOS(): 'mac' | 'linux' | 'windows' {
+  const platform = process.platform;
+  if (platform === 'darwin') return 'mac';
+  if (platform === 'win32') return 'windows';
+  return 'linux';
+}
+
+function getChromePath(): string | null {
+  const os = detectOS();
+  const paths: Record<string, string[]> = {
+    mac: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    linux: [
+      '/usr/bin/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chromium',
+      '/snap/bin/chromium',
+    ],
+    windows: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+  };
+
+  for (const p of paths[os] || []) {
+    try {
+      execSync(`test -f "${p}"`, { stdio: 'ignore' });
+      return p;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+function startChrome(chromePath: string) {
+  const userDataDir = process.env.CHROME_USER_DATA_DIR || '/tmp/surfagent-chrome';
+
+  // Copy cookies from default Chrome profile if available and dir is fresh
+  const os = detectOS();
+  try {
+    execSync(`mkdir -p "${userDataDir}/Default"`, { stdio: 'ignore' });
+
+    if (os === 'mac') {
+      const defaultProfile = `${process.env.HOME}/Library/Application Support/Google/Chrome/Default`;
+      execSync(`cp "${defaultProfile}/Cookies" "${userDataDir}/Default/" 2>/dev/null || true`, { stdio: 'ignore' });
+    } else if (os === 'linux') {
+      const defaultProfile = `${process.env.HOME}/.config/google-chrome/Default`;
+      execSync(`cp "${defaultProfile}/Cookies" "${userDataDir}/Default/" 2>/dev/null || true`, { stdio: 'ignore' });
+    }
+  } catch {}
+
+  const args = [
+    `--user-data-dir=${userDataDir}`,
+    `--remote-debugging-port=${CDP_PORT}`,
+    '--disable-save-password-bubble',
+    '--disable-popup-blocking',
+    '--disable-notifications',
+    '--disable-infobars',
+    '--disable-translate',
+    '--disable-features=PasswordManager,AutofillSaveCardBubble,TranslateUI',
+    '--password-store=basic',
+  ];
+
+  const chrome = spawn(chromePath, args, {
+    detached: true,
+    stdio: 'ignore',
+  });
+
+  chrome.unref();
+  log(`Chrome started (pid ${chrome.pid}) on port ${CDP_PORT}`);
+}
+
+async function waitForCDP(maxWait = 10000): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    if (await checkCDP()) return true;
+    await new Promise(r => setTimeout(r, 500));
+  }
+  return false;
+}
+
+async function main() {
+  const command = process.argv[2];
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(`
+surfagent — Browser Recon API for AI agents
+
+Usage:
+  surfagent start     Start Chrome + API server
+  surfagent api       Start API only (Chrome must be running)
+  surfagent chrome    Start Chrome debug session only
+  surfagent health    Check if everything is running
+  surfagent help      Show this message
+
+Environment variables:
+  CDP_PORT            Chrome debug port (default: 9222)
+  API_PORT            API server port (default: 3456)
+  CHROME_USER_DATA_DIR  Chrome profile directory (default: /tmp/surfagent-chrome)
+
+After starting, your AI agent can call http://localhost:3456
+Full API docs: https://github.com/AllAboutAI-YT/webpilot#readme
+`);
+    return;
+  }
+
+  if (command === 'health') {
+    const cdp = await checkCDP();
+    console.log(`Chrome CDP (port ${CDP_PORT}): ${cdp ? 'connected' : 'not running'}`);
+    if (cdp) {
+      try {
+        const res = await fetch(`http://localhost:${API_PORT}/health`);
+        const data = await res.json();
+        console.log(`API (port ${API_PORT}): ${data.status} — ${data.tabCount} tabs`);
+      } catch {
+        console.log(`API (port ${API_PORT}): not running`);
+      }
+    }
+    return;
+  }
+
+  if (command === 'chrome') {
+    const cdpRunning = await checkCDP();
+    if (cdpRunning) {
+      log(`Chrome already running on port ${CDP_PORT}`);
+      return;
+    }
+
+    const chromePath = getChromePath();
+    if (!chromePath) {
+      console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+      process.exit(1);
+    }
+
+    startChrome(chromePath);
+    const connected = await waitForCDP();
+    if (!connected) {
+      console.error('[surfagent] Chrome started but CDP not responding. Check port ' + CDP_PORT);
+      process.exit(1);
+    }
+    log('Chrome ready');
+    return;
+  }
+
+  if (command === 'api') {
+    const cdpRunning = await checkCDP();
+    if (!cdpRunning) {
+      console.error(`[surfagent] Chrome not running on port ${CDP_PORT}. Run: surfagent chrome`);
+      process.exit(1);
+    }
+    await import('./api/server.js');
+    return;
+  }
+
+  if (command === 'start' || !command) {
+    log('Starting...');
+
+    // 1. Check/start Chrome
+    let cdpRunning = await checkCDP();
+    if (cdpRunning) {
+      log(`Chrome already running on port ${CDP_PORT}`);
+    } else {
+      const chromePath = getChromePath();
+      if (!chromePath) {
+        console.error('[surfagent] Chrome not found. Install Google Chrome and try again.');
+        process.exit(1);
+      }
+      startChrome(chromePath);
+      cdpRunning = await waitForCDP();
+      if (!cdpRunning) {
+        console.error('[surfagent] Chrome failed to start. Try running it manually with --remote-debugging-port=9222');
+        process.exit(1);
+      }
+      log('Chrome ready');
+    }
+
+    // 2. Start API
+    await import('./api/server.js');
+    return;
+  }
+
+  console.error(`Unknown command: ${command}. Run: surfagent help`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('[surfagent]', err.message);
+  process.exit(1);
+});

package/scripts/start-chrome.sh

@@ -1,33 +0,0 @@
-#!/bin/bash
-
-# Start Chrome with remote debugging enabled
-# Uses a separate profile with copied auth data (required for Chrome 136+)
-
-PORT=${1:-9222}
-MAIN_PROFILE="$HOME/Library/Application Support/Google/Chrome/Default"
-DEBUG_PROFILE="/tmp/chrome-cdp"
-
-echo "Setting up Chrome debug profile..."
-
-# Create debug profile directory
-mkdir -p "$DEBUG_PROFILE/Default"
-
-# Copy auth data from main profile (preserves your logins)
-cp "$MAIN_PROFILE/Cookies" "$DEBUG_PROFILE/Default/" 2>/dev/null
-cp "$MAIN_PROFILE/Login Data" "$DEBUG_PROFILE/Default/" 2>/dev/null
-cp "$MAIN_PROFILE/Login Data For Account" "$DEBUG_PROFILE/Default/" 2>/dev/null
-
-echo "Starting Chrome with remote debugging on port $PORT..."
-echo "Note: This uses a separate profile with your login cookies copied over."
-echo ""
-
-/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
-  --user-data-dir="$DEBUG_PROFILE" \
-  --remote-debugging-port=$PORT \
-  --disable-save-password-bubble \
-  --disable-popup-blocking \
-  --disable-notifications \
-  --disable-infobars \
-  --disable-translate \
-  --disable-features=PasswordManager,AutofillSaveCardBubble,TranslateUI \
-  --password-store=basic