surf-cli 2.0.0

package/native/tests/cli-tests.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+cd "$(dirname "$0")/.."
+
+PASS=0
+FAIL=0
+
+test_output() {
+  local name="$1"
+  local cmd="$2"
+  local expect="$3"
+  
+  output=$(eval "$cmd" 2>&1) || true
+  if echo "$output" | grep -q "$expect"; then
+    echo "PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name"
+    echo "  Command: $cmd"
+    echo "  Expected: $expect"
+    echo "  Got: $output"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+test_exit_code() {
+  local name="$1"
+  local cmd="$2"
+  local expect_code="$3"
+  
+  eval "$cmd" > /dev/null 2>&1
+  actual_code=$?
+  if [ "$actual_code" -eq "$expect_code" ]; then
+    echo "PASS: $name"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name"
+    echo "  Command: $cmd"
+    echo "  Expected exit code: $expect_code"
+    echo "  Got: $actual_code"
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+echo "=== CLI Unit Tests (no extension required) ==="
+echo ""
+
+echo "-- Version and Help --"
+test_output "version flag" "node cli.cjs --version" "surf version"
+test_output "version short" "node cli.cjs -v" "surf version"
+test_output "basic help" "node cli.cjs --help" "Common Commands"
+test_output "full help" "node cli.cjs --help-full" "Aliases:"
+test_output "help topic refs" "node cli.cjs --help-topic refs" "Element References"
+test_output "help topic selectors" "node cli.cjs --help-topic selectors" "CSS Selectors"
+test_output "help topic cookies" "node cli.cjs --help-topic cookies" "Cookie Management"
+
+echo ""
+echo "-- Migration Hints --"
+test_output "removed read_page" "node cli.cjs read_page" "Use: page.read"
+test_output "removed list_tabs" "node cli.cjs list_tabs" "Use: tab.list"
+test_output "removed wait_for_element" "node cli.cjs wait_for_element" "Use: wait.element"
+test_output "removed javascript_tool" "node cli.cjs javascript_tool" "Use: js"
+
+echo ""
+echo "-- Aliases --"
+test_output "snap help" "node cli.cjs snap --help" "snap -> screenshot"
+test_output "read help" "node cli.cjs read --help" "accessibility tree"
+test_output "find help" "node cli.cjs find --help" "search"
+test_output "go help" "node cli.cjs go --help" "URL"
+
+echo ""
+echo "-- Find Command --"
+test_output "find screenshot" "node cli.cjs --find screenshot" "screenshot"
+test_output "find cookie" "node cli.cjs --find cookie" "cookie"
+test_output "find wait" "node cli.cjs --find wait" "wait"
+
+echo ""
+echo "-- About Command --"
+test_output "about refs" "node cli.cjs --about refs" "Element References"
+test_output "about cookies" "node cli.cjs --about cookies" "Cookie Management"
+test_output "about tab" "node cli.cjs --about tab" "Tab management"
+
+echo ""
+echo "-- Group Help --"
+test_output "tab group help" "node cli.cjs tab" "tab.list"
+test_output "cookie group help" "node cli.cjs cookie" "cookie.list"
+test_output "scroll group help" "node cli.cjs scroll" "scroll.top"
+
+echo ""
+echo "-- Command Help with Examples --"
+test_output "click help examples" "node cli.cjs click --help" "Examples"
+test_output "type help examples" "node cli.cjs type --help" "Examples"
+test_output "screenshot help examples" "node cli.cjs screenshot --help" "Examples"
+
+echo ""
+echo "-- New Commands in Help --"
+test_output "back in help" "node cli.cjs --help-full" "back"
+test_output "forward in help" "node cli.cjs --help-full" "forward"
+test_output "zoom in help" "node cli.cjs --help-full" "zoom"
+test_output "bookmark in help" "node cli.cjs --help-full" "bookmark"
+test_output "history in help" "node cli.cjs --help-full" "history"
+
+echo ""
+echo "-- List Command --"
+test_output "list shows new commands" "node cli.cjs --list" "back"
+test_output "list shows zoom" "node cli.cjs --list" "zoom"
+
+echo ""
+echo "==================================="
+echo "Results: $PASS passed, $FAIL failed"
+echo "==================================="
+
+if [ "$FAIL" -gt 0 ]; then
+  exit 1
+fi
+exit 0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "surf-cli",
+  "version": "2.0.0",
+  "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
+  "keywords": [
+    "chrome",
+    "browser",
+    "automation",
+    "ai",
+    "agent",
+    "cli",
+    "cdp",
+    "devtools"
+  ],
+  "author": "Nico Bailon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicobailon/surf-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nicobailon/surf-cli/issues"
+  },
+  "homepage": "https://github.com/nicobailon/surf-cli#readme",
+  "type": "module",
+  "bin": {
+    "surf": "native/cli.cjs"
+  },
+  "files": [
+    "native/",
+    "scripts/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "vite build --watch --mode development",
+    "build": "vite build",
+    "check": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "lint:test": "biome check test/",
+    "format": "biome format --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "install:native": "node scripts/install-native-host.cjs",
+    "uninstall:native": "node scripts/uninstall-native-host.cjs"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.21.0",
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "buffer": "^6.0.3",
+    "crypto-browserify": "^3.12.1",
+    "events": "^3.3.0",
+    "stream-browserify": "^3.0.0",
+    "vite-plugin-node-polyfills": "^0.24.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/chrome": "^0.0.287",
+    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/ui": "^4.0.16",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.0",
+    "vitest": "^4.0.16"
+  }
+}

