browser4-cli 4.13.7 → 4.13.8

package/README.md

@@ -144,18 +144,19 @@ npm install -g browser4-cli
 browser4-cli install
 ```
 
-Or bootstrap the native binary directly with a single command:
+Or bootstrap the native binary directly with a single command. The scripts
+also install the Browser4 backend (runtime bundle) afterwards — running
+`browser4-cli install` on a fresh machine, or `browser4-cli upgrade` when a
+backend is already present (pass `--skip-backend` to skip this step):
 
 **Windows (PowerShell):**
 ```powershell
 irm https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.ps1 | iex
-browser4-cli install
 ```
 
 **Linux / macOS (bash):**
 ```bash
 curl -fsSL https://browser4.oss-cn-beijing.aliyuncs.com/scripts/install-browser4-cli.sh | bash
-browser4-cli install
 ```
 
 ## 💡 CLI Guide for Humans

package/package.json

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

package/scripts/README.md

@@ -32,6 +32,8 @@ Options: `--skip-docker-build`, `--dry-run`.
 
 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.
 
+After the CLI binary is in place, both scripts install the Browser4 backend (runtime bundle) using the freshly installed CLI: `browser4-cli install` on a fresh machine, or `browser4-cli upgrade` when a backend is already present (upgrades to the latest version). Pass `--skip-backend` / `-SkipBackend` to install the CLI only. When `--version TAG` is given, the backend is installed/upgraded with the matching `--tag TAG`.
+
 ### Common options
 
 | Option | Description |
@@ -44,6 +46,7 @@ Both scripts auto-detect OS, CPU architecture, and libc variant (glibc vs musl o
 | `--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. |
+| `--skip-backend` / `-SkipBackend` | Skip installing/upgrading the Browser4 backend. |
 | `--force` / `-Force` (pwsh) | Force reinstallation even if the binary already exists at the target path. |
 | `--locate` / `-Locate` | Print detection results (OS, arch, locale) and exit (no install). |
 

package/scripts/install-browser4-cli.ps1

@@ -52,6 +52,12 @@
   Force reinstallation even if the binary is already installed at the target path.
   Overrides -SkipIfInstalled and bypasses locked-file workarounds.
 
+.PARAMETER SkipBackend
+  Skip installing/upgrading the Browser4 backend (runtime bundle).
+  By default, after the CLI binary is in place the script runs
+  `browser4-cli install` (or `browser4-cli upgrade` when a backend is
+  already installed).
+
 .PARAMETER Locate
   Print detection results (OS, architecture, script location, China locale)
   and exit without installing. Useful for diagnostics.
@@ -103,6 +109,7 @@ param(
     [switch]$SkipIfInstalled,
     [switch]$SkipLocal,
     [switch]$Force,
+    [switch]$SkipBackend,
     [switch]$Locate
 )
 
@@ -604,6 +611,89 @@ function Add-DirectoryToUserPath {
     $env:Path = "$env:Path;$Dir"
 }
 
+# ----------------------------------------------
+# Backend (runtime bundle) install / upgrade
+# ----------------------------------------------
+
+<#
+.SYNOPSIS
+  Decide which backend command to run based on `browser4-cli status` output.
+  Returns "install" when no runtime bundle is installed, otherwise "upgrade".
+#>
+function Get-BackendAction {
+    param([string]$StatusOutput)
+    if ($StatusOutput -match 'Installed bundle: not installed') {
+        return "install"
+    }
+    return "upgrade"
+}
+
+<#
+.SYNOPSIS
+  Install or upgrade the Browser4 backend (runtime bundle) with the CLI
+  binary that was just installed:
+    - no backend installed yet -> browser4-cli install
+    - backend already present  -> browser4-cli upgrade (to the latest)
+  Passes -Version through as --tag so the backend matches the CLI version.
+  Non-fatal: failures print guidance and leave the CLI usable.
+#>
+function Install-Backend {
+    param([string]$CliPath, [string]$Tag)
+
+    if ($SkipBackend) {
+        Write-Step "Skipping backend install/upgrade (-SkipBackend)"
+        return
+    }
+
+    Write-Step "Checking for an existing Browser4 backend..."
+
+    $statusOutput = ""
+    try {
+        $statusOutput = (& $CliPath status 2>&1 | Out-String)
+    } catch {
+        # Binary missing or not runnable yet (e.g. --dry-run) -- fall through.
+        $statusOutput = ""
+    }
+
+    $action = Get-BackendAction -StatusOutput $statusOutput
+
+    $backendArgs = @($action)
+    if ($Tag) { $backendArgs += @('--tag', $Tag) }
+
+    if ($action -eq 'install') {
+        Write-Step "No backend installed -- running 'browser4-cli install'..."
+    } else {
+        Write-Step "Backend already installed -- running 'browser4-cli upgrade'..."
+    }
+
+    if ($DryRun) {
+        Write-Check "[DRY-RUN] Would run: $CliPath $($backendArgs -join ' ')"
+        return
+    }
+
+    if ($Silent) {
+        $backendOutput = ""
+        try {
+            $backendOutput = (& $CliPath @backendArgs 2>&1 | Out-String)
+        } catch {
+            $backendOutput = $_.Exception.Message
+        }
+        if ($LASTEXITCODE -eq 0) {
+            Write-Check "Backend $action succeeded ($($backendArgs -join ' '))."
+        } else {
+            Write-WarnMsg "Backend $action failed ($($backendArgs -join ' ')). Retry with: browser4-cli $($backendArgs -join ' ')"
+            Write-Host $backendOutput -ForegroundColor Red
+        }
+    } else {
+        & $CliPath @backendArgs
+        if ($LASTEXITCODE -eq 0) {
+            Write-Check "Backend $action succeeded ($($backendArgs -join ' '))."
+        } else {
+            Write-WarnMsg "Backend $action failed ($($backendArgs -join ' ')). Retry with: browser4-cli $($backendArgs -join ' ')"
+        }
+    }
+}
+
 # ----------------------------------------------
 # Main
 # ----------------------------------------------
