browser4-cli 0.1.13 → 0.1.15

package/README.md

@@ -61,19 +61,42 @@ 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
 
@@ -366,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
@@ -391,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.13",
+  "version": "0.1.15",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [

package/scripts/install-browser4-cli.ps1

@@ -67,9 +67,17 @@ $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"
+# Avoid assigning to $IsLinux / $IsWindows / $IsMacOS directly —
+# they are read-only automatic variables in PowerShell 7+.
+if ($PSVersionTable.PSVersion.Major -ge 6) {
+    $script:OSWin   = $IsWindows
+    $script:OSLinux = $IsLinux
+    $script:OSMac   = $IsMacOS
+} else {
+    $script:OSWin   = [System.Environment]::OSVersion.Platform -eq "Win32NT"
+    $script:OSMac   = $false
+    $script:OSLinux = $false
+}
 
 # ──────────────────────────────────────────────
 # Helpers
@@ -102,13 +110,13 @@ function Write-WarnMsg {
 function Get-PlatformKey {
   $arch = if ([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture -eq [System.Runtime.InteropServices.Architecture]::Arm64) { "arm64" } else { "x64" }
 
-  if ($script:IsWin) {
+  if ($script:OSWin) {
     return "win32-$arch"
   }
-  elseif ($script:IsMac) {
+  elseif ($script:OSMac) {
     return "darwin-$arch"
   }
-  elseif ($script:IsLinux) {
+  elseif ($script:OSLinux) {
     # Detect musl
     $isMusl = $false
     try {
@@ -133,10 +141,10 @@ function Get-BinaryName {
 }
 
 function Get-DefaultInstallDir {
-  if ($script:IsWin) {
+  if ($script:OSWin) {
     return Join-Path $env:LOCALAPPDATA "Programs\browser4-cli"
   }
-  elseif ($script:IsLinux -or $script:IsMac) {
+  elseif ($script:OSLinux -or $script:OSMac) {
     # Prefer ~/.local/bin for user installs
     if (Test-Path "$env:HOME/.local/bin") {
       return "$env:HOME/.local/bin"
@@ -216,6 +224,97 @@ function Invoke-Download {
   }
 }
 
+# ──────────────────────────────────────────────
+# 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:OSWin) {
+    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:OSWin) {
+    $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
 # ──────────────────────────────────────────────
@@ -324,17 +423,21 @@ Please check:
   }
 
   # On Unix, ensure executable bit
-  if (-not $script:IsWin) {
+  if (-not $script:OSWin) {
     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) {
+  if ($AddToPath -and $script:OSWin) {
     Write-Summary ""
     Add-DirectoryToUserPath -Dir $installDir
-  } elseif ($AddToPath -and -not $script:IsWin) {
+  } elseif ($AddToPath -and -not $script:OSWin) {
     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"""
@@ -370,7 +473,7 @@ Please check:
   Write-Summary ""
   Write-Summary "Run 'browser4-cli --help' to get started." -Color Cyan
 
-  if ($script:IsWin) {
+  if ($script:OSWin) {
     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')"
   }

package/scripts/install-browser4-cli.sh

@@ -307,6 +307,52 @@ add_to_shell_rc() {
   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
 # ──────────────────────────────────────────────
@@ -399,6 +445,10 @@ main() {
     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 ""

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}`);