browser4-cli 0.1.12 → 0.1.14

package/README.md

@@ -37,21 +37,66 @@ brew install browser4-cli
 cargo install browser4-cli
 ```
 
+### Standalone Installer Scripts (no npm / Rust / Homebrew needed)
+
+Bootstrap the native binary directly with a single command:
+
+**Windows (PowerShell):**
+```powershell
+Invoke-WebRequest -Uri "https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1" -OutFile "$env:TEMP\install-browser4-cli.ps1"
+powershell -ExecutionPolicy Bypass -File "$env:TEMP\install-browser4-cli.ps1"
+```
+
+**Linux / macOS (bash):**
+```bash
+curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash
+```
+
+Or run the scripts locally from a cloned repo:
+- `cli/scripts/install-browser4-cli.ps1` (Windows)
+- `cli/scripts/install-browser4-cli.sh` (Linux / macOS / Git Bash)
+
+See [Standalone CLI Installer Scripts](../docs/cli-standalone-install.md) for
+the full option reference, supported platforms, and examples.
+
 ### From Source
 
+**Build prerequisites:** Rust (stable, edition 2021), Node.js 24+, pnpm 10+, git.
+
 ```bash
-git clone https://github.com/platonai/browser4-cli
-cd cli/browser4-cli
+git clone https://github.com/platonai/Browser4.git
+cd Browser4/cli/browser4-cli
 pnpm install
-pnpm build:native   # Requires Rust (https://rustup.rs)
+pnpm build:native   # Compiles the Rust binary (requires https://rustup.rs)
 pnpm link --global  # Makes browser4-cli available globally
 ```
 
+Cross-compilation from Linux (for release builds) additionally requires:
+`cargo-zigbuild`, Zig 0.13.0, `gcc-aarch64-linux-gnu`, and `mingw-w64`.
+See `cli/docker/Dockerfile.build` for a Dockerized build environment.
+
 ### 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).
+- **Chrome** — Latest Chrome installed on your system. The CLI can auto-install Chrome on most platforms when missing.
+- **Java 17+** — Required to run the Browser4 backend (`Browser4.jar`). Eclipse Temurin recommended. JDK 21+ enables best jlink compression when the CLI auto-builds a runtime bundle from source.
+- **Rust** — Only needed when building the CLI from source (see From Source above). The `stable` toolchain (edition 2021) is sufficient.
+
+#### Additional requirements for auto-building a runtime bundle from source
+
+When the CLI detects a Browser4 repository checkout, it attempts to build a
+self-contained runtime bundle (bundled JRE + dependency JARs) from source
+instead of downloading a pre-built release. This requires:
+
+| Tool | Version | Linux | macOS | Windows |
+|------|---------|-------|-------|---------|
+| **Maven** | 3.9+ | via `mvnw` wrapper | via `mvnw` wrapper | via `mvnw.cmd` wrapper |
+| **JDK tools** (`jdeps`, `jlink`) | bundled with JDK 16+ | included in JDK | included in JDK | included in JDK |
+| **PowerShell 7** (`pwsh`) | 7.0+ | **required** | **required** | built-in (`powershell.exe`) |
+| **tar** | any | **required** | **required** | built-in |
+
+Set `BROWSER4_CLI_FORCE_REMOTE_BUNDLE=1` to skip the local build and always
+download a pre-built bundle — useful in CI / corporate environments where
+Maven or jlink are unavailable.
 
 ## Usage
 
@@ -242,7 +287,7 @@ Like other advanced commands, they are intentionally omitted from the global
 Use the spaced `agent <subcommand>` form:
 
 ```shell
-browser4-cli agent run "Open example.com and summarize the hero section"
+browser4-cli agent run "Open browser4.io and summarize the hero section"
 browser4-cli agent status agent-task-1
 browser4-cli agent result agent-task-1
 ```
@@ -344,7 +389,7 @@ browser4-cli swarm submit https://example.com/direct \
   --seed-file=./swarm-seeds.txt \
   --deadline=2026-03-30T00:00:00Z \
   --expires=1d \
-  --refresh --parse --store-content
+  --refresh --store-content
 
 # poll and fetch the result
 browser4-cli swarm status scrape-task-4
@@ -369,7 +414,7 @@ browser4-cli swarm query "https://www.amazon.com/dp/B08PP5MSVB" --sql "
 browser4-cli swarm query "https://www.amazon.com/dp/B08PP5MSVB" --sql @query.sql
 
 # With seed file and load options:
-browser4-cli swarm query --sql @query.sql --seed-file=./urls.txt --refresh --parse
+browser4-cli swarm query --sql @query.sql --seed-file=./urls.txt --refresh
 ```
 
 ### Notes

package/package.json

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

package/scripts/install-browser4-cli.ps1

