browser4-cli 0.1.5 → 0.1.6

package/README.md

@@ -0,0 +1,370 @@
+# Browser4 CLI
+
+Make websites accessible for AI agents. Automate tasks online with ease.
+
+## Installation
+
+### Global Installation (recommended)
+
+Installs the native Rust binary:
+
+```bash
+npm install -g browser4-cli
+```
+
+After installation, use `browser4-cli`. The shorter `browser4` command remains
+available as a compatibility alias.
+
+### Project Installation (local dependency)
+
+For projects that want to pin the version in `package.json`:
+
+```bash
+npm install browser4-cli
+```
+
+Then use via `package.json` scripts or by invoking `browser4-cli` directly.
+
+### Homebrew (macOS)
+
+```bash
+brew install browser4-cli
+```
+
+### Cargo (Rust)
+
+```bash
+cargo install browser4-cli
+```
+
+### From Source
+
+```bash
+git clone https://github.com/platonai/browser4-cli
+cd cli/browser4-cli
+pnpm install
+pnpm build:native   # Requires Rust (https://rustup.rs)
+pnpm link --global  # Makes browser4-cli available globally
+```
+
+### Requirements
+
+- **Chrome** - Latest Chrome installed on your system.
+- **Java 17+** - Required to run the Browser4 backend (`Browser4.jar`).
+- **Rust** - Only needed when building from source (see From Source above).
+
+
+
+
+
+
+
+
+
+
+
+## Usage
+
+```
+browser4-cli <command> [args] [options]
+browser4-cli -s=<session> <command> [args] [options]
+```
+
+### Global options
+
+| Flag               | Description                                    |
+|--------------------|------------------------------------------------|
+| `--help [command]` | Print help (optionally for a specific command) |
+| `--version`        | Print version                                  |
+| `-s=<name>`        | Named session label                            |
+| `--server=<url>`   | Override Browser4 server URL                   |
+
+Sessions are persisted independently per name. Omitting `-s` uses the
+default session (`~/.browser4/cli-state.json`). With `-s=<name>`, a
+separate state file is stored under `~/.browser4/sessions/<name>.json`.
+`open` without `-s` reuses the default session if one exists; with
+`-s=<name>` it switches to or creates the named session.
+
+### Commands
+
+The tables below mirror the commands surfaced by the global `browser4-cli help` overview.
+
+#### Core
+
+| Command | Description |
+|---|---|
+| `open [url]` | Open or switch to a browser session (optionally navigate to URL) |
+| `close` | Close the active session |
+| `goto <url>` | Navigate to a URL using the current active session |
+| `click <ref> [button]` | Click an element |
+| `dblclick <ref> [button]` | Double-click an element |
+| `type <text> [ref]` | Type text into the focused element or an optional target element |
+| `fill <ref> <text>` | Fill text into an editable element |
+| `hover <ref>` | Hover over an element |
+| `select <ref> <val>` | Select an option in a dropdown |
+| `upload <ref> <file>` | Upload a file |
+| `check <ref>` | Check a checkbox or radio button |
+| `uncheck <ref>` | Uncheck a checkbox or radio button |
+| `drag <startRef> <endRef>` | Drag and drop between two elements |
+| `snapshot` | Capture accessibility snapshot |
+| `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element |
+| `dialog-accept [prompt]` | Accept a dialog |
+| `dialog-dismiss` | Dismiss a dialog |
+| `resize <w> <h>` | Resize the browser window |
+| `delete-data` | Delete session data |
+
+#### Navigation
+
+| Command | Description |
+|---|---|
+| `go-back` | Go back to the previous page |
+| `go-forward` | Go forward to the next page |
+| `reload` | Reload the current page |
+
+#### Keyboard
+
+| Command | Description |
+|---|---|
+| `press <key> [ref]` | Press a key on the focused element or an optional target element |
+| `keydown <key>` | Press and hold a key |
+| `keyup <key>` | Release a key |
+
+#### Mouse
+
+| Command | Description |
+|---|---|
+| `mousemove <x> <y>` | Move mouse to coordinates |
+| `mousedown [button]` | Press mouse button |
+| `mouseup [button]` | Release mouse button |
+| `mousewheel <dx> <dy>` | Scroll the mouse wheel |
+
+#### Save as
+
+| Command | Description |
+|---|---|
+| `screenshot [ref]` | Take a screenshot |
+| `pdf` | Save page as PDF |
+
+#### Tabs
+
+| Command | Description |
+|---|---|
+| `tab-list` | List all tabs |
+| `tab-new [url]` | Create a new tab |
+| `tab-close [index]` | Close a browser tab by zero-based index |
+| `tab-select <index>` | Select a browser tab by zero-based index |
+
+Use `tab-list` first to find the zero-based tab index you want to select or close.
+
+#### Browser sessions
+
+| Command | Description |
+|---|---|
+| `list` | List browser sessions |
+| `close-all` | Close all browser sessions without stopping `Browser4.jar` / the Browser4 backend |
+| `kill-all` | Forcefully stop `Browser4.jar` / the Browser4 backend and kill Browser4 browser processes |
+
+Use `close-all` for session cleanup when you want to keep the current Browser4 service running. Use `kill-all` only when you explicitly want to stop the backend and clean up tracked Browser4 processes.
+
+
+### Advanced commands
+
+These commands are intentionally omitted from the global `browser4-cli help` overview.
+Query `browser4-cli help <command>` for the exact syntax when you need them.
+
+| Command | Description |
+|---|---|
+| `batch [command...]` | Execute multiple commands in one invocation. Only DOM operations are supported (Core, Navigation, Keyboard, Mouse, Export, Tabs categories). Commands like `open`, `close`, `list`, `agent-run`, etc. are not allowed in batch mode. |
+| `console [min-level]` | List console messages |
+| `extract <instruction>` | Extract structured data from the current page |
+| `summarize [instruction]` | Summarize page content using AI |
+| `agent-run <task>` | Run an autonomous agent task |
+| `agent-status <id>` | Check the status of a running agent task |
+| `agent-result <id>` | Get the result of a completed agent task |
+| `co-create` | Create a collective session with parallel browser contexts |
+| `co-submit [url]` | Submit URL(s) or tasks to the active collective session |
+| `co-scrape <url>` | Scrape data from a URL using CSS selectors |
+| `co-status <id>` | Check the status of a collective task |
+| `co-result <id>` | Get the result of a completed collective task |
+
+## Element References
+
+The `snapshot` command returns an accessibility tree where every interactive
+node is labeled with a short identifier such as `e15`. Pass this identifier
+directly to commands like `click`, `type`, or `press`; the CLI automatically
+converts it to the `backend:15` selector format required by the server.
+
+You can also pass plain CSS selectors (e.g. `.my-button`, `#search-input`) or
+fully-qualified `backend:<N>` refs directly.
+
+## State Persistence
+
+`browser4-cli` persists CLI state between invocations under `~/.browser4` by
+default. Override the root directory with the `BROWSER4_CLI_STATE_DIR`
+environment variable.
+
+- Default session state: `~/.browser4/cli-state.json`
+- Named session state (`-s=<name>`): `~/.browser4/sessions/<name>.json`
+
+Each state file stores the current Browser4 server URL plus session-scoped
+fields such as:
+
+- `sessionId` — active Browser4 session ID
+- `baseUrl` — Browser4 backend URL used by the CLI
+- `activeSelector` — last selector tracked for keyboard restore flows
+- `lastMousePosition` — last pointer coordinates tracked for mouse restore flows
+
+### Session state transitions
+
+The `with_session()` helper in `src/main.rs` is the central session lifecycle
+gate for commands that require an active Browser4 session.
+
+| Situation | Persisted state transition | Result |
+|---|---|---|
+| No persisted session | No state change | `require_session()` fails with `No active session. Run "browser4-cli open" first.` |
+| `open` succeeds (no existing session) | `create_session()` writes a fresh state file with new `sessionId`, current `baseUrl`, and clears `activeSelector` / `lastMousePosition` | A new active session becomes the current CLI session |
+| `open` when a saved session exists and the backend still reports it `active` | No state change — keeps the existing `sessionId` | The existing session is reused; subsequent commands target the same session |
+| `open` when a saved session exists but is missing or no longer `active` in the backend | `invalidate_session()` clears the stale saved `sessionId`, `activeSelector`, and `lastMousePosition`, then `create_session()` writes a fresh session | The stale session is refreshed automatically by opening a new one |
+| `open -s=<name>` | Reads/writes the named session state file | Opens, reuses, or refreshes the named session for that slot; subsequent `-s=<name>` commands use the same slot |
+| Command succeeds through `with_session()` | `sessionId` stays unchanged | The command uses the persisted session normally |
+| Command fails because the server reports a stale / expired session and `recover_stale = false` | `invalidate_session()` clears `sessionId`, `activeSelector`, and `lastMousePosition`, while keeping `baseUrl` | The command fails with `Saved session expired. Run "browser4-cli open" first.` |
+| `goto` is invoked but the saved session is missing or no longer `active` in the backend | `invalidate_session()` clears the saved `sessionId`, `activeSelector`, and `lastMousePosition` | The command fails with `No active session for "goto". Run "browser4-cli open" to create or refresh the session first.` |
+| `close` with an active session | `clear_state()` removes only the current session state file after best-effort remote close | The selected default or named session is fully cleared |
+| `close` with no persisted `sessionId` | `clear_state()` best-effort removes the current session slot | Prints `No active session. Run "browser4-cli open" first.` and exits successfully as a no-op |
+| `close-all` / `kill-all` | `clear_all_state()` removes the default state file and all named session files | All persisted CLI session files are cleared |
+
+Notes:
+
+- `goto` reuses only the current backend-`active` session. It does not create a
+  new session automatically; run `browser4-cli open` first if the saved session
+  is missing or stale.
+- `open` first checks whether the saved session for the current slot is still
+  backend-`active`. It reuses active sessions and refreshes stale ones by
+  creating a new session for the same slot.
+- `list` reads persisted session files and compares them with live backend
+  sessions to show both the current status (`Active`, `Stale`, or `Unknown`)
+  and whether the next `open` will `Reuse` or `Refresh` that slot.
+
+## Runtime Temp Files
+
+`browser4-cli` keeps ephemeral runtime artifacts under the system temp directory:
+
+- Windows: `%TEMP%\.browser4\browser4-cli`
+- Linux/macOS: `${TMPDIR:-/tmp}/.browser4/browser4-cli`
+
+This temp subtree contains items such as:
+
+- startup logs for auto-started Browser4 servers
+- staged Maven wrapper launchers
+- Rust test scratch directories used by `browser4-cli` tests
+
+Persistent CLI state and the fallback `Browser4.jar` remain under `~/.browser4` by default.
+
+## Snapshots
+
+After each command that modifies browser state, the CLI automatically:
+
+1. Retrieves the current page URL and title
+2. Captures an accessibility snapshot
+3. Saves the snapshot to `.browser4-cli/snapshot/page-<timestamp>.yml`
+4. Prints the snapshot path in Markdown link format
+
+## Examples
+
+```shell
+# Open a new browser window
+browser4-cli open
+
+# Navigate to a page with the current active session
+browser4-cli goto https://playwright.dev
+
+# Inspect the page — note the eN labels on interactive nodes
+browser4-cli snapshot
+
+# Interact using refs from the snapshot
+browser4-cli click e15
+browser4-cli type "Hello World" e15
+browser4-cli press Enter e15
+browser4-cli eval "document.title"
+browser4-cli eval "element => element.textContent" e15
+browser4-cli keydown Shift
+browser4-cli mousemove 150 300
+browser4-cli mousewheel 0 100
+browser4-cli keyup Shift
+
+# Take a screenshot and save it to disk
+browser4-cli screenshot
+
+# Inspect tab indices before switching tabs
+browser4-cli tab-list
+browser4-cli tab-select 1
+browser4-cli tab-close 1
+
+# Use a custom server URL
+browser4-cli open --server http://localhost:9090
+
+# Advanced: execute multiple commands in one process (batch mode)
+# Batch mode only supports DOM operations. You must run `open` separately first.
+browser4-cli open
+browser4-cli batch "goto https://playwright.dev" "snapshot"
+
+# Advanced: stop on the first batch failure
+browser4-cli batch --bail "goto https://playwright.dev" "click e1" "screenshot"
+
+# Advanced: batch mode for form filling (recommended use case)
+browser4-cli batch "fill e1 'John Doe'" "fill e2 'john@example.com'" "click e3"
+
+# Advanced: pipe batch commands as JSON via stdin
+echo '[
+  ["goto", "https://example.com/form-filling"],
+  ["click", "#reset-btn"],
+  ["fill", "#first-name", "Bob"],
+  ["fill", "#last-name", "Smith"],
+  ["fill", "#email", "bob@example.com"],
+  ["select", "#country", "uk"],
+  ["check", "#agree-terms"],
+  ["click", "#submit-btn"]
+]' | browser4-cli batch --json
+
+# Close the session when done
+browser4-cli close
+
+# Close all sessions but keep the current Browser4 backend running
+browser4-cli close-all
+
+# Explicitly stop the Browser4 backend and clean up tracked Browser4 processes
+browser4-cli kill-all
+```
+
+## Architecture
+
+The Rust CLI is structured as follows:
+
+| Module | Purpose |
+|---|---|
+| `main.rs` | Entry point, command dispatch, session management |
+| `args.rs` | CLI argument parsing (global flags, positional args, options) |
+| `commands.rs` | Command definitions mapping to MCP tool names and parameters |
+| `http.rs` | HTTP client for calling `/mcp/call-tool` |
+| `state.rs` | Persistent state management for the default state file and named session files under `~/.browser4/` |
+| `daemon.rs` | Local server auto-start (prefer Maven from repo root, fall back to jar) and health checking |
+| `managed_processes.rs` | Registry for browser4 server processes |
+| `snapshot.rs` | Snapshot and screenshot file helpers |
+| `help.rs` | Help text generation |
+
+## Testing
+
+```bash
+## Run all tests (unit + end-to-end):
+cargo test
+
+## Run only the end-to-end tests and print their output:
+cargo test --test e2e -- --nocapture
+
+## Run a specific end-to-end test scenario:
+cargo test --test e2e -- --nocapture --scenario=test_e2e_batch_form_submission
+```
+
+## License
+
+Apache-2.0

