surf-cli 2.4.2 → 2.5.0

package/README.md

@@ -387,6 +387,9 @@ surf do 'go "https://example.com/login" | type "user@example.com" --selector "#e
 # From JSON file
 surf do --file workflow.json
 
+# Run named workflow with arguments
+surf do my-workflow --url "https://example.com" --max_items 10
+
 # Validate without executing
 surf do 'go "url" | click e5 | screenshot' --dry-run
 ```
@@ -400,25 +403,100 @@ surf do 'go "url" | click e5 | screenshot' --dry-run
 - `--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
+- `--<arg> <value>` - Pass arguments to workflow (e.g., `--url "..."`)
 
 **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:**
+#### Workflow Files
+
+Workflows can be saved as JSON files and run by name. Place them in `~/.surf/workflows/` (user) or `./.surf/workflows/` (project).
+
+**Basic format:**
 ```json
 {
-  "name": "Login Flow",
+  "name": "login-flow",
+  "description": "Log into example.com",
+  "args": {
+    "email": { "required": true, "desc": "Login email" },
+    "password": { "required": true, "desc": "Login password" }
+  },
   "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": {} }
+    { "tool": "type", "args": { "text": "%{email}", "selector": "input[name=email]" } },
+    { "tool": "type", "args": { "text": "%{password}", "selector": "input[name=password]" } },
+    { "tool": "click", "args": { "selector": "button[type=submit]" } }
+  ]
+}
+```
+
+**Step outputs** - Capture results for use in later steps:
+```json
+{
+  "steps": [
+    { "tool": "js", "args": { "code": "return document.title" }, "as": "title" },
+    { "tool": "js", "args": { "code": "return 'Page: ' + '%{title}'" } }
+  ]
+}
+```
+
+**Loops** - `repeat` for fixed iterations, `each` for arrays:
+```json
+{
+  "steps": [
+    { "tool": "js", "args": { "code": "return ['a', 'b', 'c']" }, "as": "items" },
+    {
+      "each": "%{items}",
+      "as": "item",
+      "steps": [
+        { "tool": "js", "args": { "code": "return 'Processing: %{item}'" } }
+      ]
+    }
+  ]
+}
+```
+
+```json
+{
+  "steps": [
+    {
+      "repeat": 5,
+      "steps": [
+        { "tool": "scroll", "args": { "direction": "down" } },
+        { "tool": "wait", "args": { "duration": 500 } }
+      ]
+    }
   ]
 }
 ```
 
+**Loop with exit condition** - Stop early when condition is met:
+```json
+{
+  "repeat": 20,
+  "until": { "tool": "js", "args": { "code": "return !document.querySelector('.next-page')" } },
+  "steps": [
+    { "tool": "click", "args": { "selector": ".next-page" } },
+    { "tool": "wait.load" }
+  ]
+}
+```
+
+#### Workflow Management
+
+```bash
+# List available workflows
+surf workflow.list
+
+# Show workflow details and arguments
+surf workflow.info my-workflow
+
+# Validate workflow JSON
+surf workflow.validate ./my-workflow.json
+```
+
 **Supported commands:** All surf commands work in workflows. Use aliases (`go`, `snap`, `read`) or full names (`navigate`, `screenshot`, `page.read`).
 
 ## Global Options
@@ -484,7 +562,7 @@ echo '{"type":"tool_request","method":"execute_tool","params":{"tool":"tab.list"
 
 | Group | Commands |
 |-------|----------|
-| `workflow` | `do` |
+| `workflow` | `do`, `workflow.list`, `workflow.info`, `workflow.validate` |
 | `window.*` | `new`, `list`, `focus`, `close`, `resize` |
 | `tab.*` | `list`, `new`, `switch`, `close`, `name`, `unname`, `named`, `group`, `ungroup`, `groups`, `reload` |
 | `scroll.*` | `top`, `bottom`, `to`, `info` |

package/native/cli.cjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 const net = require("net");
 const fs = require("fs");
+const path = require("path");
+const os = require("os");
 const { execSync } = require("child_process");
 const { loadConfig, getConfigPath, createStarterConfig } = require("./config.cjs");
 const networkFormatters = require("./formatters/network.cjs");
@@ -10,6 +12,249 @@ const { executeDoSteps } = require("./do-executor.cjs");
 
 const SOCKET_PATH = "/tmp/surf.sock";
 
