browser4-cli 0.1.11 → 0.1.13

package/README.md

@@ -37,6 +37,28 @@ 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
 
 ```bash
@@ -242,7 +264,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
 ```

package/package.json

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

package/scripts/install-browser4-cli.ps1

@@ -0,0 +1,379 @@
+<#
+.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
+  }
+}
+
+# ──────────────────────────────────────────────
+# 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 { }
+    }
+  }
+
+  # 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,433 @@
+#!/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"
+}
+
+# ──────────────────────────────────────────────
+# 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
+
+  # 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/sync-version.js

@@ -181,12 +181,14 @@ if (cargoVersion !== version) {
 
 // 4. Update Cargo.lock (only in sync mode)
 if (!checkOnly && cargoVersion !== version) {
+  let lockUpdated = false;
   try {
     execSync("cargo update -p browser4-cli --offline", {
       cwd: cargoDir,
       stdio: "pipe",
     });
     console.log("  Updated Cargo.lock");
+    lockUpdated = true;
   } catch {
     try {
       execSync("cargo update -p browser4-cli", {
@@ -194,8 +196,34 @@ if (!checkOnly && cargoVersion !== version) {
         stdio: "pipe",
       });
       console.log("  Updated Cargo.lock");
+      lockUpdated = true;
     } catch (e) {
-      console.error(`  Warning: Could not update Cargo.lock: ${e.message}`);
+      console.error(`  Warning: Could not update Cargo.lock via cargo: ${e.message}`);
+    }
+  }
+
+  // Fallback: edit Cargo.lock directly when cargo update fails (e.g. due to
+  // lock file version mismatch between the installed cargo and the lock file).
+  if (!lockUpdated) {
+    const cargoLockPath = join(cargoDir, "Cargo.lock");
+    try {
+      let lockContent = readFileSync(cargoLockPath, "utf-8");
+      // Match the [[package]] block for browser4-cli and replace its version.
+      // Works for both v3 and v4 lock file formats.
+      const lockPkgRegex = new RegExp(
+        `(\\[\\[package\\]\\][\\r\\n]+\\s*name\\s*=\\s*"browser4-cli"[\\r\\n]+\\s*version\\s*=\\s*)"[^"]*"`,
+        "m"
+      );
+      if (lockPkgRegex.test(lockContent)) {
+        lockContent = lockContent.replace(lockPkgRegex, `$1"${version}"`);
+        writeFileSync(cargoLockPath, lockContent);
+        console.log(`  Updated Cargo.lock directly: ${cargoVersion} -> ${version}`);
+        lockUpdated = true;
+      } else {
+        console.error("  Warning: Could not find browser4-cli entry in Cargo.lock");
+      }
+    } catch (e2) {
+      console.error(`  Warning: Could not update Cargo.lock directly: ${e2.message}`);
     }
   }
 }