browser4-cli 0.1.27 → 0.1.29

package/README.md

@@ -169,8 +169,8 @@ browser4-cli -s mysession goto https://example.com
 
 | Command | Description |
 |---|---|
-| `click <ref> [button]` | Click an element. `--modifiers` for modifier keys. |
-| `dblclick <ref> [button]` | Double-click an element. `--modifiers` for modifier keys. |
+| `click <ref> [button]` | Click an element. `--modifiers` for modifier keys, `--follow` to detect and switch to new tabs opened by the click. |
+| `dblclick <ref> [button]` | Double-click an element. `--modifiers` for modifier keys, `--follow` to detect and switch to new tabs. |
 | `hover <ref>` | Hover over an element. |
 | `drag <startRef> <endRef>` | Drag and drop between two elements. |
 | `fill <ref> <text>` | Fill text into an editable element. `--submit` to press Enter after. `--verify` to confirm. |
@@ -193,7 +193,7 @@ browser4-cli select e12 "option-value"
 
 | Command | Description |
 |---|---|
-| `press <key> [ref]` | Press a key (`a`, `Enter`, `ArrowLeft`, `Escape`). Supports `--verify`. |
+| `press <key> [ref]` | Press a key (`a`, `Enter`, `ArrowLeft`, `Escape`). Supports `--verify`, `--follow` (detect new tabs). |
 | `keydown <key>` | Press and hold a key. |
 | `keyup <key>` | Release a key. |
 | `mousemove <x> <y>` | Move mouse to coordinates. |
