surf-cli 2.4.1 → 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` |