@@ -800,6 +890,12 @@ Please check:
         Write-Summary "[DRY-RUN] Installation plan complete" -Color Yellow
     }
 
+    # Install / upgrade the Browser4 backend (runtime bundle) using the CLI
+    # binary we just installed.  Fresh machines get `browser4-cli install`;
+    # machines that already have a backend get `browser4-cli upgrade`.
+    Write-Summary ""
+    Install-Backend -CliPath $binaryPath -Tag $Version
+
     Write-Summary ""
     Write-Summary "Run 'browser4-cli --help' to get started." -Color Cyan
 

package/scripts/install-browser4-cli.sh

@@ -4,7 +4,9 @@
 #
 # 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.
+# it to a user-local directory.  After the CLI binary is in place it also
+# installs the Browser4 backend (runtime bundle) via `browser4-cli install`,
+# or upgrades an existing backend via `browser4-cli upgrade`.
 #
 # Usage:
 #   curl -fsSL https://.../install-browser4-cli.sh | bash
@@ -23,6 +25,7 @@
 #   --silent, -s         Suppress non-error output.
 #   --dry-run            Print what would be done without doing it.
 #   --skip-if-installed  Skip download if binary already exists at install path.
+#   --skip-backend       Skip installing/upgrading the Browser4 backend.
 #   --help, -h           Show this message.
 
 set -euo pipefail
@@ -42,6 +45,7 @@ SILENT=false
 DRY_RUN=false
 SKIP_IF_INSTALLED=false
 SKIP_LOCAL=false
+SKIP_BACKEND=false
 LOCATE_MODE=false
 CHINA_DETECTED=false
 SCRIPT_DIR=""
@@ -130,6 +134,7 @@ Options:
   --silent, -s        Suppress non-error output.
   --dry-run           Print what would be done without doing it.
   --skip-if-installed Skip download if binary already exists at install path.
+  --skip-backend      Skip installing/upgrading the Browser4 backend.
   --help, -h          Show this message.
 
 Examples:
@@ -141,6 +146,7 @@ Examples:
   $(basename "$0") --skip-local             # Force download, ignore bundled binary
   $(basename "$0") --source oss             # Force Aliyun OSS (China mainland)
   $(basename "$0") --skip-if-installed      # Skip download if already installed
+  $(basename "$0") --skip-backend           # CLI only, skip backend install/upgrade
 EOF
 }
 
@@ -168,6 +174,7 @@ while [[ $# -gt 0 ]]; do
     --silent|-s) SILENT=true; shift ;;
     --dry-run) DRY_RUN=true; shift ;;
     --skip-if-installed) SKIP_IF_INSTALLED=true; shift ;;
+    --skip-backend) SKIP_BACKEND=true; shift ;;
     --help|-h) usage; exit 0 ;;
     *) die "Unknown argument: $1 (use --help)";;
   esac
@@ -542,6 +549,72 @@ create_symlinks() {
   fi
 }
 