@@ -0,0 +1,474 @@
+<#
+.SYNOPSIS
+  Install browser4-cli — download the native binary and set it up on your PATH.
+
+.DESCRIPTION
+  Detects your OS and CPU architecture, downloads the matching native binary from
+  GitHub Releases or Alibaba Cloud OSS, installs it to a user-local directory, and
+  optionally adds it to your PATH.
+
+  Default install location:
+    Windows:  $env:LOCALAPPDATA\Programs\browser4-cli
+    (override with -InstallDir)
+
+  Download sources (tried in order unless -Source is specified):
+    1. GitHub Releases   — https://github.com/platonai/Browser4
+    2. Aliyun OSS        — https://browser4.oss-cn-beijing.aliyuncs.com
+
+.PARAMETER Version
+  Release version tag to download (e.g. "v4.11.0" or "v0.1.12-cli").
+  Defaults to "latest" which resolves to the most recent stable release.
+
+.PARAMETER InstallDir
+  Directory to install the binary into.
+  Default: $env:LOCALAPPDATA\Programs\browser4-cli
+
+.PARAMETER Source
+  Force a specific download source: "github" or "oss".
+  Default: try GitHub first, fall back to OSS.
+
+.PARAMETER AddToPath
+  Add the install directory to the current user's PATH environment variable.
+  Default: true.
+
+.PARAMETER Silent
+  Suppress all non-error output.
+
+.PARAMETER DryRun
+  Print what would be done without actually doing it.
+
+.EXAMPLE
+  # Quick install — default location, latest version, add to PATH
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1
+
+.EXAMPLE
+  # Silent install with a specific version
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -Version "v4.11.0" -Silent
+
+.EXAMPLE
+  # Install from OSS only, custom directory
+  powershell -ExecutionPolicy Bypass -File install-browser4-cli.ps1 -Source oss -InstallDir "C:\tools\browser4"
+#>
+
+[CmdletBinding()]
+param(
+  [string]$Version = "",
+  [string]$InstallDir = "",
+  [ValidateSet("github", "oss")]
+  [string]$Source = "",
+  [bool]$AddToPath = $true,
+  [switch]$Silent,
+  [switch]$DryRun
+)
+
+$ErrorActionPreference = "Stop"
+
+# ──────────────────────────────────────────────
+# OS detection (compatible with PS 5.1+)
+# ──────────────────────────────────────────────
+
+$script:IsWin = [System.Environment]::OSVersion.Platform -eq "Win32NT"
+$script:IsMac = [System.Environment]::OSVersion.Platform -eq "Unix" -and (uname -s 2>$null) -eq "Darwin"
+$script:IsLinux = [System.Environment]::OSVersion.Platform -eq "Unix" -and (uname -s 2>$null) -ne "Darwin"
+
+# ──────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────
+
+function Write-Summary {
+  param([string]$Message, [string]$Color = "White")
+  if (-not $Silent) { Write-Host $Message -ForegroundColor $Color }
+}
+
+function Write-Step {
+  param([string]$Message)
+  if (-not $Silent) { Write-Host "  » $Message" -ForegroundColor Gray }
+}
+
+function Write-Check {
+  param([string]$Message)
+  if (-not $Silent) { Write-Host "    ✓ $Message" -ForegroundColor Green }
+}
+
+function Write-WarnMsg {
+  param([string]$Message)
+  if (-not $Silent) { Write-Host "    ⚠ $Message" -ForegroundColor Yellow }
+}
+
+# ──────────────────────────────────────────────
+# Detection
+# ──────────────────────────────────────────────
+
+function Get-PlatformKey {
+  $arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq [System.Runtime.InteropServices.Architecture]::Arm64) { "arm64" } else { "x64" }
+
+  if ($script:IsWin) {
+    return "win32-$arch"
+  }
+  elseif ($script:IsMac) {
+    return "darwin-$arch"
+  }
+  elseif ($script:IsLinux) {
+    # Detect musl
+    $isMusl = $false
+    try {
+      $lddOutput = ldd --version 2>&1
+      if ($lddOutput -match "musl") { $isMusl = $true }
+    } catch {
+      if ((Test-Path "/lib/ld-musl-x86_64.so.1") -or (Test-Path "/lib/ld-musl-aarch64.so.1")) {
+        $isMusl = $true
+      }
+    }
+    $libc = if ($isMusl) { "musl" } else { "" }
+    if ($libc) { return "linux-$libc-$arch" } else { return "linux-$arch" }
+  }
+  else {
+    throw "Unsupported OS. Browser4 CLI supports Windows, macOS, and Linux."
+  }
+}
+
+function Get-BinaryName {
+  param([string]$PlatformKey)
+  return "browser4-cli-$PlatformKey" + $(if ($PlatformKey.StartsWith("win32")) { ".exe" } else { "" })
+}
+
+function Get-DefaultInstallDir {
+  if ($script:IsWin) {
+    return Join-Path $env:LOCALAPPDATA "Programs\browser4-cli"
+  }
+  elseif ($script:IsLinux -or $script:IsMac) {
+    # Prefer ~/.local/bin for user installs
+    if (Test-Path "$env:HOME/.local/bin") {
+      return "$env:HOME/.local/bin"
+    }
+    return "$env:HOME/.local/bin"
+  }
+  throw "Unsupported OS"
+}
+
+# ──────────────────────────────────────────────
+# Download URLs
+# ──────────────────────────────────────────────
+
+$GITHUB_REPO = "platonai/Browser4"
+$OSS_BASE = "https://browser4.oss-cn-beijing.aliyuncs.com"
+
+function Get-DownloadUrls {
+  param([string]$BinaryName, [string]$VersionTag)
+
+  $urls = @()
+
+  $ghBase = "https://github.com/$GITHUB_REPO/releases/download"
+  if ($VersionTag) {
+    $ghUrl = "$ghBase/$VersionTag/$BinaryName"
+    $ossUrl = "$OSS_BASE/releases/download/$VersionTag/$BinaryName"
+  } else {
+    # Use 'latest' redirect for GitHub, 'latest' symlink for OSS
+    $ghUrl = "https://github.com/$GITHUB_REPO/releases/latest/download/$BinaryName"
+    $ossUrl = "$OSS_BASE/releases/download/latest/$BinaryName"
+  }
+
+  if ($Source -eq "github") {
+    $urls += @{ Url = $ghUrl; Label = "GitHub Releases" }
+  } elseif ($Source -eq "oss") {
+    $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
+  } else {
+    $urls += @{ Url = $ghUrl; Label = "GitHub Releases" }
+    $urls += @{ Url = $ossUrl; Label = "Aliyun OSS" }
+  }
+
+  return $urls
+}
+
+function Invoke-Download {
+  param([string]$Url, [string]$OutFile, [string]$Label)
+
+  Write-Step "Trying $Label..."
+  Write-Step "URL: $Url"
+
+  if ($DryRun) {
+    Write-Check "[DRY-RUN] Would download to: $OutFile"
+    return $true
+  }
+
+  try {
+    $ProgressPreference = if ($Silent) { "SilentlyContinue" } else { "Continue" }
+
+    # Use Invoke-WebRequest with progress bar
+    Invoke-WebRequest -Uri $Url -OutFile $OutFile -UseBasicParsing -ErrorAction Stop
+
+    if (Test-Path $OutFile) {
+      $size = (Get-Item $OutFile).Length
+      if ($size -gt 102400) {  # > 100 KB minimum
+        Write-Check "Downloaded $( [math]::Round($size / 1MB, 1) ) MB"
+        return $true
+      } else {
+        Write-WarnMsg "Downloaded file too small ($size bytes) — may be an error page"
+        Remove-Item $OutFile -Force -ErrorAction SilentlyContinue
+        return $false
+      }
+    }
+    Write-WarnMsg "Download appeared to succeed but file not found"
+    return $false
+  } catch {
+    Write-WarnMsg "Failed: $($_.Exception.Message)"
+    return $false
+  }
+}
+
+# ──────────────────────────────────────────────
+# Symlinks
+# ──────────────────────────────────────────────
+
+function New-PlatformLink {
+  param([string]$LinkPath, [string]$TargetName, [string]$DisplayName)
+
+  # Try symbolic link first (works on Unix; on Windows needs Admin or Developer Mode)
+  try {
+    New-Item -ItemType SymbolicLink -Path $LinkPath -Target $TargetName -Force -ErrorAction Stop | Out-Null
+    Write-Check "Created symlink: $DisplayName -> $TargetName"
+    return $true
+  } catch {
+    # Symbolic link failed — try hard link on Windows
+  }
+
+  # Try hard link (Windows, same volume)
+  if ($script:IsWin) {
+    try {
+      $targetPath = Join-Path (Split-Path $LinkPath -Parent) $TargetName
+      New-Item -ItemType HardLink -Path $LinkPath -Target $targetPath -Force -ErrorAction Stop | Out-Null
+      Write-Check "Created hard link: $DisplayName -> $TargetName"
+      return $true
+    } catch {
+      # Hard link also failed — create a .cmd wrapper as last resort
+    }
+
+    # Last resort: .cmd wrapper that forwards all arguments
+    try {
+      $wrapperContent = '@"%~dp0' + $TargetName + '" %*'
+      Set-Content -Path ($LinkPath -replace '\.exe$', '.cmd') -Value $wrapperContent -Force -ErrorAction Stop
+      Write-Check "Created wrapper: " + (Split-Path ($LinkPath -replace '\.exe$', '.cmd') -Leaf) + " -> $TargetName"
+      return $true
+    } catch {
+      Write-WarnMsg "Could not create link for $DisplayName (may need admin privileges)"
+      return $false
+    }
+  }
+
+  Write-WarnMsg "Could not create link for $DisplayName"
+  return $false
+}
+
+function New-Symlinks {
+  param([string]$BinaryName, [string]$InstallDir, [string]$PlatformKey)
+
+  $ext = if ($PlatformKey.StartsWith("win32")) { ".exe" } else { "" }
+
+  # 1) Always: browser4-cli -> browser4-cli-<platform>
+  $linkName = "browser4-cli$ext"
+  $linkPath = Join-Path $InstallDir $linkName
+
+  if ($DryRun) {
+    Write-Step "[DRY-RUN] Would create link: $linkName -> $BinaryName"
+  } else {
+    New-PlatformLink -LinkPath $linkPath -TargetName $BinaryName -DisplayName $linkName
+  }
+
+  # 2) Only if no conflict: b4 -> browser4-cli-<platform>
+  $shortName = "b4$ext"
+  $shortPath = Join-Path $InstallDir $shortName
+
+  # Check if b4 is already on PATH (conflict with another tool)
+  $existingCmd = Get-Command b4 -ErrorAction SilentlyContinue
+  if ($existingCmd) {
+    Write-WarnMsg "Skipping short link '$shortName': 'b4' already found on PATH ($($existingCmd.Source))"
+    return
+  }
+
+  # Check if b4 already exists in the install directory
+  if (Test-Path $shortPath) {
+    Write-WarnMsg "Skipping short link '$shortName': already exists in $InstallDir"
+    return
+  }
+
+  # Also check b4.cmd if on Windows (wrapper fallback)
+  if ($script:IsWin) {
+    $shortCmdPath = Join-Path $InstallDir "b4.cmd"
+    if (Test-Path $shortCmdPath) {
+      Write-WarnMsg "Skipping short link '$shortName': 'b4.cmd' already exists in $InstallDir"
+      return
+    }
+  }
+
+  if ($DryRun) {
+    Write-Step "[DRY-RUN] Would create link: $shortName -> $BinaryName"
+  } else {
+    New-PlatformLink -LinkPath $shortPath -TargetName $BinaryName -DisplayName $shortName
+  }
+}
+
+# ──────────────────────────────────────────────
+# PATH management
+# ──────────────────────────────────────────────
+
+function Add-DirectoryToUserPath {
+  param([string]$Dir)
+
+  $dirResolved = (Resolve-Path $Dir -ErrorAction SilentlyContinue).Path
+  if (-not $dirResolved) { $dirResolved = $Dir }
+
+  # Read current user PATH
+  $currentUserPath = [System.Environment]::GetEnvironmentVariable("Path", [System.EnvironmentVariableTarget]::User)
+  $paths = if ($currentUserPath) { $currentUserPath -split ";" | Where-Object { $_ } } else { @() }
+
+  # Check if already present
+  $normalized = $paths | ForEach-Object { $rp = Resolve-Path $_ -ErrorAction SilentlyContinue; if ($rp) { $rp.Path } else { $_ } }
+  if ($normalized -contains $dirResolved) {
+    Write-Check "Already in user PATH: $Dir"
+    return
+  }
+
+  if ($DryRun) {
+    Write-Check "[DRY-RUN] Would add to user PATH: $Dir"
+    return
+  }
+
+  $newPath = if ($currentUserPath) { "$currentUserPath;$Dir" } else { $Dir }
+  [System.Environment]::SetEnvironmentVariable("Path", $newPath, [System.EnvironmentVariableTarget]::User)
+  Write-Check "Added to user PATH: $Dir"
+
+  # Also update current session
+  $env:Path = "$env:Path;$Dir"
+}
+
+# ──────────────────────────────────────────────
+# Main
+# ──────────────────────────────────────────────
+
+function Main {
+  Write-Summary "╔════════════════════════════════════════╗" -Color Cyan
+  Write-Summary "║   browser4-cli Installer               ║" -Color Cyan
+  Write-Summary "╚════════════════════════════════════════╝" -Color Cyan
+  Write-Summary ""
+
+  # Detect platform
+  $platformKey = Get-PlatformKey
+  $binaryName = Get-BinaryName -PlatformKey $platformKey
+  Write-Step "Platform:  $platformKey"
+  Write-Step "Binary:    $binaryName"
+
+  # Determine install directory
+  $installDir = if ($InstallDir) { $InstallDir } else { Get-DefaultInstallDir }
+  Write-Step "Install:   $installDir"
+  Write-Summary ""
+
+  if (-not (Test-Path $installDir)) {
+    if (-not $DryRun) {
+      New-Item -ItemType Directory -Path $installDir -Force | Out-Null
+    }
+    Write-Step "Created directory: $installDir"
+  }
+
+  $binaryPath = Join-Path $installDir $binaryName
+
+  # If binary already exists and no version override, skip download
+  if ((Test-Path $binaryPath) -and (-not $Version)) {
+    Write-Check "Binary already installed: $binaryPath"
+  } else {
+    # Build download URLs
+    $urls = Get-DownloadUrls -BinaryName $binaryName -VersionTag $Version
+    if (-not $urls -or $urls.Count -eq 0) {
+      throw "No download URLs configured"
+    }
+
+    $downloaded = $false
+    $tempFile = [System.IO.Path]::GetTempFileName()
+
+    foreach ($entry in $urls) {
+      if (Invoke-Download -Url $entry.Url -OutFile $tempFile -Label $entry.Label) {
+        $downloaded = $true
+        break
+      }
+    }
+
+    if (-not $downloaded) {
+      if (Test-Path $tempFile) { Remove-Item $tempFile -Force }
+      throw @"
+Could not download browser4-cli binary.
+
+Tried:
+$($urls | ForEach-Object { "  - $($_.Label): $($_.Url)" } | Out-String)
+
+Please check:
+  - Network connectivity
+  - The version/tag exists: $Version
+  - For GitHub rate limits, set GITHUB_TOKEN environment variable
+"@
+    }
+
+    # Move from temp to install dir
+    if (-not $DryRun) {
+      if (Test-Path $binaryPath) { Remove-Item $binaryPath -Force }
+      Move-Item $tempFile $binaryPath -Force
+    }
+    Write-Check "Installed: $binaryPath"
+  }
+
+  # On Unix, ensure executable bit
+  if (-not $script:IsWin) {
+    if (-not $DryRun) {
+      try { chmod +x $binaryPath 2>$null } catch { }
+    }
+  }
+
+  # Create symlinks (browser4-cli -> platform binary, b4 if no conflict)
+  Write-Summary ""
+  New-Symlinks -BinaryName $binaryName -InstallDir $installDir -PlatformKey $platformKey
+
+  # Add to PATH
+  if ($AddToPath -and $script:IsWin) {
+    Write-Summary ""
+    Add-DirectoryToUserPath -Dir $installDir
+  } elseif ($AddToPath -and -not $script:IsWin) {
+    Write-Summary ""
+    $shellRc = if (Test-Path "$env:HOME/.zshrc") { "$env:HOME/.zshrc" } elseif (Test-Path "$env:HOME/.bashrc") { "$env:HOME/.bashrc" } elseif (Test-Path "$env:HOME/.bash_profile") { "$env:HOME/.bash_profile" } else { "$env:HOME/.profile" }
+    $pathLine = "export PATH=""$installDir`:`$PATH"""
+    if (-not $DryRun) {
+      if (-not (Select-String -Path $shellRc -Pattern [regex]::Escape($installDir) -ErrorAction SilentlyContinue)) {
+        Add-Content -Path $shellRc -Value ""
+        Add-Content -Path $shellRc -Value "# browser4-cli"
+        Add-Content -Path $shellRc -Value $pathLine
+        Write-Check "Added to PATH in $shellRc"
+      } else {
+        Write-Check "PATH entry already in $shellRc"
+      }
+    } else {
+      Write-Check "[DRY-RUN] Would add to $shellRc"
+    }
+  }
+
+  # Verify
+  Write-Summary ""
+  if (-not $DryRun) {
+    try {
+      $versionOutput = & $binaryPath --version 2>&1
+      Write-Summary "✓ browser4-cli installed successfully" -Color Green
+      Write-Summary "  Version: $versionOutput"
+    } catch {
+      Write-Summary "✓ Binary installed at: $binaryPath" -Color Green
+      Write-WarnMsg "Could not verify --version (this is normal on first install)"
+    }
+  } else {
+    Write-Summary "[DRY-RUN] Installation plan complete" -Color Yellow
+  }
+
+  Write-Summary ""
+  Write-Summary "Run 'browser4-cli --help' to get started." -Color Cyan
+
+  if ($script:IsWin) {
+    Write-Summary "If the command isn't found, restart your terminal or run:"
+    Write-Summary "  `$env:Path = [System.Environment]::GetEnvironmentVariable('Path','User') + ';' + [System.Environment]::GetEnvironmentVariable('Path','Machine')"
+  }
+}
+
+Main