@@ -264,11 +264,11 @@ browser4-cli tab-close 1
 |---|---|
 | `snapshot` | Capture an accessibility snapshot. See [Snapshot](#snapshot) below. |
 | `get <mode> <selector> [name]` | Extract data from a page element in one of six modes (see below). |
-| `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element. `--file <path>` to read from file. `--json` to wrap scalar results. |
+| `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element. `--file <path>`, `--base64`, or `--stdin` to provide the expression. `--json` to wrap scalar results. |
 | `generate-locator <ref>` | Generate a stable CSS selector path for an element. |
 | `htmlsnapshot` | Short form of `htmlsnapshot capture`. Capture a static HTML snapshot. See [HTML Snapshot](#dom-snapshot) below. |
 | `htmlsnapshot capture` | Capture a static HTML snapshot. See [HTML Snapshot](#dom-snapshot) below. |
-| `extract <instruction>` | Extract structured data with AI. `--schema <file>` for typed output. `--filename <path>`, `--raw`. |
+| `extract <instruction>` | Extract structured data with AI. `--schema <json>` for typed output. `--filename <path>`, `--raw`. |
 | `summarize [instruction]` | Summarize page content with AI. `--selector <css>`, `--filename <path>`, `--raw`. |
 
 `get` modes:
@@ -286,8 +286,10 @@ browser4-cli tab-close 1
 browser4-cli eval "document.title"
 browser4-cli eval "el => el.textContent" e15
 browser4-cli eval --file script.js
+browser4-cli eval --base64 ZG9jdW1lbnQudGl0bGU=
 browser4-cli generate-locator e5
 browser4-cli extract "product name, price, and rating"
+browser4-cli extract "contacts" --schema '{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}}'
 browser4-cli summarize --selector "#reviews"
 ```
 
@@ -511,7 +513,7 @@ paginated at 2000 lines by default; `get all text` is not paginated by default.
 > **correlated multi-field extraction** (title + price + URL per item), use
 > `htmlsnapshot query` with X-SQL's `DOM_LOAD_AND_SELECT` — it scopes each row
 > to a parent container so fields stay aligned. See the
-> [list-page scraping pattern](skill/references/x-sql-dom-load-select.md).
+> [list-page scraping pattern](skills/browser4-cli/references/x-sql-dom-load-select.md).
 
 ```bash
 browser4-cli htmlsnapshot get all text "h2 a"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [

package/scripts/README.md

@@ -0,0 +1,135 @@
+# CLI Scripts
+
+Build, install, test, and publish utilities for the browser4-cli native binary and npm package.
+
+## Build
+
+| Script | Platform | Purpose |
+|--------|----------|---------|
+| `build-all-platforms.sh` | Linux/macOS | Docker-based cross-compilation for all targets |
+| `build-all-platforms.ps1` | Windows | PowerShell equivalent — same targets via Docker |
+| `copy-native.js` | All (Node) | Copies the compiled Rust binary to `bin/` with platform-specific naming |
+
+Both build-all-platforms scripts produce binaries for:
+- `x86_64-unknown-linux-gnu` (Linux x64, glibc)
+- `aarch64-unknown-linux-gnu` (Linux arm64, glibc)
+- `x86_64-unknown-linux-musl` (Linux x64, musl)
+- `aarch64-unknown-linux-musl` (Linux arm64, musl)
+- `x86_64-pc-windows-gnu` (Windows x64)
+- `x86_64-apple-darwin` (macOS x64)
+- `aarch64-apple-darwin` (macOS arm64)
+
+Options: `--skip-docker-build`, `--dry-run`.
+
+`copy-native.js` expects a pre-built binary at `browser4-cli/target/release/browser4-cli` and copies it to `bin/browser4-cli-<platform>-<arch>`.
+
+## Install
+
+| Script | Platform | Purpose |
+|--------|----------|---------|
+| `install-browser4-cli.sh` | Linux/macOS | Download and install the native binary |
+| `install-browser4-cli.ps1` | Windows | PowerShell equivalent |
+
+Both scripts auto-detect OS, CPU architecture, and libc variant (glibc vs musl on Linux). They download the matching binary from GitHub Releases or Alibaba Cloud OSS (auto-selected by locale: OSS first in China mainland). The binary is installed to a user-local directory and optionally added to PATH.
+
+### Common options
+
+| Option | Description |
+|--------|-------------|
+| `--version, -v TAG` | Release tag (e.g. `v4.11.0`). Default: latest. |
+| `--install-dir, -d DIR` | Install directory (default: `~/.local/bin` on Unix, `%LOCALAPPDATA%\Programs\browser4-cli` on Windows). |
+| `--source SRC` | Force download source: `github` or `oss`. Default: auto (locale-aware). |
+| `--no-path` / `-AddToPath:$false` | Skip adding the install directory to PATH. |
+| `--silent, -s` / `-Silent` | Suppress non-error output. |
+| `--dry-run` / `-DryRun` | Print what would be done without doing it. |
+| `--skip-if-installed` / `-SkipIfInstalled` | Skip download if binary already exists. |
+| `--skip-local` / `-SkipLocal` | Skip local bundled binary check; always download. |
+| `--locate` (sh only) | Print detection results and exit (no install). |
+
+### One-liner install
+
+```shell
+# Linux / macOS
+curl -fsSL https://raw.githubusercontent.com/platonai/Browser4/main/cli/scripts/install-browser4-cli.sh | bash
+
+# Windows (PowerShell)
+iwr -useb https://raw.githubusercontent.com/platonai/Browser4/main/cli/scripts/install-browser4-cli.ps1 | iex
+```
+
+## Test
+
+| Script | Platform | Purpose |
+|--------|----------|---------|
+| `smoke-test-runtime-bundle.sh` | Linux/macOS | End-to-end CLI smoke test against a runtime bundle |
+
+Runs a full CLI smoke test suitable for CI and local development:
+
+1. Extracts a platform runtime bundle (`.tar.gz` or `.zip`)
+2. Sets up a local runtime directory (no network download)
+3. Starts a Python HTTP server serving a minimal interactive page
+4. Executes the full command cycle: `open` → `goto` → `snapshot` → `type` → `click` → `get` → `eval` → `screenshot` → `wait` → `close` → `kill-all`
+5. Reports pass/fail for each step
+
+```shell
+./smoke-test-runtime-bundle.sh <cli-binary> <bundle-archive> [test-port] [timeout-secs]
+```
+
+### Install script tests
+
+| File | Purpose |
+|------|---------|
+| `tests/install-browser4-cli.tests.sh` | Unit tests for the Unix install script |
+| `tests/install-browser4-cli.tests.ps1` | Unit tests for the Windows install script (Pester) |
+
+## Publish (npm)
+
+| Script | Purpose |
+|--------|---------|
+| `npm-publish-check.js` | Shared library: reads package metadata and compares local vs npm registry version |
+| `check-npm-publish-needed.js` | CLI wrapper: checks whether a publish is needed and prints the decision |
+| `publish-if-needed.js` | Publishes to npm only when the local version differs from the registry |
+| `postinstall.js` | npm `postinstall` hook: downloads the platform native binary after `npm install` |
+
+### Version check
+
+```shell
+node scripts/check-npm-publish-needed.js        # human-readable output
+node scripts/check-npm-publish-needed.js --json  # JSON output
+node scripts/check-npm-publish-needed.js --shell # shell-var output
+node scripts/check-npm-publish-needed.js --github-output  # append to $GITHUB_OUTPUT
+```
+
+### Conditional publish
+
+```shell
+node scripts/publish-if-needed.js             # publish if versions differ
+node scripts/publish-if-needed.js --dry-run   # print what would happen
+```
+
+Optional env: `BROWSER4_CLI_NPM_REMOTE_VERSION` to override the remote version for testing.
+
+### Postinstall
+
+`postinstall.js` runs automatically after `npm install browser4-cli`. It detects the platform and downloads the matching native binary to `bin/`. On global installs, it also patches npm's bin shims to invoke the native binary directly.
+
+## Documentation
+
+| Script | Platform | Purpose |
+|--------|----------|---------|
+| `enumerate-help.ps1` | Windows (pwsh) | Discovers all CLI commands/subcommands and generates categorized help output |
+
+Enumerates every browser4-cli command (including hidden ones), captures `--help` output for each, and saves organized documentation to `cli/help-output/`:
+
+- Top-level help overview
+- One file per command (with numbered prefixes for ordering)
+- Prefix group overviews (`swarm`, `agent`, `htmlsnapshot`, `crawl`, `snapshot`)
+- `INDEX.md` for easy navigation
+
+```powershell
+.\enumerate-help.ps1
+.\enumerate-help.ps1 -Binary "C:\tools\browser4-cli.exe" -OutDir ".\docs\cli-help"
+```
+
+---
+
+This README is intentionally concise; extend as the script collection grows.

package/scripts/smoke-test-runtime-bundle.sh

@@ -9,7 +9,7 @@
 #   1. Extracts the platform runtime bundle (.tar.gz or .zip)
 #   2. Sets up a local "installed" runtime directory (no network download)
 #   3. Starts a Python HTTP server serving a minimal interactive page
-#   4. Runs CLI commands: open → goto → type → click → close → kill-all
+#   4. Runs CLI commands: open → goto → snapshot → type → click → get → eval → screenshot → wait → close → kill-all
 #   5. Reports pass/fail for each step
 #
 # Designed for CI (GitHub Actions) but also runs on developer machines.
@@ -101,11 +101,16 @@ case "$BUNDLE_ARCHIVE" in
         tar xzf "$BUNDLE_ARCHIVE" -C "$EXTRACT_DIR"
         ;;
     *.zip)
+        # On Windows (Git Bash / MSYS2), Python is a native Windows program.
+        # MSYS2 auto-converts command-line *arguments* that look like Unix
+        # paths, but it cannot see paths embedded inside a -c string literal.
+        # Pass the paths as sys.argv entries so they are correctly translated
+        # to Windows-native paths before Python receives them.
         python3 -c "
 import zipfile, sys
-with zipfile.ZipFile('$BUNDLE_ARCHIVE', 'r') as z:
-    z.extractall('$EXTRACT_DIR')
-" 2>/dev/null || unzip -q "$BUNDLE_ARCHIVE" -d "$EXTRACT_DIR"
+with zipfile.ZipFile(sys.argv[1], 'r') as z:
+    z.extractall(sys.argv[2])
+" "$BUNDLE_ARCHIVE" "$EXTRACT_DIR" 2>/dev/null || unzip -q "$BUNDLE_ARCHIVE" -d "$EXTRACT_DIR"
         ;;
     *)
         fail "Unsupported archive format: $BUNDLE_ARCHIVE (expected .tar.gz or .zip)"
@@ -153,6 +158,7 @@ cat > "$TEST_PAGE" <<'HTML'
 <h1>Browser4 Smoke Test</h1>
 <input id="input1" type="text" value="">
 <button id="btn1" onclick="document.getElementById('input1').value='clicked'">Click Me</button>
+<span id="output">ready</span>
 </body></html>
 HTML
 
@@ -235,10 +241,25 @@ check_step "type" type "hello-smoke" "#input1"
 # 4d. click — click the button
 check_step "click" click "#btn1"
 
-# 4e. close — close the active session
+# 4e. snapshot — capture page accessibility tree
+check_step "snapshot" snapshot
+
+# 4f. get text — extract text content from an element
+check_step "get text" get text "#output"
+
+# 4g. eval — execute JavaScript on the page
+check_step "eval" eval "document.title"
+
+# 4h. screenshot — capture page screenshot
+check_step "screenshot" screenshot
+
+# 4i. wait — wait for an element to be present
+check_step "wait" wait "#output"
+
+# 4j. close — close the active session
 check_step "close" close
 
-# 4f. kill-all — stop the server and clean up
+# 4k. kill-all — stop the server and clean up
 check_step "kill-all" kill-all
 
 # ---------------------------------------------------------------------------