+// ============================================================================
+// Workflow Resolution and Management
+// ============================================================================
+
+/**
+ * Get workflow search directories
+ * @returns {Array<{path: string, scope: string}>}
+ */
+function getWorkflowDirs() {
+  return [
+    { path: path.join(process.cwd(), '.surf', 'workflows'), scope: 'project' },
+    { path: path.join(os.homedir(), '.surf', 'workflows'), scope: 'user' },
+  ];
+}
+
+/**
+ * Resolve a workflow by name or path
+ * @param {string} nameOrPath - Workflow name or file path
+ * @returns {{ type: 'inline'|'file'|'not_found', content?: string, path?: string, name?: string }}
+ */
+function resolveWorkflow(nameOrPath) {
+  // Check if it's an inline workflow (contains pipe)
+  if (nameOrPath.includes('|')) {
+    return { type: 'inline', content: nameOrPath };
+  }
+  
+  // Check if it's a direct file path (with extension or path separator)
+  if (nameOrPath.includes('/') || nameOrPath.includes('\\') || nameOrPath.endsWith('.json')) {
+    if (fs.existsSync(nameOrPath)) {
+      return { type: 'file', path: nameOrPath };
+    }
+    return { type: 'not_found', name: nameOrPath };
+  }
+  
+  // Look up by name in workflow directories
+  const searchDirs = getWorkflowDirs();
+  
+  for (const { path: dir } of searchDirs) {
+    const filePath = path.join(dir, `${nameOrPath}.json`);
+    if (fs.existsSync(filePath)) {
+      return { type: 'file', path: filePath };
+    }
+  }
+  
+  return { type: 'not_found', name: nameOrPath };
+}
+
+/**
+ * List all available workflows
+ * @returns {Array<{name: string, description: string, scope: string, path: string, args?: object}>}
+ */
+function listWorkflows() {
+  const workflows = [];
+  const searchDirs = getWorkflowDirs();
+  
+  for (const { path: dir, scope } of searchDirs) {
+    if (fs.existsSync(dir)) {
+      try {
+        const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+          const filePath = path.join(dir, file);
+          try {
+            const content = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+            workflows.push({
+              name: content.name || file.replace('.json', ''),
+              description: content.description || '',
+              scope,
+              path: filePath,
+              args: content.args,
+              stepCount: content.steps?.length || 0,
+            });
+          } catch {
+            // Skip invalid JSON files
+          }
+        }
+      } catch {
+        // Skip inaccessible directories
+      }
+    }
+  }
+  
+  return workflows;
+}
+
+/**
+ * Get detailed info about a workflow
+ * @param {string} name - Workflow name
+ * @returns {{ error?: string, name?: string, description?: string, args?: object, steps?: Array, path?: string }}
+ */
+function getWorkflowInfo(name) {
+  const resolved = resolveWorkflow(name);
+  
+  if (resolved.type === 'not_found') {
+    return { error: `Workflow not found: ${name}` };
+  }
+  
+  if (resolved.type === 'inline') {
+    return { error: 'Cannot get info for inline workflows' };
+  }
+  
+  try {
+    const content = JSON.parse(fs.readFileSync(resolved.path, 'utf8'));
+    return {
+      name: content.name || name,
+      description: content.description || '',
+      args: content.args || {},
+      steps: content.steps || [],
+      path: resolved.path,
+    };
+  } catch (e) {
+    return { error: `Failed to parse workflow: ${e.message}` };
+  }
+}
+
+/**
+ * Validate workflow args against schema
+ * @param {object} workflow - Workflow with args schema
+ * @param {object} providedArgs - User-provided args
+ * @returns {string[]} - Array of error messages
+ */
+function validateWorkflowArgs(workflow, providedArgs) {
+  const errors = [];
+  if (workflow.args) {
+    for (const [name, spec] of Object.entries(workflow.args)) {
+      if (spec.required && providedArgs[name] === undefined) {
+        errors.push(`Missing required argument: --${name}`);
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Apply default values to workflow args
+ * @param {object} workflow - Workflow with args schema
+ * @param {object} providedArgs - User-provided args
+ * @returns {object} - Args with defaults applied
+ */
+function applyArgDefaults(workflow, providedArgs) {
+  const vars = { ...providedArgs };
+  if (workflow.args) {
+    for (const [name, spec] of Object.entries(workflow.args)) {
+      if (vars[name] === undefined && spec.default !== undefined) {
+        vars[name] = spec.default;
+      }
+    }
+  }
+  return vars;
+}
+
+/**
+ * Validate a workflow JSON file
+ * @param {string} filePath - Path to workflow file
+ * @returns {{ valid: boolean, error?: string, workflow?: object }}
+ */
+function validateWorkflowFile(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { valid: false, error: `File not found: ${filePath}` };
+  }
+  
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const workflow = JSON.parse(content);
+    
+    // Basic structure validation
+    if (!workflow.steps || !Array.isArray(workflow.steps)) {
+      return { valid: false, error: "Workflow must have a 'steps' array" };
+    }
+    
+    if (workflow.steps.length === 0) {
+      return { valid: false, error: "Workflow has no steps" };
+    }
+    
+    // Validate each step
+    for (let i = 0; i < workflow.steps.length; i++) {
+      const step = workflow.steps[i];
+      
+      // Check for loops
+      if (step.repeat !== undefined || step.each !== undefined) {
+        if (!step.steps || !Array.isArray(step.steps)) {
+          return { valid: false, error: `Step ${i + 1}: loop must have a 'steps' array` };
+        }
+        continue;
+      }
+      
+      // Regular step must have tool/cmd
+      if (!step.tool && !step.cmd) {
+        return { valid: false, error: `Step ${i + 1}: must have 'tool' field` };
+      }
+    }
+    
+    // Validate args schema if present
+    if (workflow.args && typeof workflow.args !== 'object') {
+      return { valid: false, error: "'args' must be an object" };
+    }
+    
+    return { valid: true, workflow };
+  } catch (e) {
+    return { valid: false, error: `Invalid JSON: ${e.message}` };
+  }
+}
+
+/**
+ * Format a step for display
+ * @param {object} step - Workflow step
+ * @param {number} indent - Indentation level
+ * @returns {string}
+ */
+function formatStep(step, indent = 0) {
+  const pad = '  '.repeat(indent);
+  
+  if (step.repeat !== undefined) {
+    const lines = [`${pad}repeat ${step.repeat} times:`];
+    for (const s of step.steps || []) {
+      lines.push(formatStep(s, indent + 1));
+    }
+    if (step.until) {
+      lines.push(`${pad}  until: ${step.until.tool || step.until.cmd}`);
+    }
+    return lines.join('\n');
+  }
+  
+  if (step.each !== undefined) {
+    const lines = [`${pad}each ${step.each} as ${step.as || 'item'}:`];
+    for (const s of step.steps || []) {
+      lines.push(formatStep(s, indent + 1));
+    }
+    return lines.join('\n');
+  }
+  
+  const tool = step.tool || step.cmd;
+  const args = step.args || {};
+  const argStr = Object.entries(args)
+    .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+    .join(' ');
+  
+  let line = `${pad}${tool}`;
+  if (argStr) line += ` ${argStr}`;
+  if (step.as) line += ` → ${step.as}`;
+  
+  return line;
+}
+
 // Cross-platform image resize (macOS: sips, Linux: ImageMagick)
 function resizeImage(filePath, maxSize) {
   const platform = process.platform;
@@ -804,7 +1049,7 @@ const TOOLS = {
     }
   },
   workflow: {
-    desc: "Workflow execution",
+    desc: "Workflow execution and management",
     commands: {
       "do": {
         desc: "Execute multiple commands as a single workflow",
@@ -819,9 +1064,34 @@ const TOOLS = {
         examples: [
           { cmd: 'do \'go "https://example.com" | click e5 | screenshot\'', desc: "Inline workflow" },
           { cmd: 'do -f login.json', desc: "From JSON file" },
+          { cmd: 'do github-login --email "x" --password "y"', desc: "Named workflow with args" },
           { cmd: 'do \'go "url" | click e5\' --dry-run', desc: "Validate without running" },
         ]
       },
+      "workflow.list": {
+        desc: "List available workflows",
+        args: [],
+        opts: {},
+        examples: [
+          { cmd: 'workflow.list', desc: "Show all workflows" },
+        ]
+      },
+      "workflow.info": {
+        desc: "Show workflow details and arguments",
+        args: ["name"],
+        opts: {},
+        examples: [
+          { cmd: 'workflow.info github-login', desc: "Show workflow details" },
+        ]
+      },
+      "workflow.validate": {
+        desc: "Validate workflow JSON file",
+        args: ["file"],
+        opts: {},
+        examples: [
+          { cmd: 'workflow.validate ./my-flow.json', desc: "Check JSON validity" },
+        ]
+      },
     }
   },
   zoom: {
@@ -1762,6 +2032,12 @@ if (args[0] === "do") {
   let tabId = undefined;
   let windowId = undefined;
   
+  // Reserved flags that aren't workflow args
+  const reservedFlags = ['file', 'f', 'dry-run', 'on-error', 'no-auto-wait', 'step-delay', 'json', 'tab-id', 'window-id'];
+  
+  // Workflow-specific args (collected for variable substitution)
+  const workflowArgs = {};
+  
   // Parse do-specific arguments
   for (let i = 0; i < doArgs.length; i++) {
     const arg = doArgs[i];
@@ -1787,61 +2063,165 @@ if (args[0] === "do") {
     } else if (arg === "--window-id") {
       windowId = parseInt(doArgs[i + 1], 10);
       i++;
+    } else if (arg.startsWith("--")) {
+      // Workflow-specific arg (e.g., --email, --password)
+      const key = arg.slice(2);
+      if (!reservedFlags.includes(key)) {
+        const next = doArgs[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+          // Type coercion
+          let val = next;
+          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);
+          workflowArgs[key] = val;
+          i++;
+        } else {
+          workflowArgs[key] = true;
+        }
+      }
     } 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("Error: commands string, workflow name, or --file required");
+    console.error('Usage: surf do \'go "url" | click e5\'');
     console.error("       surf do --file workflow.json");
+    console.error("       surf do my-workflow --arg1 value1 --arg2 value2");
     process.exit(1);
   }
   
   let steps;
+  let workflow = null; // Full workflow object (for arg validation)
+  let workflowName = null;
+  
   try {
     if (fileInput) {
+      // Explicit file path via --file
       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 || {} }));
+      workflow = JSON.parse(content);
+      workflowName = workflow.name || fileInput;
     } else {
-      // Inline string parsing
-      steps = parseDoCommands(commandsInput);
+      // Resolve: inline | file path | named workflow
+      const resolved = resolveWorkflow(commandsInput);
+      
+      if (resolved.type === 'inline') {
+        // Inline pipe syntax
+        steps = parseDoCommands(resolved.content);
+      } else if (resolved.type === 'file') {
+        // Found workflow file
+        const content = fs.readFileSync(resolved.path, "utf8");
+        workflow = JSON.parse(content);
+        workflowName = workflow.name || commandsInput;
+      } else {
+        // Not found - try parsing as inline (might be a single command)
+        steps = parseDoCommands(commandsInput);
+        if (steps.length === 0) {
+          console.error(`Error: Workflow not found: ${commandsInput}`);
+          console.error(`Searched in:`);
+          for (const { path: dir } of getWorkflowDirs()) {
+            console.error(`  ${dir}`);
+          }
+          console.error(`\nRun 'surf workflow.list' to see available workflows.`);
+          process.exit(1);
+        }
+      }
+    }
+    
+    // Process workflow file if loaded
+    if (workflow) {
+      if (!workflow.steps || !Array.isArray(workflow.steps)) {
+        throw new Error("Workflow must have a 'steps' array");
+      }
+      
+      // Validate required args
+      const argErrors = validateWorkflowArgs(workflow, workflowArgs);
+      if (argErrors.length > 0) {
+        console.error("Error: Missing required arguments:");
+        argErrors.forEach(e => console.error(`  ${e}`));
+        if (workflow.args) {
+          console.error(`\nWorkflow arguments:`);
+          for (const [name, spec] of Object.entries(workflow.args)) {
+            const req = spec.required ? ' (required)' : '';
+            const def = spec.default !== undefined ? ` [default: ${spec.default}]` : '';
+            const desc = spec.desc || spec.description || '';
+            console.error(`  --${name}${req}${def}${desc ? ` - ${desc}` : ''}`);
+          }
+        }
+        console.error(`\nRun 'surf workflow.info ${workflowName}' for details.`);
+        process.exit(1);
+      }
+      
+      // Convert steps: support both { tool, args } and { cmd, args } formats
+      // Also preserve loop steps as-is
+      steps = workflow.steps.map(s => {
+        if (s.repeat !== undefined || s.each !== undefined) {
+          // Loop step - convert nested steps recursively
+          const convertSteps = (stepsArr) => stepsArr.map(ns => {
+            if (ns.repeat !== undefined || ns.each !== undefined) {
+              // Recursively convert nested loop steps and until condition
+              return { 
+                ...ns, 
+                steps: convertSteps(ns.steps || []),
+                until: ns.until ? { cmd: ns.until.tool || ns.until.cmd, args: ns.until.args || {} } : undefined
+              };
+            }
+            return { cmd: ns.tool || ns.cmd, args: ns.args || {}, as: ns.as };
+          });
+          return { 
+            ...s, 
+            steps: convertSteps(s.steps || []),
+            until: s.until ? { cmd: s.until.tool || s.until.cmd, args: s.until.args || {} } : undefined
+          };
+        }
+        return { cmd: s.tool || s.cmd, args: s.args || {}, as: s.as };
+      });
     }
   } catch (e) {
     console.error(`Error: Failed to parse workflow: ${e.message}`);
     process.exit(1);
   }
   
-  if (steps.length === 0) {
+  if (!steps || steps.length === 0) {
     console.error("Error: No commands found in workflow");
     process.exit(1);
   }
   
+  // Apply arg defaults
+  const vars = workflow ? applyArgDefaults(workflow, workflowArgs) : workflowArgs;
+  
   // Validate with --dry-run
   if (dryRun) {
-    console.log(`Would execute ${steps.length} steps:`);
+    if (workflowName) {
+      console.log(`Workflow: ${workflowName}`);
+      if (workflow?.description) console.log(`Description: ${workflow.description}`);
+    }
+    console.log(`\nWould 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}`);
+      console.log(`  ${i + 1}. ${formatStep(s)}`);
     });
+    if (Object.keys(vars).length > 0) {
+      console.log(`\nVariables:`);
+      for (const [k, v] of Object.entries(vars)) {
+        console.log(`  ${k} = ${JSON.stringify(v)}`);
+      }
+    }
     process.exit(0);
   }
   
   if (!wantJson) {
-    console.log(`Running workflow (${steps.length} steps)...\n`);
+    if (workflowName) {
+      console.log(`Running workflow: ${workflowName} (${steps.length} steps)...\n`);
+    } else {
+      console.log(`Running workflow (${steps.length} steps)...\n`);
+    }
   }
   
   const runWorkflow = async () => {
@@ -1850,6 +2230,7 @@ if (args[0] === "do") {
       autoWait: !noAutoWait,
       stepDelay,
       quiet: wantJson,
+      vars,
       context: {
         tabId,
         windowId,
@@ -1880,6 +2261,127 @@ if (args[0] === "do") {
   return;
 }
 
+// Handle workflow management commands
+if (args[0] === "workflow.list") {
+  const workflows = listWorkflows();
+  
+  if (workflows.length === 0) {
+    console.log("No workflows found.");
+    console.log(`\nWorkflow directories:`);
+    for (const { path: dir, scope } of getWorkflowDirs()) {
+      console.log(`  ${scope}: ${dir}`);
+    }
+    console.log(`\nCreate a workflow JSON file in one of these directories.`);
+    process.exit(0);
+  }
+  
+  // Group by scope
+  const byScope = { project: [], user: [] };
+  for (const w of workflows) {
+    byScope[w.scope].push(w);
+  }
+  
+  if (byScope.user.length > 0) {
+    console.log(`User Workflows (~/.surf/workflows/):`);
+    for (const w of byScope.user) {
+      const desc = w.description ? ` - ${w.description}` : '';
+      console.log(`  ${w.name.padEnd(20)} ${desc}`);
+    }
+    console.log("");
+  }
+  
+  if (byScope.project.length > 0) {
+    console.log(`Project Workflows (./.surf/workflows/):`);
+    for (const w of byScope.project) {
+      const desc = w.description ? ` - ${w.description}` : '';
+      console.log(`  ${w.name.padEnd(20)} ${desc}`);
+    }
+    console.log("");
+  }
+  
+  console.log(`Run 'surf workflow.info <name>' for details.`);
+  process.exit(0);
+}
+
+if (args[0] === "workflow.info") {
+  const name = args[1];
+  if (!name) {
+    console.error("Error: workflow name required");
+    console.error("Usage: surf workflow.info <name>");
+    process.exit(1);
+  }
+  
+  const info = getWorkflowInfo(name);
+  if (info.error) {
+    console.error(`Error: ${info.error}`);
+    process.exit(1);
+  }
+  
+  console.log(`${info.name}${info.description ? ` - ${info.description}` : ''}`);
+  console.log("");
+  
+  // Arguments
+  if (info.args && Object.keys(info.args).length > 0) {
+    console.log("Arguments:");
+    for (const [argName, spec] of Object.entries(info.args)) {
+      const req = spec.required ? ' (required)' : '';
+      const def = spec.default !== undefined ? ` [default: ${spec.default}]` : '';
+      const desc = spec.desc || spec.description || '';
+      console.log(`  --${argName}${req}${def}`);
+      if (desc) console.log(`      ${desc}`);
+    }
+    console.log("");
+  }
+  
+  // Steps
+  console.log(`Steps (${info.steps.length}):`);
+  info.steps.forEach((step, i) => {
+    console.log(`  ${i + 1}. ${formatStep(step)}`);
+  });
+  console.log("");
+  
+  // Location
+  console.log(`Location: ${info.path}`);
+  console.log("");
+  
+  // Example run command
+  const argExample = Object.entries(info.args || {})
+    .filter(([_, spec]) => spec.required)
+    .map(([name, _]) => `--${name} "..."`)
+    .join(' ');
+  console.log(`Run:`);
+  console.log(`  surf do ${name}${argExample ? ' ' + argExample : ''}`);
+  
+  process.exit(0);
+}
+
+if (args[0] === "workflow.validate") {
+  const filePath = args[1];
+  if (!filePath) {
+    console.error("Error: file path required");
+    console.error("Usage: surf workflow.validate <file>");
+    process.exit(1);
+  }
+  
+  const result = validateWorkflowFile(filePath);
+  
+  if (result.valid) {
+    console.log(`✓ Valid workflow: ${filePath}`);
+    console.log(`  Name: ${result.workflow.name || '(unnamed)'}`);
+    console.log(`  Steps: ${result.workflow.steps.length}`);
+    if (result.workflow.args) {
+      const argCount = Object.keys(result.workflow.args).length;
+      const reqCount = Object.values(result.workflow.args).filter(a => a.required).length;
+      console.log(`  Args: ${argCount} (${reqCount} required)`);
+    }
+    process.exit(0);
+  } else {
+    console.error(`✗ Invalid workflow: ${filePath}`);
+    console.error(`  Error: ${result.error}`);
+    process.exit(1);
+  }
+}
+
 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"];

package/native/do-executor.cjs

@@ -2,6 +2,11 @@
  * Executor for surf `do` workflow commands
  * 
  * Executes steps sequentially with auto-waits and streaming progress output.
+ * Supports:
+ *   - Step outputs: capture results with `as` field
+ *   - Loops: `repeat` for fixed iterations, `each` for array iteration
+ *   - Variable substitution: %{varname} syntax
+ * 
  * Follows the same socket communication pattern as --script mode in cli.cjs.
  */
 
@@ -9,6 +14,9 @@ const net = require("net");
 
 const SOCKET_PATH = "/tmp/surf.sock";
 
+// Maximum iterations for loops (safety cap)
+const MAX_LOOP_ITERATIONS = 100;
+
 // Commands that trigger auto-wait after execution
 // Note: 'type' is intentionally excluded - typing doesn't trigger navigation or DOM changes
 const AUTO_WAIT_COMMANDS = [
@@ -114,6 +122,32 @@ function sendDoRequest(toolName, toolArgs, context = {}) {
   });
 }
 
+/**
+ * Resolve a variable reference or perform string substitution
+ * @param {*} template - Value to resolve (may contain %{var} references)
+ * @param {object} vars - Variables map
+ * @returns {*} - Resolved value
+ */
+function resolveVar(template, vars) {
+  if (typeof template !== 'string') return template;
+  
+  // Check if it's a simple variable reference like %{urls}
+  const match = template.match(/^%\{(\w+)\}$/);
+  if (match) {
+    const value = vars[match[1]];
+    return value !== undefined ? value : template;
+  }
+  
+  // Otherwise do string substitution
+  return template.replace(/%\{(\w+)\}/g, (_, name) => {
+    const val = vars[name];
+    if (val === undefined) return `%{${name}}`;
+    // Convert objects/arrays to string for interpolation
+    if (typeof val === 'object') return JSON.stringify(val);
+    return String(val);
+  });
+}
+
 /**
  * Substitute variables in arguments using %{varname} syntax
  * @param {object} args - Arguments object
@@ -123,10 +157,28 @@ function sendDoRequest(toolName, toolArgs, context = {}) {
 function substituteVars(args, vars) {
   if (!args || typeof args !== 'object') return args;
   
+  // Handle arrays specially to preserve array type
+  if (Array.isArray(args)) {
+    return args.map(item => {
+      if (typeof item === 'string') {
+        return resolveVar(item, vars);
+      } else if (typeof item === 'object' && item !== null) {
+        return substituteVars(item, vars);
+      } else {
+        return item;
+      }
+    });
+  }
+  
+  // Handle plain objects
   const result = {};
   for (const [key, val] of Object.entries(args)) {
     if (typeof val === 'string') {
-      result[key] = val.replace(/%\{(\w+)\}/g, (_, name) => vars[name] ?? `%{${name}}`);
+      result[key] = resolveVar(val, vars);
+    } else if (Array.isArray(val)) {
+      result[key] = substituteVars(val, vars);
+    } else if (typeof val === 'object' && val !== null) {
+      result[key] = substituteVars(val, vars);
     } else {
       result[key] = val;
     }
@@ -134,9 +186,219 @@ function substituteVars(args, vars) {
   return result;
 }
 
+/**
+ * Extract usable output from a step response for the `as` capture
+ * @param {object} resp - Response from sendDoRequest
+ * @returns {*} - Extracted value
+ */
+function extractStepOutput(resp) {
+  // MCP format: resp.result.content[0].text
+  if (resp.result?.content?.[0]?.text) {
+    const text = resp.result.content[0].text;
+    // Try to parse as JSON, otherwise return raw text
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  
+  // Direct value (some tools return this)
+  if (resp.value !== undefined) return resp.value;
+  
+  // Direct result object
+  if (resp.result !== undefined) return resp.result;
+  
+  // Fallback to the whole response
+  return resp;
+}
+
+/**
+ * Execute a single tool step (non-loop)
+ * @param {object} step - Step to execute { cmd, args, as? }
+ * @param {object} vars - Variables map (mutated if step has `as`)
+ * @param {object} context - Execution context
+ * @param {object} options - Execution options
+ * @returns {Promise<object>} - Result { success, error?, output? }
+ */
+async function executeSingleStep(step, vars, context, options) {
+  const { autoWait = true, stepDelay = 100 } = options;
+  
+  // Substitute variables in args
+  const resolvedArgs = substituteVars(step.args || {}, vars);
+  
+  try {
+    const resp = await sendDoRequest(step.cmd, resolvedArgs, context);
+    
+    if (resp.error) {
+      const errText = resp.error.content?.[0]?.text || JSON.stringify(resp.error);
+      return { success: false, error: errText };
+    }
+    
+    // Capture output if step has `as` field
+    if (step.as) {
+      const output = extractStepOutput(resp);
+      vars[step.as] = output;
+    }
+    
+    // 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
+        }
+      }
+    }
+    
+    // Delay between steps
+    if (stepDelay > 0) {
+      await new Promise(r => setTimeout(r, stepDelay));
+    }
+    
+    return { success: true, output: step.as ? vars[step.as] : undefined };
+  } catch (err) {
+    return { success: false, error: err.message };
+  }
+}
+
+/**
+ * Execute a single step, handling loops recursively
+ * @param {object} step - Step to execute (may be a loop or regular step)
+ * @param {object} vars - Variables map
+ * @param {object} context - Execution context
+ * @param {object} options - Execution options
+ * @param {function} onProgress - Progress callback for streaming output
+ * @returns {Promise<object>} - Result { success, error?, stepsExecuted }
+ */
+async function executeStep(step, vars, context, options, onProgress) {
+  const { onError = 'stop' } = options;
+  
+  // Handle `repeat` loop
+  if (step.repeat !== undefined) {
+    // Resolve repeat count (may be a variable)
+    let max = resolveVar(step.repeat, vars);
+    if (typeof max === 'string') max = parseInt(max, 10);
+    if (typeof max !== 'number' || isNaN(max)) max = 1;
+    
+    // Safety cap
+    max = Math.min(max, MAX_LOOP_ITERATIONS);
+    
+    if (!Array.isArray(step.steps) || step.steps.length === 0) {
+      return { success: false, error: 'repeat: steps array required', stepsExecuted: 0 };
+    }
+    
+    let totalExecuted = 0;
+    
+    for (let i = 0; i < max; i++) {
+      // Create loop-scoped variables
+      const loopVars = { ...vars, _index: i, _iteration: i + 1 };
+      
+      // Execute nested steps
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, context, options, onProgress);
+        totalExecuted += result.stepsExecuted || 1;
+        
+        if (!result.success && onError === 'stop') {
+          return { success: false, error: result.error, stepsExecuted: totalExecuted };
+        }
+      }
+      
+      // Copy captured variables back to parent scope (only from regular steps, not loops)
+      for (const nestedStep of step.steps) {
+        // Skip loop steps - their 'as' is the loop variable, not an output capture
+        const isNestedLoop = nestedStep.repeat !== undefined || nestedStep.each !== undefined;
+        if (!isNestedLoop && nestedStep.as && loopVars[nestedStep.as] !== undefined) {
+          vars[nestedStep.as] = loopVars[nestedStep.as];
+        }
+      }
+      
+      // Check `until` condition
+      if (step.until) {
+        const untilResult = await executeSingleStep(step.until, loopVars, context, options);
+        totalExecuted++;
+        
+        // Exit loop if until condition is truthy
+        const exitValue = untilResult.output;
+        if (exitValue === true || exitValue === 'true' || exitValue) {
+          break;
+        }
+      }
+    }
+    
+    return { success: true, stepsExecuted: totalExecuted };
+  }
+  
+  // Handle `each` loop
+  if (step.each !== undefined) {
+    const items = resolveVar(step.each, vars);
+    
+    if (!Array.isArray(items)) {
+      return { 
+        success: false, 
+        error: `each: expected array, got ${typeof items}${items === undefined ? ' (undefined)' : ''}`, 
+        stepsExecuted: 0 
+      };
+    }
+    
+    if (!Array.isArray(step.steps) || step.steps.length === 0) {
+      return { success: false, error: 'each: steps array required', stepsExecuted: 0 };
+    }
+    
+    // Safety cap
+    const maxItems = Math.min(items.length, MAX_LOOP_ITERATIONS);
+    const itemVar = step.as || 'item';
+    let totalExecuted = 0;
+    
+    for (let i = 0; i < maxItems; i++) {
+      // Create loop-scoped variables
+      const loopVars = { ...vars, [itemVar]: items[i], _index: i, _iteration: i + 1 };
+      
+      // Execute nested steps
+      for (const nestedStep of step.steps) {
+        const result = await executeStep(nestedStep, loopVars, context, options, onProgress);
+        totalExecuted += result.stepsExecuted || 1;
+        
+        if (!result.success && onError === 'stop') {
+          return { success: false, error: result.error, stepsExecuted: totalExecuted };
+        }
+      }
+      
+      // Copy captured variables back to parent scope (only from regular steps, not loops)
+      for (const nestedStep of step.steps) {
+        // Skip loop steps - their 'as' is the loop variable, not an output capture
+        const isNestedLoop = nestedStep.repeat !== undefined || nestedStep.each !== undefined;
+        if (!isNestedLoop && nestedStep.as && loopVars[nestedStep.as] !== undefined) {
+          vars[nestedStep.as] = loopVars[nestedStep.as];
+        }
+      }
+    }
+    
+    return { success: true, stepsExecuted: totalExecuted };
+  }
+  
+  // Regular step (non-loop)
+  if (onProgress) {
+    onProgress(step, 'start');
+  }
+  
+  const result = await executeSingleStep(step, vars, context, options);
+  
+  if (onProgress) {
+    onProgress(step, result.success ? 'ok' : 'fail', result.error);
+  }
+  
+  return { ...result, stepsExecuted: 1 };
+}
+
 /**
  * Execute all workflow steps sequentially
- * @param {Array<{ cmd: string, args: object }>} steps - Steps to execute
+ * @param {Array<object>} steps - Steps to execute
  * @param {object} options - Execution options
  * @returns {Promise<object>} - Execution result
  */