package/scripts/install-browser4-cli.sh

@@ -0,0 +1,483 @@
+#!/usr/bin/env bash
+# install-browser4-cli.sh
+# Download and install the browser4-cli native binary.
+#
+# Detects OS, CPU architecture, and libc variant (glibc / musl), downloads
+# the matching binary from GitHub Releases or Alibaba Cloud OSS, and installs
+# it to a user-local directory.
+#
+# Usage:
+#   curl -fsSL https://.../install-browser4-cli.sh | bash
+#   curl -fsSL https://.../install-browser4-cli.sh | bash -s -- --silent
+#
+#   ./install-browser4-cli.sh [OPTIONS]
+#
+# Options:
+#   --version, -v TAG   Release tag (e.g. "v4.11.0"). Default: latest.
+#   --install-dir, -d DIR  Install directory (default: ~/.local/bin).
+#   --source SRC        Force download source: "github" or "oss".
+#   --no-path            Skip adding install dir to PATH.
+#   --silent, -s         Suppress non-error output.
+#   --dry-run            Print what would be done without doing it.
+#   --help, -h           Show this message.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────
+# Globals
+# ──────────────────────────────────────────────
+
+GITHUB_REPO="platonai/Browser4"
+OSS_BASE="https://browser4.oss-cn-beijing.aliyuncs.com"
+
+VERSION=""
+INSTALL_DIR=""
+SOURCE=""
+ADD_TO_PATH=true
+SILENT=false
+DRY_RUN=false
+
+# ──────────────────────────────────────────────
+# Helpers
+# ──────────────────────────────────────────────
+
+say()    { if [[ "$SILENT" != true ]]; then echo -e "$*"; fi; }
+step()   { say "  → $*"; }
+ok()     { say "    ✓ $*"; }
+warn()   { say "    ⚠ $*" >&2; }
+die()    { echo "ERROR: $*" >&2; exit 1; }
+
+color_cyan='\033[0;36m'
+color_green='\033[0;32m'
+color_yellow='\033[0;33m'
+color_reset='\033[0m'
+
+header() {
+  if [[ "$SILENT" != true ]]; then
+    echo -e "${color_cyan}╔════════════════════════════════════════╗${color_reset}"
+    echo -e "${color_cyan}║   browser4-cli Installer               ║${color_reset}"
+    echo -e "${color_cyan}╚════════════════════════════════════════╝${color_reset}"
+    echo ""
+  fi
+}
+
+usage() {
+  cat <<EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Download and install the browser4-cli native binary.
+
+Options:
+  --version, -v TAG   Release tag (e.g. "v4.11.0"). Default: latest.
+  --install-dir, -d DIR  Install directory (default: ~/.local/bin).
+  --source SRC        Force source: "github" or "oss" (default: try both).
+  --no-path           Skip adding install dir to shell rc file.
+  --silent, -s        Suppress non-error output.
+  --dry-run           Print what would be done without doing it.
+  --help, -h          Show this message.
+
+Examples:
+  $(basename "$0")                          # Install latest to ~/.local/bin
+  $(basename "$0") --version v4.11.0        # Install specific version
+  $(basename "$0") --source oss --silent    # Silent install from Aliyun OSS
+  $(basename "$0") --install-dir /usr/local/bin  # System-wide install (needs sudo)
+EOF
+}
+
+# ──────────────────────────────────────────────
+# Argument parsing
+# ──────────────────────────────────────────────
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --version|-v)
+      shift; [[ -z "${1:-}" ]] && die "--version requires a value"
+      VERSION="$1"; shift ;;
+    --install-dir|-d)
+      shift; [[ -z "${1:-}" ]] && die "--install-dir requires a value"
+      INSTALL_DIR="$1"; shift ;;
+    --source)
+      shift; [[ -z "${1:-}" ]] && die "--source requires a value"
+      if [[ "$1" != "github" && "$1" != "oss" ]]; then
+        die "--source must be 'github' or 'oss'"
+      fi
+      SOURCE="$1"; shift ;;
+    --no-path) ADD_TO_PATH=false; shift ;;
+    --silent|-s) SILENT=true; shift ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) die "Unknown argument: $1 (use --help)";;
+  esac
+done
+
+# ──────────────────────────────────────────────
+# Platform detection
+# ──────────────────────────────────────────────
+
+detect_os() {
+  case "$(uname -s)" in
+    Linux)  echo "linux" ;;
+    Darwin) echo "darwin" ;;
+    MINGW*|MSYS*|CYGWIN*) echo "win32" ;;
+    *) die "Unsupported OS: $(uname -s)" ;;
+  esac
+}
+
+detect_arch() {
+  local arch
+  arch=$(uname -m)
+  case "$arch" in
+    x86_64|amd64) echo "x64" ;;
+    aarch64|arm64) echo "arm64" ;;
+    *) die "Unsupported architecture: $arch" ;;
+  esac
+}
+
+detect_libc() {
+  # Only relevant on Linux
+  if [[ "$(uname -s)" != "Linux" ]]; then
+    echo ""
+    return
+  fi
+
+  # Check for musl
+  if ldd --version 2>&1 | grep -qi musl; then
+    echo "musl"
+  elif [[ -f /lib/ld-musl-x86_64.so.1 ]] || [[ -f /lib/ld-musl-aarch64.so.1 ]]; then
+    echo "musl"
+  else
+    echo ""
+  fi
+}
+
+get_platform_key() {
+  local os arch libc
+  os=$(detect_os)
+  arch=$(detect_arch)
+
+  if [[ "$os" == "linux" ]]; then
+    libc=$(detect_libc)
+    if [[ -n "$libc" ]]; then
+      echo "linux-${libc}-${arch}"
+    else
+      echo "linux-${arch}"
+    fi
+  else
+    echo "${os}-${arch}"
+  fi
+}
+
+get_binary_name() {
+  local platform_key="$1"
+  local ext=""
+  if [[ "$platform_key" == win32-* ]]; then
+    ext=".exe"
+  fi
+  echo "browser4-cli-${platform_key}${ext}"
+}
+
+get_default_install_dir() {
+  local dir="${HOME}/.local/bin"
+  # Prefer existing dir
+  if [[ -d "$dir" ]]; then
+    echo "$dir"
+    return
+  fi
+  # Check if ~/bin exists
+  if [[ -d "${HOME}/bin" ]]; then
+    echo "${HOME}/bin"
+    return
+  fi
+  echo "$dir"
+}
+
+# ──────────────────────────────────────────────
+# Download
+# ──────────────────────────────────────────────
+
+check_commands() {
+  if ! command -v curl >/dev/null 2>&1; then
+    die "'curl' is required but not found. Install curl and retry."
+  fi
+}
+
+get_download_urls() {
+  local binary_name="$1"
+  local version_tag="$2"
+  local urls=()
+
+  if [[ -n "$version_tag" ]]; then
+    local gh_url="https://github.com/${GITHUB_REPO}/releases/download/${version_tag}/${binary_name}"
+    local oss_url="${OSS_BASE}/releases/download/${version_tag}/${binary_name}"
+  else
+    # Use 'latest' redirect for GitHub, 'latest' symlink for OSS
+    local gh_url="https://github.com/${GITHUB_REPO}/releases/latest/download/${binary_name}"
+    local oss_url="${OSS_BASE}/releases/download/latest/${binary_name}"
+  fi
+
+  case "$SOURCE" in
+    github) urls+=("GitHub Releases|${gh_url}") ;;
+    oss)    urls+=("Aliyun OSS|${oss_url}") ;;
+    *)
+      urls+=("GitHub Releases|${gh_url}")
+      urls+=("Aliyun OSS|${oss_url}")
+      ;;
+  esac
+
+  printf '%s\n' "${urls[@]}"
+}
+
+download_file() {
+  local url="$1"
+  local dest="$2"
+  local label="$3"
+
+  step "Trying ${label}..."
+  step "URL: $url"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    ok "[DRY-RUN] Would download to: $dest"
+    return 0
+  fi
+
+  local http_code
+  http_code=$(curl -sSfL -w "%{http_code}" -o "$dest" \
+    ${GITHUB_TOKEN:+-H "Authorization: Bearer $GITHUB_TOKEN"} \
+    "$url" 2>/dev/null) || true
+
+  if [[ "$http_code" == "200" ]] || [[ "$http_code" == "302" ]]; then
+    local size
+    size=$(stat -c%s "$dest" 2>/dev/null || stat -f%z "$dest" 2>/dev/null || echo 0)
+
+    # Sanity check: binary must be > 100 KB
+    if [[ "$size" -gt 102400 ]]; then
+      local size_mb
+      size_mb=$(awk "BEGIN { printf \"%.1f\", $size / 1048576 }")
+      ok "Downloaded ${size_mb} MB"
+      return 0
+    fi
+
+    warn "Downloaded file too small (${size} bytes) — may be an error page"
+    rm -f "$dest"
+    return 1
+  fi
+
+  warn "Failed: HTTP ${http_code}"
+  rm -f "$dest"
+  return 1
+}
+
+# ──────────────────────────────────────────────
+# PATH management
+# ──────────────────────────────────────────────
+
+add_to_shell_rc() {
+  local dir="$1"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    ok "[DRY-RUN] Would add to shell rc: $dir"
+    return
+  fi
+
+  # Pick the best rc file
+  local rc_file=""
+  for candidate in "$HOME/.zshrc" "$HOME/.bashrc" "$HOME/.bash_profile" "$HOME/.profile"; do
+    if [[ -f "$candidate" ]]; then
+      rc_file="$candidate"
+      break
+    fi
+  done
+
+  if [[ -z "$rc_file" ]]; then
+    rc_file="$HOME/.profile"
+  fi
+
+  if grep -qF "$dir" "$rc_file" 2>/dev/null; then
+    ok "PATH entry already in $rc_file"
+    return
+  fi
+
+  {
+    echo ""
+    echo "# browser4-cli"
+    echo "export PATH=\"$dir:\$PATH\""
+  } >> "$rc_file"
+
+  ok "Added to PATH in $rc_file"
+  say "    Reload with: source $rc_file"
+}
+
+# ──────────────────────────────────────────────
+# Symlinks
+# ──────────────────────────────────────────────
+
+create_symlinks() {
+  local binary_name="$1"
+  local install_dir="$2"
+
+  local ext=""
+  if [[ "$binary_name" == *.exe ]]; then
+    ext=".exe"
+  fi
+
+  # 1) Always: browser4-cli -> browser4-cli-<platform>
+  local link_name="browser4-cli${ext}"
+  local link_path="${install_dir}/${link_name}"
+
+  if [[ "$DRY_RUN" == true ]]; then
+    step "[DRY-RUN] Would create symlink: ${link_name} -> ${binary_name}"
+  else
+    ln -sf "$binary_name" "$link_path"
+    ok "Created symlink: ${link_name} -> ${binary_name}"
+  fi
+
+  # 2) Only if no conflict: b4 -> browser4-cli-<platform>
+  local short_name="b4${ext}"
+  local short_path="${install_dir}/${short_name}"
+
+  if command -v b4 >/dev/null 2>&1; then
+    warn "Skipping short link '${short_name}': 'b4' already found on PATH"
+    return
+  fi
+
+  if [[ -e "$short_path" ]] || [[ -L "$short_path" ]]; then
+    warn "Skipping short link '${short_name}': already exists in ${install_dir}"
+    return
+  fi
+
+  if [[ "$DRY_RUN" == true ]]; then
+    step "[DRY-RUN] Would create symlink: ${short_name} -> ${binary_name}"
+  else
+    ln -sf "$binary_name" "$short_path"
+    ok "Created symlink: ${short_name} -> ${binary_name}"
+  fi
+}
+
+# ──────────────────────────────────────────────
+# Main
+# ──────────────────────────────────────────────
+
+main() {
+  check_commands
+  header
+
+  # Detect platform
+  local platform_key binary_name
+  platform_key=$(get_platform_key)
+  binary_name=$(get_binary_name "$platform_key")
+
+  step "Platform:  $platform_key"
+  step "Binary:    $binary_name"
+
+  # Install directory
+  if [[ -z "$INSTALL_DIR" ]]; then
+    INSTALL_DIR=$(get_default_install_dir)
+  fi
+  step "Install:   $INSTALL_DIR"
+  say ""
+
+  # Ensure install directory exists
+  if [[ ! -d "$INSTALL_DIR" ]]; then
+    if [[ "$DRY_RUN" != true ]]; then
+      mkdir -p "$INSTALL_DIR"
+    fi
+    step "Created directory: $INSTALL_DIR"
+  fi
+
+  local binary_path="${INSTALL_DIR}/${binary_name}"
+
+  # Download if needed
+  if [[ -f "$binary_path" ]] && [[ -z "$VERSION" ]]; then
+    ok "Binary already installed: $binary_path"
+  else
+    local urls
+    IFS=$'\n' read -r -d '' -a urls < <(get_download_urls "$binary_name" "$VERSION" && printf '\0')
+
+    if [[ ${#urls[@]} -eq 0 ]]; then
+      die "No download URLs configured"
+    fi
+
+    local downloaded=false
+    local tmpfile
+    tmpfile=$(mktemp)
+
+    # Ensure cleanup
+    cleanup() { rm -f "$tmpfile"; }
+    trap cleanup EXIT
+
+    for entry in "${urls[@]}"; do
+      local label url
+      label="${entry%%|*}"
+      url="${entry#*|}"
+
+      if download_file "$url" "$tmpfile" "$label"; then
+        downloaded=true
+        break
+      fi
+    done
+
+    if [[ "$downloaded" != true ]]; then
+      local tried_msg="Could not download browser4-cli binary."$'\n'$'\n'"Tried:"$'\n'
+      for entry in "${urls[@]}"; do
+        local l="${entry%%|*}" u="${entry#*|}"
+        tried_msg+="  - ${l}: ${u}"$'\n'
+      done
+      tried_msg+=$'\n'"Please check:"$'\n'
+      tried_msg+="  - Network connectivity"$'\n'
+      tried_msg+="  - The version/tag exists: ${VERSION:-latest}"$'\n'
+      tried_msg+="  - For GitHub rate limits, set GITHUB_TOKEN environment variable"
+      die "$tried_msg"
+    fi
+
+    # Move from temp to install dir
+    if [[ "$DRY_RUN" != true ]]; then
+      rm -f "$binary_path"
+      mv "$tmpfile" "$binary_path"
+      chmod +x "$binary_path"
+    fi
+    ok "Installed: $binary_path"
+
+    trap - EXIT
+  fi
+
+  # Ensure executable
+  if [[ "$DRY_RUN" != true ]] && [[ -f "$binary_path" ]]; then
+    chmod +x "$binary_path" 2>/dev/null || true
+  fi
+
+  # Create symlinks (browser4-cli -> platform binary, b4 if no conflict)
+  say ""
+  create_symlinks "$binary_name" "$INSTALL_DIR"
+
+  # Add to PATH
+  if [[ "$ADD_TO_PATH" == true ]]; then
+    say ""
+    add_to_shell_rc "$INSTALL_DIR"
+  fi
+
+  # Verify
+  say ""
+  if [[ "$DRY_RUN" != true ]]; then
+    if version_output=$("$binary_path" --version 2>&1); then
+      echo -e "${color_green}✓ browser4-cli installed successfully${color_reset}"
+      say "  Version: $version_output"
+    else
+      echo -e "${color_green}✓ Binary installed at: $binary_path${color_reset}"
+      warn "Could not verify --version (this is normal on first install)"
+    fi
+  else
+    echo -e "${color_yellow}[DRY-RUN] Installation plan complete${color_reset}"
+  fi
+
+  say ""
+  echo -e "${color_cyan}Run 'browser4-cli --help' to get started.${color_reset}"
+
+  # If ADD_TO_PATH was used, remind about sourcing
+  if [[ "$ADD_TO_PATH" == true ]] && [[ "$DRY_RUN" != true ]]; then
+    say ""
+    say "To use immediately, run:"
+    say "  export PATH=\"$INSTALL_DIR:\$PATH\""
+  fi
+}
+
+main

package/scripts/npm-publish-check.js

@@ -9,6 +9,9 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 export const cliRootDir = join(__dirname, '..');
 const packageJsonPath = join(cliRootDir, 'package.json');
 
+/** The only valid npm package name for the CLI. */
+const EXPECTED_PACKAGE_NAME = 'browser4-cli';
+
 /**
  * Reads browser4-cli package metadata.
  *
@@ -16,6 +19,15 @@ const packageJsonPath = join(cliRootDir, 'package.json');
  */
 export function readPackageMetadata() {
   const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+
+  if (packageJson.name !== EXPECTED_PACKAGE_NAME) {
+    console.error(
+      `ERROR: cli/package.json name is "${packageJson.name}", expected "${EXPECTED_PACKAGE_NAME}". ` +
+      `Refusing to proceed with an unexpected package name.`
+    );
+    process.exit(1);
+  }
+
   return {
     name: packageJson.name,
     version: packageJson.version,

package/scripts/sync-version.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 
 /**
- * Syncs the CLI version from cli/package.json to the Cargo manifest.
+ * Syncs the CLI version from cli/VERSION-CLI to all dependent files.
  *
- * cli/package.json is the single source of truth for the CLI version.  This
+ * cli/VERSION-CLI is the single source of truth for the CLI version.  This
  * allows the backend Maven project and the CLI to be published separately with
  * different versions.  This script:
- *   - Reads the version from cli/package.json
- *   - Strips the Maven-style "-SNAPSHOT" suffix
+ *   - Reads the version from cli/VERSION-CLI
+ *   - Strips any "-SNAPSHOT" suffix (if present)
  *   - Fetches the latest published version from npm and compares it
  *     against the local version, warning when the bump is neither a
  *     patch nor a minor increment.
- *   - Writes the clean semver to cli/browser4-cli/Cargo.toml
+ *   - Writes the version to cli/package.json
+ *   - Writes the version to cli/browser4-cli/Cargo.toml
  *   - Updates Cargo.lock to match
  *
  * Usage:
@@ -126,19 +127,26 @@ function checkVersionBump(published, local) {
 
 const checkOnly = process.argv.includes("--check");
 
-// 1. Read the CLI version from cli/package.json (the source of truth)
-const packageJsonPath = join(cliDir, "package.json");
-const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
-const pkgName = packageJson.name;
-const pkgVersion = packageJson.version;
+// The npm package name (hard-coded — stable across versions)
+const pkgName = "browser4-cli";
 
-if (!pkgVersion) {
-  console.error("ERROR: cli/package.json does not contain a version field.");
+// 1. Read the CLI version from cli/VERSION-CLI (the single source of truth)
+const versionCliPath = join(cliDir, "VERSION-CLI");
+let versionRaw;
+try {
+  versionRaw = readFileSync(versionCliPath, "utf-8").trim();
+} catch {
+  console.error(`ERROR: Cannot read ${versionCliPath}`);
   process.exit(1);
 }
 
-const version = stripSnapshot(pkgVersion);
-if (checkOnly) console.log(`cli/package.json: ${version}`);
+if (!versionRaw) {
+  console.error("ERROR: cli/VERSION-CLI is empty.");
+  process.exit(1);
+}
+
+const version = stripSnapshot(versionRaw);
+if (checkOnly) console.log(`cli/VERSION-CLI: ${version}`);
 
 // 2. Compare against the latest published version on npm
 const publishedVersion = getLatestPublishedVersion(pkgName);
@@ -154,7 +162,34 @@ if (publishedVersion) {
   console.log(`Latest published: (not found — package may not be published yet)`);
 }
 
-// 3. Sync cli/browser4-cli/Cargo.toml
+// ---------------------------------------------------------------------------
+// 3. Sync cli/package.json
+// ---------------------------------------------------------------------------
+const packageJsonPath = join(cliDir, "package.json");
+const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+
+if (!packageJson.version) {
+  console.error("ERROR: cli/package.json does not contain a version field.");
+  process.exit(1);
+}
+
+if (packageJson.version !== version) {
+  if (checkOnly) {
+    console.error(`MISMATCH: ${packageJsonPath} version is "${packageJson.version}", expected "${version}"`);
+    process.exitCode = 1;
+  } else {
+    const oldVersion = packageJson.version;
+    packageJson.version = version;
+    writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + "\n");
+    console.log(`  Updated ${packageJsonPath}: ${oldVersion} -> ${version}`);
+  }
+} else {
+  if (!checkOnly) console.log(`  ${packageJsonPath} already up to date`);
+}
+
+// ---------------------------------------------------------------------------
+// 4. Sync cli/browser4-cli/Cargo.toml
+// ---------------------------------------------------------------------------
 const cargoTomlPath = join(cargoDir, "Cargo.toml");
 let cargoToml = readFileSync(cargoTomlPath, "utf-8");
 const cargoVersionRegex = /^version\s*=\s*"[^"]*"/m;
@@ -179,7 +214,9 @@ if (cargoVersion !== version) {
   if (!checkOnly) console.log(`  ${cargoTomlPath} already up to date`);
 }
 
-// 4. Update Cargo.lock (only in sync mode)
+// ---------------------------------------------------------------------------
+// 5. Update Cargo.lock (only in sync mode)
+// ---------------------------------------------------------------------------
 if (!checkOnly && cargoVersion !== version) {
   let lockUpdated = false;
   try {
@@ -228,12 +265,12 @@ if (!checkOnly && cargoVersion !== version) {
   }
 }
 
-// 5. Report
+// 6. Report
 if (checkOnly) {
   if (process.exitCode === 1) {
     console.error("\nVersion mismatch detected! Run 'node cli/scripts/sync-version.js' to fix.");
   } else {
-    console.log(`\nAll versions in sync: ${version}`);
+    console.log(`\nAll versions in sync with cli/VERSION-CLI: ${version}`);
   }
 } else {
   console.log(`\nVersion sync complete: ${pkgName}@${version}`);