package/bin/.install-method

@@ -0,0 +1 @@
+npm

package/bin/browser4-cli.js

@@ -2,18 +2,48 @@
 
 import fs from "fs";
 import path from "path";
-import { spawn } from "child_process";
+import { arch } from "os";
+import { execSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
 
 const __filename = fileURLToPath(import.meta.url);
 const scriptDir = path.dirname(__filename);
-const exeName = process.platform === "win32" ? "browser4-cli.exe" : "browser4-cli";
-const exePath = path.join(scriptDir, "target", "release", exeName);
 
-if (!fs.existsSync(exePath)) {
+function isMusl() {
+  if (process.platform !== "linux") {
+    return false;
+  }
+
+  try {
+    const result = execSync("ldd --version 2>&1 || true", { encoding: "utf8" });
+    return result.toLowerCase().includes("musl");
+  } catch {
+    return fs.existsSync("/lib/ld-musl-x86_64.so.1") || fs.existsSync("/lib/ld-musl-aarch64.so.1");
+  }
+}
+
+function resolveExecutableCandidates() {
+  const platformKey = `${process.platform === "linux" && isMusl() ? "linux-musl" : process.platform}-${arch()}`;
+  const nativeBinaryName = `browser4-cli-${platformKey}${process.platform === "win32" ? ".exe" : ""}`;
+  const sourceBinaryName = `browser4-cli${process.platform === "win32" ? ".exe" : ""}`;
+
+  return [
+    path.join(scriptDir, nativeBinaryName),
+    path.join(scriptDir, "target", "release", sourceBinaryName),
+    path.join(scriptDir, "..", "browser4-cli", "target", "release", sourceBinaryName),
+  ];
+}
+
+const candidatePaths = resolveExecutableCandidates();
+const exePath = candidatePaths.find((candidate) => fs.existsSync(candidate));
+
+if (!exePath) {
   const scriptName = path.basename(__filename);
-  console.error(`[${scriptName}] ERROR: executable not found: "${exePath}"`);
-  console.error(`[${scriptName}] Run: cargo build --release (in cli/browser4-cli)`);
+  console.error(`[${scriptName}] ERROR: executable not found. Checked:`);
+  for (const candidate of candidatePaths) {
+    console.error(`  - ${candidate}`);
+  }
+  console.error(`[${scriptName}] Run: npm install browser4-cli or cargo build --release --manifest-path cli/browser4-cli/Cargo.toml`);
   process.exit(1);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [
@@ -10,6 +10,7 @@
     "skills"
   ],
   "bin": {
+    "browser4-cli": "./bin/browser4-cli.js",
     "browser4": "./bin/browser4-cli.js"
   },
   "scripts": {
@@ -27,12 +28,12 @@
   "keywords": [
     "browser",
     "browser4",
+    "browser4-cli",
     "automation",
     "headless",
     "chrome",
     "cdp",
     "cli",
-    "browser4-cli",
     "agent"
   ],
   "license": "Apache-2.0",
@@ -44,6 +45,8 @@
     "url": "https://github.com/platonai/Browser4/issues"
   },
   "homepage": "https://browser4.io",
-  "devDependencies": {},
-  "packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be"
+  "packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be",
+  "dependencies": {
+    "browser4-cli": "^0.1.5"
+  }
 }

package/scripts/postinstall.js

@@ -43,6 +43,7 @@ const packageJson = JSON.parse(
   (await import('fs')).readFileSync(join(projectRoot, 'package.json'), 'utf8')
 );
 const version = packageJson.version;
+const commandNames = Object.keys(packageJson.bin || { 'browser4-cli': './bin/browser4-cli.js' });
 
 // GitHub release URL
 const GITHUB_REPO = 'platonai/Browser4';
@@ -202,12 +203,12 @@ function showInstallReminder() {
   console.log('  ⚠ No Chrome installation detected.');
   console.log('  If you plan to use a local browser, run:');
   console.log('');
-  console.log('    browser4 install');
+  console.log('    browser4-cli install');
   if (platform() === 'linux') {
     console.log('');
     console.log('  On Linux, include system dependencies with:');
     console.log('');
-    console.log('    browser4 install --with-deps');
+    console.log('    browser4-cli install --with-deps');
   }
   console.log('');
   console.log('  You can skip this if you use --cdp, --provider, --engine, or --executable-path.');
@@ -240,27 +241,31 @@ async function fixUnixSymlink() {
     return; // npm not available
   }
 
-  const symlinkPath = join(npmBinDir, 'browser4');
+  let optimized = false;
+  for (const commandName of commandNames) {
+    const symlinkPath = join(npmBinDir, commandName);
 
-  // Check if symlink exists (indicates global install)
-  try {
-    const stat = lstatSync(symlinkPath);
-    if (!stat.isSymbolicLink()) {
-      return; // Not a symlink, don't touch it
+    try {
+      const stat = lstatSync(symlinkPath);
+      if (!stat.isSymbolicLink()) {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+
+    try {
+      unlinkSync(symlinkPath);
+      symlinkSync(binaryPath, symlinkPath);
+      optimized = true;
+    } catch (err) {
+      console.log(`⚠ Could not optimize symlink for ${commandName}: ${err.message}`);
+      console.log('  CLI will work via Node.js wrapper (slightly slower startup)');
     }
-  } catch {
-    return; // Symlink doesn't exist, not a global install
   }
 
-  // Replace symlink to point directly to native binary
-  try {
-    unlinkSync(symlinkPath);
-    symlinkSync(binaryPath, symlinkPath);
+  if (optimized) {
     console.log('✓ Optimized: symlink points to native binary (zero overhead)');
-  } catch (err) {
-    // Permission error or other issue - not critical, JS wrapper still works
-    console.log(`⚠ Could not optimize symlink: ${err.message}`);
-    console.log('  CLI will work via Node.js wrapper (slightly slower startup)');
   }
 }
 
@@ -277,19 +282,9 @@ async function fixWindowsShims() {
     return;
   }
 
-  const cmdShim = join(npmBinDir, 'browser4.cmd');
-  const ps1Shim = join(npmBinDir, 'browser4.ps1');
-
-  // Shims may not exist yet during postinstall (npm creates them after
-  // lifecycle scripts). If missing, fall back: the JS wrapper at
-  // bin/browser4.js handles Windows correctly via child_process.spawn.
-  if (!existsSync(cmdShim)) {
-    return;
-  }
-
   // Detect architecture so ARM64 Windows is handled correctly
   const cpuArch = arch() === 'arm64' ? 'arm64' : 'x64';
-  const relativeBinaryPath = `node_modules\\browser4\\bin\\browser4-win32-${cpuArch}.exe`;
+  const relativeBinaryPath = `node_modules\\${packageJson.name}\\bin\\browser4-cli-win32-${cpuArch}.exe`;
   const absoluteBinaryPath = join(npmBinDir, relativeBinaryPath);
 
   // Only rewrite shims if the native binary actually exists
@@ -298,13 +293,31 @@ async function fixWindowsShims() {
   }
 
   try {
-    const cmdContent = `@ECHO off\r\n"%~dp0${relativeBinaryPath}" %*\r\n`;
-    writeFileSync(cmdShim, cmdContent);
-
-    const ps1Content = `#!/usr/bin/env pwsh\r\n$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent\r\n& "$basedir\\${relativeBinaryPath}" $args\r\nexit $LASTEXITCODE\r\n`;
-    writeFileSync(ps1Shim, ps1Content);
+    let optimized = false;
+    for (const commandName of commandNames) {
+      const cmdShim = join(npmBinDir, `${commandName}.cmd`);
+      const ps1Shim = join(npmBinDir, `${commandName}.ps1`);
+
+      if (!existsSync(cmdShim) && !existsSync(ps1Shim)) {
+        continue;
+      }
+
+      if (existsSync(cmdShim)) {
+        const cmdContent = `@ECHO off\r\n"%~dp0${relativeBinaryPath}" %*\r\n`;
+        writeFileSync(cmdShim, cmdContent);
+      }
+
+      if (existsSync(ps1Shim)) {
+        const ps1Content = `#!/usr/bin/env pwsh\r\n$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent\r\n& "$basedir\\${relativeBinaryPath}" $args\r\nexit $LASTEXITCODE\r\n`;
+        writeFileSync(ps1Shim, ps1Content);
+      }
+
+      optimized = true;
+    }
 
-    console.log('✓ Optimized: shims point to native binary (zero overhead)');
+    if (optimized) {
+      console.log('✓ Optimized: shims point to native binary (zero overhead)');
+    }
   } catch (err) {
     console.log(`⚠ Could not optimize shims: ${err.message}`);
     console.log('  CLI will work via Node.js wrapper (slightly slower startup)');