@@ -147,118 +409,111 @@ async function executeDoSteps(steps, options = {}) {
     stepDelay = 100,
     context = {},
     quiet = false,  // For --json mode, suppress streaming output
+    vars: initialVars = {},
   } = options;
   
   const results = [];
-  const vars = context.vars || {};
+  const vars = { ...initialVars, ...(context.vars || {}) };
   const total = steps.length;
   let failed = 0;
+  let stepsExecuted = 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;
+    // Check if this is a loop step
+    const isLoop = step.repeat !== undefined || step.each !== undefined;
     
-    // Print step prefix (streaming output)
-    if (!quiet) {
-      process.stdout.write(`${stepNum} ${desc} ... `);
-    }
-    
-    try {
-      // Substitute variables in args
-      const resolvedArgs = substituteVars(step.args, vars);
+    if (isLoop) {
+      // Loops handle their own progress output
+      if (!quiet) {
+        const loopType = step.repeat !== undefined ? `repeat ${step.repeat}` : `each ${step.each}`;
+        console.log(`[${i + 1}/${total}] Loop: ${loopType} (${step.steps?.length || 0} nested steps)`);
+      }
       
-      const resp = await sendDoRequest(step.cmd, resolvedArgs, context);
+      const result = await executeStep(step, vars, context, { onError, autoWait, stepDelay }, null);
       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 });
