surf-cli 2.3.0 → 2.4.0

package/README.md

@@ -1,6 +1,14 @@
+<p>
+  <img src="surf-banner.png" alt="surf" width="1100">
+</p>
+
 # Surf
 
-The CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.
+**The CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.**
+
+[![npm version](https://img.shields.io/npm/v/surf-cli?style=for-the-badge)](https://www.npmjs.com/package/surf-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux-blue?style=for-the-badge)]()
 
 ```bash
 surf go "https://example.com"
@@ -365,6 +373,55 @@ surf network.stats                    # Capture statistics
 Storage location: `/tmp/surf/` (override with `--network-path` or `SURF_NETWORK_PATH` env).
 Auto-cleanup: 24 hours TTL, 200MB max.
 
+### Workflows
+
+Execute multi-step browser automation as a single command:
+
+```bash
+# Inline workflow (newline-separated commands)
+surf do 'go "https://example.com/login"
+type "user@example.com" --selector "input[name=email]"
+type "password123" --selector "input[name=password]"
+click --selector "button[type=submit]"
+screenshot --output /tmp/after-login.png'
+
+# From JSON file (same format as --script)
+surf do --file login-workflow.json
+
+# Validate without executing
+surf do 'go "url"\nclick e5\nscreenshot' --dry-run
+```
+
+**Why workflows?** Instead of 6-8 separate CLI calls with LLM orchestration between each step, a workflow executes deterministically with smart auto-waits. Faster, cheaper, and more reliable.
+
+**Options:**
+- `--file`, `-f` - Load workflow from JSON file
+- `--dry-run` - Parse and validate without executing
+- `--on-error stop|continue` - Error handling (default: stop)
+- `--step-delay <ms>` - Delay between steps (default: 100, use 0 to disable)
+- `--no-auto-wait` - Disable automatic waits between steps
+- `--json` - Output structured JSON result
+
+**Auto-waits:** Commands that trigger page changes automatically wait for completion:
+- Navigation (`go`, `back`, `forward`) → waits for page load
+- Clicks, key presses, form fills → waits for DOM stability
+- Tab switches → waits for tab to load
+
+**JSON file format:**
+```json
+{
+  "name": "Login Flow",
+  "steps": [
+    { "tool": "navigate", "args": { "url": "https://example.com/login" } },
+    { "tool": "type", "args": { "text": "user@example.com", "selector": "input[name=email]" } },
+    { "tool": "click", "args": { "selector": "button[type=submit]" } },
+    { "tool": "screenshot", "args": {} }
+  ]
+}
+```
+
+**Supported commands:** All surf commands work in workflows. Use aliases (`go`, `snap`, `read`) or full names (`navigate`, `screenshot`, `page.read`).
+
 ## Global Options
 
 ```bash
@@ -385,10 +442,50 @@ For programmatic integration, send JSON to `/tmp/surf.sock`:
 echo '{"type":"tool_request","method":"execute_tool","params":{"tool":"tab.list","args":{}},"id":"1"}' | nc -U /tmp/surf.sock
 ```
 
+### Protocol Reference
+
+**Request:**
+```json
+{
+  "type": "tool_request",
+  "method": "execute_tool",
+  "params": {
+    "tool": "click",
+    "args": { "ref": "e5" }
+  },
+  "id": "unique-request-id",
+  "tabId": 123,
+  "windowId": 456
+}
+```
+
+**Success Response:**
+```json
+{
+  "type": "tool_response",
+  "id": "unique-request-id",
+  "result": {
+    "content": [{ "type": "text", "text": "Result message" }]
+  }
+}
+```
+
+**Error Response:**
+```json
+{
+  "type": "tool_response",
+  "id": "unique-request-id",
+  "error": {
+    "content": [{ "type": "text", "text": "Error message" }]
+  }
+}
+```
+
 ## Command Groups
 
 | Group | Commands |
 |-------|----------|
+| `workflow` | `do` |
 | `window.*` | `new`, `list`, `focus`, `close`, `resize` |
 | `tab.*` | `list`, `new`, `switch`, `close`, `name`, `unname`, `named`, `group`, `ungroup`, `groups`, `reload` |
 | `scroll.*` | `top`, `bottom`, `to`, `info` |
@@ -449,6 +546,20 @@ surf install <extension-id> --browser chromium
 - Screenshot resize uses ImageMagick instead of macOS `sips`
 - Headless servers need Xvfb + VNC for initial login setup
 
+## AI Agent Integration
+
+Surf includes a skill file for AI coding agents like [Pi](https://github.com/badlogic/pi-mono):
+
+```bash
+# Symlink for auto-updates
+ln -s "$(pwd)/skills/surf" ~/.pi/agent/skills/surf
+
+# Or copy
+cp -r skills/surf ~/.pi/agent/skills/
+```
+
+See [`skills/README.md`](skills/README.md) for details.
+
 ## Development
 
 ```bash

package/native/cli.cjs

@@ -5,6 +5,8 @@ const { execSync } = require("child_process");
 const { loadConfig, getConfigPath, createStarterConfig } = require("./config.cjs");
 const networkFormatters = require("./formatters/network.cjs");
 const networkStore = require("./network-store.cjs");
+const { parseDoCommands } = require("./do-parser.cjs");
+const { executeDoSteps } = require("./do-executor.cjs");
 
 const SOCKET_PATH = "/tmp/surf.sock";
 
@@ -801,6 +803,27 @@ const TOOLS = {
       },
     }
   },