+# ----------------------------------------------
+# Backend (runtime bundle) install / upgrade
+# ----------------------------------------------
+
+# Decide which backend command to run based on `browser4-cli status` output.
+# Echoes "install" when no runtime bundle is installed yet, otherwise
+# "upgrade" (refresh CLI + runtime to the latest version).
+pick_backend_action() {
+  local status_output="$1"
+  if echo "$status_output" | grep -q "Installed bundle: not installed"; then
+    echo "install"
+  else
+    echo "upgrade"
+  fi
+}
+
+# After the CLI binary is in place, install the Browser4 backend:
+#   - no backend installed yet  -> browser4-cli install
+#   - backend already present   -> browser4-cli upgrade (to the latest)
+# A --version tag is passed through as --tag so the backend matches the CLI.
+# Non-fatal: a failed backend step leaves a working CLI behind.
+install_backend() {
+  local cli_path="$1"
+  local tag="$2"
+
+  if [[ "$SKIP_BACKEND" == true ]]; then
+    step "Skipping backend install/upgrade (--skip-backend)"
+    return 0
+  fi
+
+  step "Checking for an existing Browser4 backend..."
+
+  local status_output
+  status_output=$("$cli_path" status 2>&1 || true)
+
+  local action
+  action=$(pick_backend_action "$status_output")
+
+  local args=("$action")
+  if [[ -n "$tag" ]]; then
+    args+=(--tag "$tag")
+  fi
+
+  if [[ "$action" == "install" ]]; then
+    step "No backend installed -- running 'browser4-cli install'..."
+  else
+    step "Backend already installed -- running 'browser4-cli upgrade'..."
+  fi
+
+  if [[ "$DRY_RUN" == true ]]; then
+    ok "[DRY-RUN] Would run: $cli_path ${args[*]}"
+    return 0
+  fi
+
+  local backend_output
+  if backend_output=$("$cli_path" "${args[@]}" 2>&1); then
+    ok "Backend ${action} succeeded (${args[*]})."
+    if [[ "$SILENT" != true ]]; then
+      echo "$backend_output"
+    fi
+  else
+    echo "    [!] Backend ${action} failed (${args[*]}). Retry manually with: browser4-cli ${args[*]}" >&2
+    echo "$backend_output" >&2
+  fi
+}
+
 # ----------------------------------------------
 # Main
 # ----------------------------------------------