+      stepsExecuted += result.stepsExecuted || 0;
+      
+      if (!result.success) {
+        results.push({ step: i + 1, type: 'loop', status: 'error', error: result.error, ms });
         failed++;
         
         if (onError === 'stop') {
           return { 
             status: 'failed', 
-            completedSteps: i, 
+            completedSteps: stepsExecuted, 
             totalSteps: total, 
             results, 
-            error: errText,
-            totalMs: Date.now() - startTotal
+            error: result.error,
+            totalMs: Date.now() - startTotal,
+            vars
           };
         }
       } else {
+        results.push({ step: i + 1, type: 'loop', status: 'ok', stepsExecuted: result.stepsExecuted, ms });
         if (!quiet) {
-          console.log(`OK (${ms}ms)`);
+          console.log(`     Loop completed: ${result.stepsExecuted} steps (${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;
+    } else {
+      // Regular step
+      const stepNum = `[${i + 1}/${total}]`;
+      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;
       
       if (!quiet) {
-        console.log(`FAIL`);
-        console.log(`     Error: ${err.message}`);
+        process.stdout.write(`${stepNum} ${desc} ... `);
       }
       
-      results.push({ step: i + 1, cmd: step.cmd, status: 'error', error: err.message, ms });
-      failed++;
+      const result = await executeSingleStep(step, vars, context, { onError, autoWait, stepDelay });
+      const ms = Date.now() - startTime;
+      stepsExecuted++;
       
-      if (onError === 'stop') {
-        return { 
-          status: 'failed', 
-          completedSteps: i, 
-          totalSteps: total, 
-          results, 
-          error: err.message,
-          totalMs: Date.now() - startTotal
-        };
+      if (!result.success) {
+        if (!quiet) {
+          console.log('FAIL');
+          console.log(`     Error: ${result.error}`);
+        }
+        
+        results.push({ step: i + 1, cmd: step.cmd, status: 'error', error: result.error, ms });
+        failed++;
+        
+        if (onError === 'stop') {
+          return { 
+            status: 'failed', 
+            completedSteps: stepsExecuted - 1, 
+            totalSteps: total, 
+            results, 
+            error: result.error,
+            totalMs: Date.now() - startTotal,
+            vars
+          };
+        }
+      } else {
+        if (!quiet) {
+          console.log(`OK (${ms}ms)`);
+        }
+        results.push({ step: i + 1, cmd: step.cmd, status: 'ok', ms });
       }
     }
   }
   
   return { 
     status: failed > 0 ? 'partial' : 'completed', 
-    completedSteps: total - failed, 
+    completedSteps: stepsExecuted, 
     totalSteps: total, 
     results,
     failed,
-    totalMs: Date.now() - startTotal
+    totalMs: Date.now() - startTotal,
+    vars
   };
 }
 
@@ -268,6 +523,11 @@ module.exports = {
   shouldAutoWait,
   getAutoWaitCommand,
   substituteVars,
+  resolveVar,
+  extractStepOutput,
+  executeStep,
+  executeSingleStep,
   AUTO_WAIT_COMMANDS,
-  AUTO_WAIT_MAP
+  AUTO_WAIT_MAP,
+  MAX_LOOP_ITERATIONS
 };

package/package.json

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