+  workflow: {
+    desc: "Workflow execution",
+    commands: {
+      "do": {
+        desc: "Execute multiple commands as a single workflow",
+        args: ["commands"],
+        opts: {
+          file: "Load workflow from JSON file",
+          "on-error": "stop (default) | continue",
+          "no-auto-wait": "Disable automatic waits between steps",
+          "step-delay": "Delay between steps in ms (default: 100)",
+          "dry-run": "Parse and validate without executing"
+        },
+        examples: [
+          { cmd: 'do \'go "https://example.com"\\nclick e5\\nscreenshot\'', desc: "Inline workflow" },
+          { cmd: 'do -f login.json', desc: "From JSON file" },
+          { cmd: 'do \'go "url"\\nclick e5\' --dry-run', desc: "Validate without running" },
+        ]
+      },
+    }
+  },
   zoom: {
     desc: "Zoom control",
     commands: {
@@ -1725,7 +1748,139 @@ if (args.includes("--script")) {
   return;
 }
 
-const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save"];
+// Handle `surf do` workflow command
+// Must be parsed before general parseArgs since it uses its own arg handling
+if (args[0] === "do") {
+  const doArgs = args.slice(1);
+  let commandsInput = null;
+  let fileInput = null;
+  let dryRun = false;
+  let onError = "stop";
+  let noAutoWait = false;
+  let stepDelay = 100;
+  let wantJson = false;
+  let tabId = undefined;
+  let windowId = undefined;
+  
+  // Parse do-specific arguments
+  for (let i = 0; i < doArgs.length; i++) {
+    const arg = doArgs[i];
+    if (arg === "--file" || arg === "-f") {
+      fileInput = doArgs[i + 1];
+      i++;
+    } else if (arg === "--dry-run") {
+      dryRun = true;
+    } else if (arg === "--on-error") {
+      onError = doArgs[i + 1] || "stop";
+      i++;
+    } else if (arg === "--no-auto-wait") {
+      noAutoWait = true;
+    } else if (arg === "--step-delay") {
+      const parsed = parseInt(doArgs[i + 1], 10);
+      stepDelay = isNaN(parsed) ? 100 : parsed;
+      i++;
+    } else if (arg === "--json") {
+      wantJson = true;
+    } else if (arg === "--tab-id") {
+      tabId = parseInt(doArgs[i + 1], 10);
+      i++;
+    } else if (arg === "--window-id") {
+      windowId = parseInt(doArgs[i + 1], 10);
+      i++;
+    } else if (!arg.startsWith("-")) {
+      commandsInput = arg;
+    }
+  }
+  
+  if (!commandsInput && !fileInput) {
+    console.error("Error: commands string or --file required");
+    console.error('Usage: surf do \'go "url"\\nclick e5\'');
+    console.error("       surf do --file workflow.json");
+    process.exit(1);
+  }
+  
+  let steps;
+  try {
+    if (fileInput) {
+      if (!fs.existsSync(fileInput)) {
+        console.error(`Error: File not found: ${fileInput}`);
+        process.exit(1);
+      }
+      const content = fs.readFileSync(fileInput, "utf8");
+      // JSON file format (same as --script)
+      const script = JSON.parse(content);
+      if (!script.steps || !Array.isArray(script.steps)) {
+        throw new Error("JSON must have a 'steps' array");
+      }
+      // Convert --script format { tool, args } to do format { cmd, args }
+      steps = script.steps.map(s => ({ cmd: s.tool, args: s.args || {} }));
+    } else {
+      // Inline string parsing
+      steps = parseDoCommands(commandsInput);
+    }
+  } catch (e) {
+    console.error(`Error: Failed to parse workflow: ${e.message}`);
+    process.exit(1);
+  }
+  
+  if (steps.length === 0) {
+    console.error("Error: No commands found in workflow");
+    process.exit(1);
+  }
+  
+  // Validate with --dry-run
+  if (dryRun) {
+    console.log(`Would execute ${steps.length} steps:`);
+    steps.forEach((s, i) => {
+      const argStr = Object.entries(s.args || {})
+        .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+        .join(" ");
+      console.log(`  ${i + 1}. ${s.cmd} ${argStr}`);
+    });
+    process.exit(0);
+  }
+  
+  if (!wantJson) {
+    console.log(`Running workflow (${steps.length} steps)...\n`);
+  }
+  
+  const runWorkflow = async () => {
+    const result = await executeDoSteps(steps, {
+      onError,
+      autoWait: !noAutoWait,
+      stepDelay,
+      quiet: wantJson,
+      context: {
+        tabId,
+        windowId,
+      },
+    });
+    
+    // Print summary
+    if (wantJson) {
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.status === "completed" ? 0 : 1);
+    }
+    
+    console.log("");
+    if (result.status === "completed") {
+      console.log(`Completed: ${result.completedSteps}/${result.totalSteps} steps (${result.totalMs}ms)`);
+      process.exit(0);
+    } else if (result.status === "partial") {
+      console.log(`Partial: ${result.completedSteps}/${result.totalSteps} steps completed, ${result.failed} failed`);
+      process.exit(1);
+    } else {
+      console.error(`Failed: ${result.completedSteps}/${result.totalSteps} steps completed`);
+      if (result.error) console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+  };
+  
+  runWorkflow();
+  return;
+}
+
+const BOOLEAN_FLAGS = ["auto-capture", "json", "stream", "dry-run", "stop-on-error", "fail-fast", "clear", "submit", "all", "case-sensitive", "hard", "annotate", "fullpage", "reset", "no-screenshot", "full", "soft-fail", "has-body", "exclude-static", "v", "vv", "request", "by-tab", "har", "jsonl", "no-save", "no-auto-wait"];
 
 const AUTO_SCREENSHOT_TOOLS = ["click", "type", "key", "smart_type", "form.fill", "form_input", "drag", "hover", "scroll", "scroll.top", "scroll.bottom", "scroll.to", "dialog.accept", "dialog.dismiss", "js", "eval"];
 
@@ -1755,8 +1910,12 @@ const parseArgs = (rawArgs) => {
       result.options.v = true;
     } else if (arg === "-vv") {
       result.options.vv = true;
+    } else if (arg === "-f" && rawArgs[i + 1] && !rawArgs[i + 1].startsWith("-")) {
+      // -f takes a file path argument (for surf do -f <file>)
+      result.options.file = rawArgs[i + 1];
+      i++;
     } else if (arg.startsWith("-") && arg.length === 2) {
-      // Short flag like -n, -f
+      // Short flag like -n
       result.options[arg.slice(1)] = true;
     } else {
       result.positional.push(arg);

package/native/do-executor.cjs

@@ -0,0 +1,273 @@
+/**
+ * Executor for surf `do` workflow commands
+ * 
+ * Executes steps sequentially with auto-waits and streaming progress output.
+ * Follows the same socket communication pattern as --script mode in cli.cjs.
+ */
+
+const net = require("net");
+
+const SOCKET_PATH = "/tmp/surf.sock";
+
+// Commands that trigger auto-wait after execution
+// Note: 'type' is intentionally excluded - typing doesn't trigger navigation or DOM changes
+const AUTO_WAIT_COMMANDS = [
+  'go', 'navigate', 'click', 'key', 'form.fill', 'submit',
+  'tab.switch', 'tab.new', 'back', 'forward'
+];
+
+// Auto-wait strategies per command type
+const AUTO_WAIT_MAP = {
+  'navigate': 'wait.load',
+  'go': 'wait.load',
+  'click': 'wait.dom',
+  'key': 'wait.dom',
+  'form.fill': 'wait.dom',
+  'submit': 'wait.load',  // Form submission typically triggers navigation
+  'tab.switch': 'wait.load',
+  'tab.new': 'wait.load',
+  'back': 'wait.load',
+  'forward': 'wait.load',
+};
+
+/**
+ * Check if a command should trigger an auto-wait
+ * @param {string} cmd - Command name
+ * @returns {boolean}
+ */
+function shouldAutoWait(cmd) {
+  return AUTO_WAIT_COMMANDS.some(c => cmd === c || cmd.startsWith(c + '.'));
+}
+
+/**
+ * Get the appropriate auto-wait command for a given command
+ * @param {string} cmd - Command name
+ * @returns {string|null} - Wait command to execute, or null
+ */
+function getAutoWaitCommand(cmd) {
+  // Check exact match first
+  if (AUTO_WAIT_MAP[cmd] !== undefined) return AUTO_WAIT_MAP[cmd];
+  
+  // Check prefix match
+  for (const [prefix, waitCmd] of Object.entries(AUTO_WAIT_MAP)) {
+    if (cmd.startsWith(prefix + '.')) return waitCmd;
+  }
+  
+  return null;
+}
+
+/**
+ * Send a single tool request over socket
+ * @param {string} toolName - Tool/command name
+ * @param {object} toolArgs - Tool arguments
+ * @param {object} context - Execution context (tabId, windowId)
+ * @returns {Promise<object>} - Response from host
+ */
+function sendDoRequest(toolName, toolArgs, context = {}) {
+  return new Promise((resolve, reject) => {
+    const sock = net.createConnection(SOCKET_PATH, () => {
+      const req = {
+        type: "tool_request",
+        method: "execute_tool",
+        params: { tool: toolName, args: toolArgs },
+        id: "do-" + Date.now() + "-" + Math.random(),
+      };
+      if (context.tabId) req.tabId = context.tabId;
+      if (context.windowId) req.windowId = context.windowId;
+      sock.write(JSON.stringify(req) + "\n");
+    });
+    
+    let buf = "";
+    sock.on("data", (d) => {
+      buf += d.toString();
+      const lines = buf.split("\n");
+      buf = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          const resp = JSON.parse(line);
+          sock.end();
+          resolve(resp);
+        } catch {
+          sock.end();
+          reject(new Error("Invalid JSON response"));
+        }
+      }
+    });
+    
+    sock.on("error", (e) => {
+      if (e.code === "ENOENT") {
+        reject(new Error("Socket not found. Is Chrome running with the extension?"));
+      } else if (e.code === "ECONNREFUSED") {
+        reject(new Error("Connection refused. Native host not running."));
+      } else {
+        reject(e);
+      }
+    });
+    
+    const timeoutId = setTimeout(() => { 
+      sock.destroy(); 
+      reject(new Error("Request timeout")); 
+    }, 30000);
+    
+    sock.on("close", () => clearTimeout(timeoutId));
+  });
+}
+
+/**
+ * Substitute variables in arguments using %{varname} syntax
+ * @param {object} args - Arguments object
+ * @param {object} vars - Variables map
+ * @returns {object} - Arguments with variables substituted
+ */
+function substituteVars(args, vars) {
+  if (!args || typeof args !== 'object') return args;
+  
+  const result = {};
+  for (const [key, val] of Object.entries(args)) {
+    if (typeof val === 'string') {
+      result[key] = val.replace(/%\{(\w+)\}/g, (_, name) => vars[name] ?? `%{${name}}`);
+    } else {
+      result[key] = val;
+    }
+  }
+  return result;
+}
+
+/**
+ * Execute all workflow steps sequentially
+ * @param {Array<{ cmd: string, args: object }>} steps - Steps to execute
+ * @param {object} options - Execution options
+ * @returns {Promise<object>} - Execution result
+ */
+async function executeDoSteps(steps, options = {}) {
+  const {
+    onError = 'stop',
+    autoWait = true,
+    stepDelay = 100,
+    context = {},
+    quiet = false,  // For --json mode, suppress streaming output
+  } = options;
+  
+  const results = [];
+  const vars = context.vars || {};
+  const total = steps.length;
+  let failed = 0;
+  const startTotal = Date.now();
+  
+  for (let i = 0; i < total; i++) {
+    const step = steps[i];
+    const startTime = Date.now();
+    const stepNum = `[${i + 1}/${total}]`;
+    
+    // Build description (matches --script output format)
+    const argSummary = Object.entries(step.args || {})
+      .map(([k, v]) => typeof v === "string" && v.length > 40 
+        ? `${k}="${v.slice(0, 37)}..."` 
+        : `${k}=${JSON.stringify(v)}`)
+      .join(" ");
+    const desc = argSummary ? `${step.cmd} ${argSummary}` : step.cmd;
+    
+    // Print step prefix (streaming output)
+    if (!quiet) {
+      process.stdout.write(`${stepNum} ${desc} ... `);
+    }
+    
+    try {
+      // Substitute variables in args
+      const resolvedArgs = substituteVars(step.args, vars);
+      
+      const resp = await sendDoRequest(step.cmd, resolvedArgs, context);
+      const ms = Date.now() - startTime;
+      
+      if (resp.error) {
+        const errText = resp.error.content?.[0]?.text || JSON.stringify(resp.error);
+        
+        if (!quiet) {
+          console.log(`FAIL`);
+          console.log(`     Error: ${errText}`);
+        }
+        
+        results.push({ step: i + 1, cmd: step.cmd, status: 'error', error: errText, ms });
+        failed++;
+        
+        if (onError === 'stop') {
+          return { 
+            status: 'failed', 
+            completedSteps: i, 
+            totalSteps: total, 
+            results, 
+            error: errText,
+            totalMs: Date.now() - startTotal
+          };
+        }
+      } else {
+        if (!quiet) {
+          console.log(`OK (${ms}ms)`);
+        }
+        
+        results.push({ step: i + 1, cmd: step.cmd, status: 'ok', ms });
+        
+        // Command-specific auto-wait
+        if (autoWait) {
+          const waitCmd = getAutoWaitCommand(step.cmd);
+          if (waitCmd) {
+            const waitArgs = waitCmd === 'wait.load' 
+              ? { timeout: 10000 } 
+              : { stable: 100, timeout: 5000 };
+            try {
+              await sendDoRequest(waitCmd, waitArgs, context);
+            } catch {
+              // Ignore auto-wait failures silently
+            }
+          }
+        }
+      }
+      
+      // Fixed delay between steps
+      if (stepDelay > 0 && i < total - 1) {
+        await new Promise(r => setTimeout(r, stepDelay));
+      }
+    } catch (err) {
+      const ms = Date.now() - startTime;
+      
+      if (!quiet) {
+        console.log(`FAIL`);
+        console.log(`     Error: ${err.message}`);
+      }
+      
+      results.push({ step: i + 1, cmd: step.cmd, status: 'error', error: err.message, ms });
+      failed++;
+      
+      if (onError === 'stop') {
+        return { 
+          status: 'failed', 
+          completedSteps: i, 
+          totalSteps: total, 
+          results, 
+          error: err.message,
+          totalMs: Date.now() - startTotal
+        };
+      }
+    }
+  }
+  
+  return { 
+    status: failed > 0 ? 'partial' : 'completed', 
+    completedSteps: total - failed, 
+    totalSteps: total, 
+    results,
+    failed,
+    totalMs: Date.now() - startTotal
+  };
+}
+
+module.exports = { 
+  executeDoSteps, 
+  sendDoRequest, 
+  shouldAutoWait,
+  getAutoWaitCommand,
+  substituteVars,
+  AUTO_WAIT_COMMANDS,
+  AUTO_WAIT_MAP
+};

package/native/do-parser.cjs

@@ -0,0 +1,232 @@
+/**
+ * Parser for surf `do` workflow commands
+ * 
+ * Parses newline-separated commands into structured step arrays:
+ * 
+ * Input:
+ *   'go "https://example.com"
+ *    click e5
+ *    screenshot'
+ * 
+ * Output:
+ *   [
+ *     { cmd: 'navigate', args: { url: 'https://example.com' } },
+ *     { cmd: 'click', args: { ref: 'e5' } },
+ *     { cmd: 'screenshot', args: {} }
+ *   ]
+ */
+
+// Aliases mapping (matches cli.cjs)
+const ALIASES = {
+  snap: "screenshot",
+  read: "page.read",
+  find: "search",
+  go: "navigate",
+  net: "network",
+  "network.dump": "network.get",
+};
+
+// Primary argument mapping for positional args (matches cli.cjs)
+const PRIMARY_ARG_MAP = {
+  ai: "query",
+  gemini: "query",
+  chatgpt: "query",
+  perplexity: "query",
+  grok: "query",
+  navigate: "url",
+  go: "url",
+  js: "code",
+  javascript_tool: "code",
+  key: "key",
+  wait: "duration",
+  health: "url",
+  new_tab: "url",
+  "tab.new": "url",
+  switch_tab: "tab_id",
+  "tab.switch": "id",
+  close_tab: "tab_id",
+  "tab.close": "id",
+  "tab.name": "name",
+  "tab.unname": "name",
+  scroll_to_position: "position",
+  type: "text",
+  smart_type: "text",
+  "emulate.network": "preset",
+  "emulate.cpu": "rate",
+  search: "term",
+  find: "term",
+  "wait.element": "selector",
+  "wait.url": "pattern",
+  zoom: "level",
+  "history.search": "query",
+  "network.get": "id",
+  "network.body": "id",
+  "network.curl": "id",
+  "network.path": "id",
+  "window.new": "url",
+  "window.focus": "id",
+  "window.close": "id",
+  "locate.role": "role",
+  "locate.text": "text",
+  "locate.label": "label",
+  "emulate.device": "device",
+  "frame.js": "code",
+  "element.styles": "selector",
+  "select": "selector",
+};
+
+/**
+ * Tokenize a command line, respecting single and double quotes
+ * @param {string} line - Single line to tokenize
+ * @returns {string[]} - Array of tokens
+ */
+function tokenize(line) {
+  const tokens = [];
+  let current = '';
+  let inQuote = null;
+  
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    
+    if (inQuote) {
+      if (ch === inQuote) {
+        // End of quoted string
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      // Start of quoted string
+      inQuote = ch;
+    } else if (ch === ' ' || ch === '\t') {
+      // Whitespace separator
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+  
+  // Don't forget last token
+  if (current) {
+    tokens.push(current);
+  }
+  
+  return tokens;
+}
+
+/**
+ * Parse a single command line into a step object
+ * @param {string} line - Single command line
+ * @returns {{ cmd: string, args: object } | null}
+ */
+function parseCommandLine(line) {
+  const tokens = tokenize(line);
+  if (tokens.length === 0) return null;
+  
+  // Get command and apply alias
+  let cmd = tokens[0];
+  cmd = ALIASES[cmd] || cmd;
+  
+  const args = {};
+  let i = 1;
+  
+  // Handle first positional argument based on command type
+  if (i < tokens.length && !tokens[i].startsWith('--')) {
+    const firstArg = tokens[i];
+    
+    // Special handling for click command
+    if (cmd === 'click') {
+      if (/^e\d+$/.test(firstArg)) {
+        // Element reference: e5 -> ref
+        args.ref = firstArg;
+        i++;
+      } else if (/^\d+$/.test(firstArg) && tokens[i + 1] && /^\d+$/.test(tokens[i + 1])) {
+        // Coordinates: 100 200 -> x, y
+        args.x = parseInt(firstArg, 10);
+        args.y = parseInt(tokens[i + 1], 10);
+        i += 2;
+      }
+    } else if (cmd === 'select') {
+      // Select takes selector + one or more values: select e5 "US" or select e5 "opt1" "opt2"
+      args.selector = firstArg;
+      i++;
+      // Collect remaining positional args as values
+      const values = [];
+      while (i < tokens.length && !tokens[i].startsWith('--')) {
+        values.push(tokens[i]);
+        i++;
+      }
+      // Host expects 'values' (always), matching CLI behavior
+      if (values.length === 1) {
+        args.values = values[0];  // Single value as string (host will wrap in array)
+      } else if (values.length > 1) {
+        args.values = values;     // Multiple values as array
+      }
+    } else {
+      // Use PRIMARY_ARG_MAP for other commands
+      const primaryKey = PRIMARY_ARG_MAP[cmd];
+      if (primaryKey) {
+        args[primaryKey] = firstArg;
+        i++;
+      }
+    }
+  }
+  
+  // Parse --flag value pairs
+  while (i < tokens.length) {
+    const token = tokens[i];
+    if (token.startsWith('--')) {
+      const key = token.slice(2);
+      const next = tokens[i + 1];
+      if (next && !next.startsWith('--')) {
+        // Flag with value
+        let val = next;
+        // Type coercion
+        if (val === "true") val = true;
+        else if (val === "false") val = false;
+        else if (/^-?\d+$/.test(val)) val = parseInt(val, 10);
+        else if (/^-?\d+\.\d+$/.test(val)) val = parseFloat(val);
+        args[key] = val;
+        i += 2;
+      } else {
+        // Boolean flag
+        args[key] = true;
+        i++;
+      }
+    } else {
+      // Skip unrecognized positional (shouldn't happen normally)
+      i++;
+    }
+  }
+  
+  return { cmd, args };
+}
+
+/**
+ * Parse a multi-line workflow string into step array
+ * @param {string} input - Multi-line workflow string
+ * @returns {Array<{ cmd: string, args: object }>}
+ */
+function parseDoCommands(input) {
+  // Replace literal \n (backslash + n) with actual newlines
+  // This handles bash single-quoted strings like 'go "url"\nclick e5'
+  const normalized = input.replace(/\\n/g, '\n');
+  
+  return normalized
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+    .map(line => parseCommandLine(line))
+    .filter(step => step !== null);
+}
+
+module.exports = { 
+  parseDoCommands, 
+  parseCommandLine, 
+  tokenize,
+  ALIASES,
+  PRIMARY_ARG_MAP
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "surf-cli",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "CLI for AI agents to control Chrome. Zero config, agent-agnostic, battle-tested.",
   "keywords": [
     "chrome",

package/native/CHANGELOG.md

@@ -1,136 +0,0 @@
-# Changelog
-
-All notable changes to surf CLI will be documented in this file.
-
-## [2.2.0] - 2026-01-07
-
-### Added
-- Network capture: `network`, `network.stats`, `network.origins`, `network.get`, `network.clear`, `network.export`
-- Filtering by method, status, URL, content-type
-- Export formats: curl, raw JSON, URL list
-- Persistence to `/tmp/surf/` (configurable via `SURF_NETWORK_PATH`)
-
-## [2.1.0] - 2025-12-30
-
-### Added
-
-**ChatGPT Integration**
-- `chatgpt <query>` - Send prompt to ChatGPT using browser cookies (no API key)
-  - `--with-page` - Include current page context
-  - `--model` - Specify model (gpt-4o, o1, etc.)
-  - `--timeout` - Custom timeout (default: 45 minutes)
-  - File attachments coming soon
-
-**Gemini Integration (Coming Soon)**
-- `gemini <query>` - Command structure ready, implementation pending
-
-**Request Queue**
-- AI requests are queued sequentially with 2s minimum delay between requests
-- Prevents rate limiting when making multiple AI queries
-
-### Technical Changes
-- New `chatgpt-client.cjs` module for ChatGPT browser automation
-- Extension: `GET_CHATGPT_COOKIES`, `GET_GOOGLE_COOKIES` handlers
-- Extension: `CHATGPT_NEW_TAB`, `CHATGPT_CLOSE_TAB`, `CHATGPT_CDP_COMMAND`, `CHATGPT_EVALUATE` handlers
-- CDP controller: Added public `sendCommand()` method
-
-## [2.0.0] - 2025-12-27
-
-### Breaking Changes
-- Removed snake_case command aliases (use dot-notation instead)
-  - `read_page` -> `page.read`
-  - `list_tabs` -> `tab.list`
-  - `wait_for_element` -> `wait.element`
-  - `javascript_tool` -> `js`
-  - And others (see REMOVED_COMMANDS in cli.cjs for full list)
-- Removed all single-letter short flags for consistency
-  - Use `--output` instead of `-o`
-  - Use `--ref` instead of `-r`
-  - Use `--annotate` instead of `-a`
-  - Use `--fullpage` instead of `-f`
-- Migration hints shown when using old command names
-
-### Added
-
-**Navigation**
-- `back` - Go back in browser history
-- `forward` - Go forward in browser history
-- `tab.reload` - Reload tab (with `--hard` for cache bypass)
-
-**Tab Groups**
-- `tab.group` - Create or add to tab group
-- `tab.ungroup` - Remove tabs from group
-- `tab.groups` - List all tab groups
-
-**Zoom Control**
-- `zoom` - Get current zoom level
-- `zoom <level>` - Set zoom (e.g., `zoom 1.5` for 150%)
-- `zoom --reset` - Reset to default zoom
-
-**Cookies**
-- `cookie.list` - List cookies for current domain
-- `cookie.get` - Get specific cookie by name
-- `cookie.set` - Set a cookie
-- `cookie.clear` - Clear specific cookie or all (`--all`)
-
-**Search**
-- `search <term>` - Search for text in page (alias: `find`)
-- Returns match refs, context, and element associations
-
-**Batch Execution**
-- `batch --actions '[...]'` - Execute multiple actions
-- `batch --file workflow.json` - Load actions from file
-
-**Bookmarks**
-- `bookmark.add` - Bookmark current page
-- `bookmark.remove` - Remove bookmark for current page
-- `bookmark.list` - List bookmarks
-
-**History**
-- `history.list` - Recent browser history
-- `history.search <query>` - Search history
-
-**Screenshot Enhancements**
-- `--annotate` - Draw element labels on screenshot
-- `--fullpage` - Capture entire scrollable page
-- `--max-height` - Limit fullpage capture height (default: 4000px)
-- Extension UI automatically hidden during capture
-
-**Aliases**
-- `snap` -> `screenshot` (auto-saves to /tmp if no output specified)
-- `read` -> `page.read`
-- `find` -> `search`
-- `go` -> `navigate`
-
-**Discovery Features**
-- `--find <query>` - Fuzzy search for commands
-- `--about <topic>` - Learn about a topic
-
-**Help System**
-- `--help` - Basic help with common commands
-- `--help-full` - Complete command reference
-- `--help-topic <topic>` - Topic-specific guide
-- Command-level help with examples
-
-**Other**
-- `--version` - Show version
-- `click 100 200` - Positional coordinates for click
-- `click --selector ".btn" --index 2` - Click nth element matching selector
-
-### Changed
-- Primary argument support for commands:
-  - `wait.element <selector>` (was `--selector`)
-  - `wait.url <pattern>` (was `--pattern`)
-  - `click <ref>` with e-prefix detection (e.g., `click e5`)
-- Help output includes usage examples for all commands
-- `dialog.dismiss --all` for repeatedly dismissing dialogs
-- Fullpage screenshot delay increased to 300ms for lazy-loaded content
-- Error messages standardized to terse format for AI consumption
-
-### Fixed
-- `--limit 0` now correctly returns empty results (was defaulting to max)
-- Screenshot always hides extension UI (was conditional on `--clean` flag)
-
-## [1.x] - Previous Releases
-
-See git history for changes before v2.0.0.

package/native/README.md

@@ -1,141 +0,0 @@
-# Surf Native Host
-
-Native messaging host that bridges CLI commands to the Chrome extension via Unix socket.
-
-## Architecture
-
-```
-CLI (surf) → Unix Socket (/tmp/surf.sock) → Native Host → Chrome Extension → CDP
-```
-
-## Files
-
-| File | Purpose |
-|------|---------|
-| `host.cjs` | Main native host with socket server and tool handling |
-| `cli.cjs` | CLI tool for browser automation |
-| `chatgpt-client.cjs` | ChatGPT browser automation client |
-| `protocol.cjs` | Chrome native messaging protocol helpers |
-| `host-wrapper.py` | Python wrapper for native host execution |
-| `host.sh` | Shell script to start the host |
-
-## Setup
-
-1. Install the native host manifest:
-```bash
-npm run install:native <extension-id>
-```
-
-Or manually:
-```bash
-mkdir -p ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts
-cat > ~/Library/Application\ Support/Google/Chrome/NativeMessagingHosts/com.anthropic.pi_chrome.json << EOF
-{
-  "name": "com.anthropic.pi_chrome",
-  "description": "Surf CLI Native Host",
-  "path": "$PWD/host-wrapper.py",
-  "type": "stdio",
-  "allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID/"]
-}
-EOF
-```
-
-2. Start the native host:
-```bash
-node host.cjs
-```
-
-The host creates a Unix socket at `/tmp/surf.sock`.
-
-## CLI Reference
-
-See the main [README](../README.md) for full CLI documentation.
-
-### Quick Reference
-
-```bash
-surf go "https://example.com"       # Navigate
-surf read                           # Get accessibility tree
-surf click e5                       # Click element
-surf type "hello" --submit          # Type and submit
-surf snap                           # Screenshot to /tmp
-surf chatgpt "explain this"         # Query ChatGPT
-```
-
-### Global Options
-
-```bash
---tab-id <id>     # Target specific tab
---json            # Output raw JSON
---soft-fail       # Warn instead of error on restricted pages
---no-screenshot   # Skip auto-screenshot after actions
---full            # Full resolution screenshots
-```
-
-## Protocol
-
-### Tool Request
-
-```json
-{
-  "type": "tool_request",
-  "method": "execute_tool",
-  "params": {
-    "tool": "TOOL_NAME",
-    "args": { ... },
-    "tabId": 123
-  },
-  "id": "unique-request-id"
-}
-```
-
-### Tool Response (Success)
-
-```json
-{
-  "type": "tool_response",
-  "id": "unique-request-id",
-  "result": {
-    "content": [
-      { "type": "text", "text": "Result message" }
-    ]
-  }
-}
-```
-
-### Tool Response (With Image)
-
-```json
-{
-  "type": "tool_response",
-  "id": "unique-request-id",
-  "result": {
-    "content": [
-      { "type": "text", "text": "Screenshot captured" },
-      { "type": "image", "data": "base64...", "mimeType": "image/png" }
-    ]
-  }
-}
-```
-
-### Tool Response (Error)
-
-```json
-{
-  "type": "tool_response",
-  "id": "unique-request-id",
-  "error": {
-    "content": [{ "type": "text", "text": "Error message" }]
-  }
-}
-```
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| Socket not found | Ensure `node host.cjs` is running |
-| No response | Check extension is loaded in Chrome |
-| "Content script not loaded" | Navigate to a page first |
-| "Cannot control this page" | Page is restricted (chrome://, extensions) - use `--soft-fail` |
-| Slow first operation | Normal - CDP debugger attachment takes ~100-500ms |