@@ -743,6 +816,12 @@ main() {
     echo -e "${color_yellow}[DRY-RUN] Installation plan complete${color_reset}"
   fi
 
+  # Install / upgrade the Browser4 backend (runtime bundle) using the CLI
+  # we just installed.  Fresh machines get `browser4-cli install`; machines
+  # that already have a backend get `browser4-cli upgrade` to the latest.
+  say ""
+  install_backend "$binary_path" "$VERSION"
+
   say ""
   echo -e "${color_cyan}Run 'browser4-cli --help' to get started.${color_reset}"
 

package/scripts/tests/install-browser4-cli.tests.ps1

@@ -102,7 +102,8 @@ $ast = [System.Management.Automation.Language.Parser]::ParseInput($content, [ref
 
 Test "param block defines all expected parameters" {
     $expected = @('Version', 'InstallDir', 'Source', 'AddToPath',
-                  'Silent', 'DryRun', 'SkipIfInstalled', 'SkipLocal', 'Locate')
+                  'Silent', 'DryRun', 'SkipIfInstalled', 'SkipLocal',
+                  'Force', 'SkipBackend', 'Locate')
     # Extract param block text via AST extents
     $paramAst = $ast.ParamBlock
     if (-not $paramAst) { throw "Could not find param block AST" }
@@ -189,6 +190,28 @@ Test "-SkipIfInstalled flag accepted" {
     if ($ec3 -ne 0) { throw "Exit code: $ec3, output: $($r3.Output)" }
 }
 
+Test "-SkipBackend flag accepted" {
+    $ecSkipBackend = 0
+    $rSkipBackend = RunScript -scriptArgs "-SkipBackend -DryRun" -exitCode ([ref]$ecSkipBackend)
+    if ($ecSkipBackend -ne 0) { throw "Exit code: $ecSkipBackend, output: $($rSkipBackend.Output)" }
+}
+
+Test "-DryRun prints backend plan" {
+    $ecPlan = 0
+    $rPlan = RunScript -scriptArgs "-DryRun -AddToPath:`$false" -exitCode ([ref]$ecPlan)
+    if ($rPlan.Output -notmatch 'Would run:') {
+        throw "Expected backend plan ('Would run:') in: $($rPlan.Output.Substring(0, [Math]::Min(800, $rPlan.Output.Length)))"
+    }
+}
+
+Test "-SkipBackend suppresses backend plan" {
+    $ecSkip = 0
+    $rSkip = RunScript -scriptArgs "-SkipBackend -DryRun -AddToPath:`$false" -exitCode ([ref]$ecSkip)
+    if ($rSkip.Output -match 'Would run:') {
+        throw "Expected no backend plan with -SkipBackend, got: $($rSkip.Output.Substring(0, [Math]::Min(800, $rSkip.Output.Length)))"
+    }
+}
+
 Test "-SkipLocal flag accepted" {
     $ec4 = 0; $r4 = RunScript -scriptArgs "-SkipLocal -DryRun" -exitCode ([ref]$ec4)
     if ($ec4 -ne 0) { throw "Exit code: $ec4, output: $($r4.Output)" }
@@ -297,6 +320,21 @@ $sb = [ScriptBlock]::Create($scriptContent)
     Test "Test-LocalBinary returns false for null" {
         if (Test-LocalBinary -Path $null) { throw "Should be false" }
     }
+
+    Test "Get-BackendAction returns install when not installed" {
+        $action = Get-BackendAction -StatusOutput "Installed bundle: not installed (run 'browser4-cli install')"
+        if ($action -ne "install") { throw "Expected 'install', got: $action" }
+    }
+
+    Test "Get-BackendAction returns upgrade when installed" {
+        $action = Get-BackendAction -StatusOutput "Installed bundle: v4.13.0 (at 2026-01-01T00:00:00Z)"
+        if ($action -ne "upgrade") { throw "Expected 'upgrade', got: $action" }
+    }
+
+    Test "Get-BackendAction defaults to upgrade on empty status" {
+        $action = Get-BackendAction -StatusOutput ""
+        if ($action -ne "upgrade") { throw "Expected 'upgrade', got: $action" }
+    }
 }
 
 Write-Host ""

package/scripts/tests/install-browser4-cli.tests.sh

@@ -263,9 +263,22 @@ test "test_local_binary returns error for nonexistent" bash -c "
     ! test_local_binary '/nonexistent/path/binary' 2>/dev/null
 "
 
-echo ""
+test "pick_backend_action returns install when not installed" bash -c "
+    source '$FUNC_TEST_SCRIPT' >/dev/null 2>&1
+    [[ \"\$(pick_backend_action 'Installed bundle: not installed (run browser4-cli install)')\" == 'install' ]]
+"
+
+test "pick_backend_action returns upgrade when installed" bash -c "
+    source '$FUNC_TEST_SCRIPT' >/dev/null 2>&1
+    [[ \"\$(pick_backend_action 'Installed bundle: v4.13.0 (at 2026-01-01T00:00:00Z)')\" == 'upgrade' ]]
+"
 
-# ── --skip-if-installed behavior ───────────────────────
+test "pick_backend_action defaults to upgrade on empty status" bash -c "
+    source '$FUNC_TEST_SCRIPT' >/dev/null 2>&1
+    [[ \"\$(pick_backend_action '')\" == 'upgrade' ]]
+"
+
+echo ""
 
 echo "--- --skip-if-installed ---" | cyan
 
@@ -275,6 +288,32 @@ test "--skip-if-installed flag accepted" bash -c "
 
 echo ""
 
+# ── Backend install/upgrade ────────────────────────────
+
+echo "--- Backend install/upgrade ---" | cyan
+
+test "--help mentions --skip-backend" bash -c "
+    bash '$INSTALL_SCRIPT' --help 2>&1 | grep -q 'skip-backend'
+"
+
+test "--skip-backend flag accepted" bash -c "
+    bash '$INSTALL_SCRIPT' --skip-backend --dry-run 2>&1 | grep -qi 'skip-backend\|DRY-RUN'
+"
+
+test "--dry-run prints backend plan" bash -c "
+    bash '$INSTALL_SCRIPT' --dry-run --no-path 2>&1 | grep -q 'Would run:'
+"
+
+test "--skip-backend suppresses backend plan" bash -c "
+    ! bash '$INSTALL_SCRIPT' --skip-backend --dry-run --no-path 2>&1 | grep -q 'Would run:'
+"
+
+test "--version passes tag to backend plan" bash -c "
+    bash '$INSTALL_SCRIPT' --dry-run --no-path --version v4.11.0 2>&1 | grep -q 'Would run:.*--tag v4\.11\.0'
+"
+
+echo ""
+
 # ── Header UX ──────────────────────────────────────────
 
 echo "--- Header ---" | cyan