package/scripts/install-native-host.cjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync, spawnSync } = require("child_process");
+
+const HOST_NAME = "surf.browser.host";
+
+const BROWSERS = {
+  chrome: {
+    name: "Google Chrome",
+    darwin: "Library/Application Support/Google/Chrome/NativeMessagingHosts",
+    linux: ".config/google-chrome/NativeMessagingHosts",
+    win32: "Google\\Chrome",
+  },
+  chromium: {
+    name: "Chromium",
+    darwin: "Library/Application Support/Chromium/NativeMessagingHosts",
+    linux: ".config/chromium/NativeMessagingHosts",
+    win32: "Chromium",
+  },
+  brave: {
+    name: "Brave",
+    darwin:
+      "Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts",
+    linux: ".config/BraveSoftware/Brave-Browser/NativeMessagingHosts",
+    win32: "BraveSoftware\\Brave-Browser",
+  },
+  edge: {
+    name: "Microsoft Edge",
+    darwin: "Library/Application Support/Microsoft Edge/NativeMessagingHosts",
+    linux: ".config/microsoft-edge/NativeMessagingHosts",
+    win32: "Microsoft\\Edge",
+  },
+  arc: {
+    name: "Arc",
+    darwin:
+      "Library/Application Support/Arc/User Data/NativeMessagingHosts",
+    linux: null,
+    win32: null,
+  },
+};
+
+const NODE_PATHS = {
+  darwin: [
+    "/opt/homebrew/bin/node",
+    "/usr/local/bin/node",
+    "/usr/bin/node",
+  ],
+  linux: [
+    "/usr/bin/node",
+    "/usr/local/bin/node",
+  ],
+  win32: [
+    "C:\\Program Files\\nodejs\\node.exe",
+    "C:\\Program Files (x86)\\nodejs\\node.exe",
+  ],
+};
+
+function findNode() {
+  const platform = process.platform;
+  const paths = NODE_PATHS[platform] || [];
+  for (const p of paths) {
+    if (fs.existsSync(p)) return p;
+  }
+  try {
+    const which = platform === "win32" ? "where" : "which";
+    const result = execSync(`${which} node`, { encoding: "utf8" }).trim();
+    if (result) return result.split("\n")[0];
+  } catch {}
+  return null;
+}
+
+function findNpmGlobalRoot() {
+  try {
+    return execSync("npm root -g", { encoding: "utf8" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function getWrapperDir() {
+  const platform = process.platform;
+  const home = os.homedir();
+  switch (platform) {
+    case "darwin":
+      return path.join(home, "Library/Application Support/surf-cli");
+    case "linux":
+      return path.join(home, ".local/share/surf-cli");
+    case "win32":
+      return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData/Local"), "surf-cli");
+    default:
+      return null;
+  }
+}
+
+function getHostPath() {
+  const npmRoot = findNpmGlobalRoot();
+  if (npmRoot) {
+    const globalPath = path.join(npmRoot, "surf-cli/native/host.cjs");
+    if (fs.existsSync(globalPath)) return globalPath;
+  }
+  const localPath = path.resolve(__dirname, "../native/host.cjs");
+  if (fs.existsSync(localPath)) return localPath;
+  return null;
+}
+
+function createWrapper(wrapperDir, nodePath, hostPath) {
+  const platform = process.platform;
+  fs.mkdirSync(wrapperDir, { recursive: true });
+
+  if (platform === "win32") {
+    const batPath = path.join(wrapperDir, "host-wrapper.bat");
+    const content = `@echo off\r\n"${nodePath}" "${hostPath}"\r\n`;
+    fs.writeFileSync(batPath, content);
+    return batPath;
+  } else {
+    const shPath = path.join(wrapperDir, "host-wrapper.sh");
+    const hostDir = path.dirname(hostPath);
+    const content = `#!/bin/bash
+cd "${hostDir}"
+exec "${nodePath}" "${hostPath}"
+`;
+    fs.writeFileSync(shPath, content);
+    fs.chmodSync(shPath, "755");
+    return shPath;
+  }
+}
+
+function installManifest(browser, extensionId, wrapperPath) {
+  const platform = process.platform;
+  const browserConfig = BROWSERS[browser];
+
+  if (!browserConfig || !browserConfig[platform]) {
+    return null;
+  }
+
+  if (platform === "win32") {
+    return installWindowsRegistry(browser, extensionId, wrapperPath);
+  }
+
+  const manifestDir = path.join(os.homedir(), browserConfig[platform]);
+  fs.mkdirSync(manifestDir, { recursive: true });
+
+  const manifest = {
+    name: HOST_NAME,
+    description: "Surf CLI Native Host",
+    path: wrapperPath,
+    type: "stdio",
+    allowed_origins: [`chrome-extension://${extensionId}/`],
+  };
+
+  const manifestPath = path.join(manifestDir, `${HOST_NAME}.json`);
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+  return manifestPath;
+}
+
+function installWindowsRegistry(browser, extensionId, wrapperPath) {
+  const browserConfig = BROWSERS[browser];
+  const regPath = `HKCU\\Software\\${browserConfig.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
+
+  const manifestDir = getWrapperDir();
+  const manifestPath = path.join(manifestDir, `${HOST_NAME}.json`);
+
+  const manifest = {
+    name: HOST_NAME,
+    description: "Surf CLI Native Host",
+    path: wrapperPath,
+    type: "stdio",
+    allowed_origins: [`chrome-extension://${extensionId}/`],
+  };
+
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  try {
+    execSync(`reg add "${regPath}" /ve /t REG_SZ /d "${manifestPath}" /f`, {
+      stdio: "pipe",
+    });
+    return manifestPath;
+  } catch (e) {
+    console.error(`Failed to add registry entry: ${e.message}`);
+    return null;
+  }
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = { extensionId: null, browsers: ["chrome"] };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--browser" || arg === "-b") {
+      const browserArg = args[++i];
+      if (browserArg === "all") {
+        result.browsers = Object.keys(BROWSERS);
+      } else {
+        result.browsers = browserArg.split(",").map((b) => b.trim().toLowerCase());
+      }
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    } else if (!arg.startsWith("-")) {
+      result.extensionId = arg;
+    }
+  }
+  return result;
+}
+
+function printHelp() {
+  console.log(`
+Surf CLI Native Host Installer
+
+Usage: install-native-host.cjs <extension-id> [options]
+
+Arguments:
+  extension-id    Chrome extension ID (32 lowercase letters a-p)
+                  Find at chrome://extensions with Developer Mode enabled
+
+Options:
+  -b, --browser   Browser(s) to install for (default: chrome)
+                  Values: chrome, chromium, brave, edge, arc, all
+                  Multiple: --browser chrome,brave
+
+Examples:
+  node install-native-host.cjs abcdefghijklmnopabcdefghijklmnop
+  node install-native-host.cjs abcdefghijklmnop --browser brave
+  node install-native-host.cjs abcdefghijklmnop --browser all
+`);
+}
+
+function main() {
+  const { extensionId, browsers } = parseArgs();
+
+  if (!extensionId) {
+    console.error("Error: Extension ID required");
+    console.error("Usage: install-native-host.cjs <extension-id> [--browser chrome|brave|edge|all]");
+    console.error("\nFind your extension ID at chrome://extensions (enable Developer Mode)");
+    process.exit(1);
+  }
+
+  if (!/^[a-p]{32}$/.test(extensionId)) {
+    console.error("Error: Invalid extension ID format");
+    console.error("Expected 32 lowercase letters (a-p)");
+    process.exit(1);
+  }
+
+  const nodePath = findNode();
+  if (!nodePath) {
+    console.error("Error: Could not find Node.js");
+    console.error("Make sure Node.js is installed and in your PATH");
+    process.exit(1);
+  }
+
+  const hostPath = getHostPath();
+  if (!hostPath) {
+    console.error("Error: Could not find host.cjs");
+    console.error("Make sure surf-cli is installed correctly");
+    process.exit(1);
+  }
+
+  const wrapperDir = getWrapperDir();
+  if (!wrapperDir) {
+    console.error("Error: Unsupported platform");
+    process.exit(1);
+  }
+
+  console.log(`Platform: ${process.platform}`);
+  console.log(`Node: ${nodePath}`);
+  console.log(`Host: ${hostPath}`);
+  console.log(`Wrapper dir: ${wrapperDir}`);
+  console.log("");
+
+  const wrapperPath = createWrapper(wrapperDir, nodePath, hostPath);
+  console.log(`Created wrapper: ${wrapperPath}`);
+  console.log("");
+
+  const installed = [];
+  const skipped = [];
+
+  for (const browser of browsers) {
+    if (!BROWSERS[browser]) {
+      console.error(`Unknown browser: ${browser}`);
+      continue;
+    }
+
+    const result = installManifest(browser, extensionId, wrapperPath);
+    if (result) {
+      installed.push({ browser: BROWSERS[browser].name, path: result });
+    } else {
+      skipped.push(BROWSERS[browser].name);
+    }
+  }
+
+  if (installed.length > 0) {
+    console.log("Installed for:");
+    for (const { browser, path: p } of installed) {
+      console.log(`  ${browser}: ${p}`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    console.log(`\nSkipped (not supported on ${process.platform}): ${skipped.join(", ")}`);
+  }
+
+  console.log("\nDone! Restart your browser for changes to take effect.");
+}
+
+main();

package/scripts/uninstall-native-host.cjs

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execSync } = require("child_process");
+
+const HOST_NAME = "surf.browser.host";
+
+const BROWSERS = {
+  chrome: {
+    name: "Google Chrome",
+    darwin: "Library/Application Support/Google/Chrome/NativeMessagingHosts",
+    linux: ".config/google-chrome/NativeMessagingHosts",
+    win32: "Google\\Chrome",
+  },
+  chromium: {
+    name: "Chromium",
+    darwin: "Library/Application Support/Chromium/NativeMessagingHosts",
+    linux: ".config/chromium/NativeMessagingHosts",
+    win32: "Chromium",
+  },
+  brave: {
+    name: "Brave",
+    darwin: "Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts",
+    linux: ".config/BraveSoftware/Brave-Browser/NativeMessagingHosts",
+    win32: "BraveSoftware\\Brave-Browser",
+  },
+  edge: {
+    name: "Microsoft Edge",
+    darwin: "Library/Application Support/Microsoft Edge/NativeMessagingHosts",
+    linux: ".config/microsoft-edge/NativeMessagingHosts",
+    win32: "Microsoft\\Edge",
+  },
+  arc: {
+    name: "Arc",
+    darwin: "Library/Application Support/Arc/User Data/NativeMessagingHosts",
+    linux: null,
+    win32: null,
+  },
+};
+
+function getWrapperDir() {
+  const platform = process.platform;
+  const home = os.homedir();
+  switch (platform) {
+    case "darwin":
+      return path.join(home, "Library/Application Support/surf-cli");
+    case "linux":
+      return path.join(home, ".local/share/surf-cli");
+    case "win32":
+      return path.join(process.env.LOCALAPPDATA || path.join(home, "AppData/Local"), "surf-cli");
+    default:
+      return null;
+  }
+}
+
+function removeManifest(browser) {
+  const platform = process.platform;
+  const browserConfig = BROWSERS[browser];
+
+  if (!browserConfig || !browserConfig[platform]) {
+    return null;
+  }
+
+  if (platform === "win32") {
+    return removeWindowsRegistry(browser);
+  }
+
+  const manifestPath = path.join(
+    os.homedir(),
+    browserConfig[platform],
+    `${HOST_NAME}.json`
+  );
+
+  try {
+    fs.unlinkSync(manifestPath);
+    return manifestPath;
+  } catch {
+    return null;
+  }
+}
+
+function removeWindowsRegistry(browser) {
+  const browserConfig = BROWSERS[browser];
+  const regPath = `HKCU\\Software\\${browserConfig.win32}\\NativeMessagingHosts\\${HOST_NAME}`;
+
+  try {
+    execSync(`reg delete "${regPath}" /f`, { stdio: "pipe" });
+    return regPath;
+  } catch {
+    return null;
+  }
+}
+
+function removeWrapperDir() {
+  const wrapperDir = getWrapperDir();
+  if (!wrapperDir) return null;
+
+  try {
+    fs.rmSync(wrapperDir, { recursive: true, force: true });
+    return wrapperDir;
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = { browsers: ["chrome"], all: false };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--browser" || arg === "-b") {
+      const browserArg = args[++i];
+      if (browserArg === "all") {
+        result.browsers = Object.keys(BROWSERS);
+        result.all = true;
+      } else {
+        result.browsers = browserArg.split(",").map((b) => b.trim().toLowerCase());
+      }
+    } else if (arg === "--all" || arg === "-a") {
+      result.browsers = Object.keys(BROWSERS);
+      result.all = true;
+    } else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+  return result;
+}
+
+function printHelp() {
+  console.log(`
+Surf CLI Native Host Uninstaller
+
+Usage: uninstall-native-host.cjs [options]
+
+Options:
+  -b, --browser   Browser(s) to uninstall from (default: chrome)
+                  Values: chrome, chromium, brave, edge, arc, all
+  -a, --all       Uninstall from all browsers and remove wrapper
+
+Examples:
+  node uninstall-native-host.cjs
+  node uninstall-native-host.cjs --browser brave
+  node uninstall-native-host.cjs --all
+`);
+}
+
+function main() {
+  const { browsers, all } = parseArgs();
+
+  console.log(`Platform: ${process.platform}`);
+  console.log("");
+
+  const removed = [];
+  const notFound = [];
+
+  for (const browser of browsers) {
+    if (!BROWSERS[browser]) {
+      console.error(`Unknown browser: ${browser}`);
+      continue;
+    }
+
+    const result = removeManifest(browser);
+    if (result) {
+      removed.push({ browser: BROWSERS[browser].name, path: result });
+    } else {
+      notFound.push(BROWSERS[browser].name);
+    }
+  }
+
+  if (removed.length > 0) {
+    console.log("Removed manifests:");
+    for (const { browser, path: p } of removed) {
+      console.log(`  ${browser}: ${p}`);
+    }
+  }
+
+  if (notFound.length > 0) {
+    console.log(`\nNot found: ${notFound.join(", ")}`);
+  }
+
+  if (all) {
+    const wrapperDir = removeWrapperDir();
+    if (wrapperDir) {
+      console.log(`\nRemoved wrapper directory: ${wrapperDir}`);
+    }
+  }
+
+  console.log("\nDone!");
+}
+
+main();