browser4-cli 0.1.28 → 0.1.30

package/README.md

@@ -513,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.28",
+  "version": "0.1.30",
   "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.
@@ -158,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
 
@@ -240,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
 
 # ---------------------------------------------------------------------------