browser4-cli 0.1.3

package/bin/browser4-cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const scriptDir = path.dirname(__filename);
+const exeName = process.platform === "win32" ? "browser4-cli.exe" : "browser4-cli";
+const exePath = path.join(scriptDir, "target", "release", exeName);
+
+if (!fs.existsSync(exePath)) {
+  const scriptName = path.basename(__filename);
+  console.error(`[${scriptName}] ERROR: executable not found: "${exePath}"`);
+  console.error(`[${scriptName}] Run: cargo build --release (in sdks/browser4-cli)`);
+  process.exit(1);
+}
+
+const child = spawn(exePath, process.argv.slice(2), {
+  stdio: "inherit",
+});
+
+child.on("error", (error) => {
+  console.error(`[${path.basename(__filename)}] ERROR: failed to launch executable: ${error.message}`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+
+  process.exit(code === null ? 1 : code);
+});
+

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "browser4-cli",
+  "version": "0.1.3",
+  "description": "Browser automation CLI for AI agents",
+  "type": "module",
+  "files": [
+    "bin",
+    "scripts",
+    "skill-data",
+    "skills"
+  ],
+  "bin": {
+    "browser4": "./bin/browser4-cli.js"
+  },
+  "scripts": {
+    "version:sync": "node scripts/sync-version.js",
+    "version": "npm run version:sync && git add browser4-cli/Cargo.toml",
+    "build:native": "npm run version:sync && cargo build --release --manifest-path browser4-cli/Cargo.toml && node scripts/copy-native.js",
+    "build:linux": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-linux",
+    "build:macos": "npm run version:sync && (cargo build --release --manifest-path browser4-cli/Cargo.toml --target aarch64-apple-darwin & cargo build --release --manifest-path browser4-cli/Cargo.toml --target x86_64-apple-darwin & wait) && cp cli/target/aarch64-apple-darwin/release/browser4 bin/browser4-darwin-arm64 && cp cli/target/x86_64-apple-darwin/release/browser4 bin/browser4-darwin-x64",
+    "build:windows": "npm run version:sync && docker compose -f docker/docker-compose.yml run --rm build-windows",
+    "build:all-platforms": "npm run version:sync && (npm run build:linux & npm run build:windows & wait) && npm run build:macos",
+    "build:docker": "docker build -t browser4-builder -f docker/Dockerfile.build .",
+    "release": "npm run version:sync && npm run build:all-platforms && npm publish",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "keywords": [
+    "browser",
+    "browser4",
+    "automation",
+    "headless",
+    "chrome",
+    "cdp",
+    "cli",
+    "browser4-cli",
+    "agent"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/platonai/Browser4.git"
+  },
+  "bugs": {
+    "url": "https://github.com/platonai/Browser4/issues"
+  },
+  "homepage": "https://browser4.io",
+  "devDependencies": {},
+  "packageManager": "pnpm@10.32.1+sha512.a706938f0e89ac1456b6563eab4edf1d1faf3368d1191fc5c59790e96dc918e4456ab2e67d613de1043d2e8c81f87303e6b40d4ffeca9df15ef1ad567348f2be"
+}

package/scripts/build-all-platforms.ps1

@@ -0,0 +1,104 @@
+[CmdletBinding()]
+param(
+    [string]$ProjectRoot = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path,
+    [string]$ImageName = "browser4-builder",
+    [switch]$SkipDockerBuild,
+    [switch]$DryRun
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$OutputDir = Join-Path $ProjectRoot "bin"
+$CliDir = Join-Path $ProjectRoot "browser4-cli"
+$DockerfilePath = Join-Path $ProjectRoot "docker/Dockerfile.build"
+
+$Targets = @(
+    @{ Target = "x86_64-unknown-linux-gnu"; Output = "browser4-cli-linux-x64" },
+    @{ Target = "aarch64-unknown-linux-gnu"; Output = "browser4-cli-linux-arm64" },
+    @{ Target = "x86_64-pc-windows-gnu"; Output = "browser4-cli-win32-x64.exe" },
+    @{ Target = "x86_64-apple-darwin"; Output = "browser4-cli-darwin-x64" },
+    @{ Target = "aarch64-apple-darwin"; Output = "browser4-cli-darwin-arm64" },
+    @{ Target = "x86_64-unknown-linux-musl"; Output = "browser4-cli-linux-musl-x64" },
+    @{ Target = "aarch64-unknown-linux-musl"; Output = "browser4-cli-linux-musl-arm64" }
+)
+
+function Invoke-DockerCommand {
+    param([string[]]$Args)
+
+    if ($DryRun) {
+        Write-Host ("[DRY-RUN] docker " + ($Args -join " ")) -ForegroundColor DarkYellow
+        return
+    }
+
+    & docker @Args
+    if ($LASTEXITCODE -ne 0) {
+        throw "Docker command failed with exit code $LASTEXITCODE"
+    }
+}
+
+function Build-Target {
+    param(
+        [string]$Target,
+        [string]$OutputName
+    )
+
+    Write-Host "Building for $Target..." -ForegroundColor Yellow
+
+    $containerCmd = "cargo zigbuild --release --target $Target && cp /build/target/$Target/release/browser4-cli* /output/$OutputName && chmod +x /output/$OutputName 2>/dev/null || true"
+
+    Invoke-DockerCommand -Args @(
+        "run", "--rm",
+        "-v", "${CliDir}:/build",
+        "-v", "${OutputDir}:/output",
+        $ImageName,
+        "-c", $containerCmd
+    )
+
+    $artifactPath = Join-Path $OutputDir $OutputName
+    if (-not (Test-Path -Path $artifactPath -PathType Leaf)) {
+        throw "Failed to build $OutputName"
+    }
+
+    $artifactSize = (Get-Item -Path $artifactPath).Length
+    if ($artifactSize -le 0) {
+        throw "Built artifact is empty: $OutputName"
+    }
+
+    Write-Host "Built $OutputName" -ForegroundColor Green
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    throw "Docker CLI not found in PATH. Install Docker Desktop and retry."
+}
+
+Write-Host "Building browser4-cli for all platforms..." -ForegroundColor Yellow
+Write-Host ""
+
+New-Item -ItemType Directory -Force -Path $OutputDir | Out-Null
+
+if (-not $SkipDockerBuild) {
+    Write-Host "Building Docker cross-compilation image..." -ForegroundColor Yellow
+    Invoke-DockerCommand -Args @(
+        "build",
+        "-t", $ImageName,
+        "-f", $DockerfilePath,
+        $ProjectRoot
+    )
+    Write-Host ""
+}
+
+foreach ($entry in $Targets) {
+    Build-Target -Target $entry.Target -OutputName $entry.Output
+}
+
+Write-Host ""
+Write-Host "Build complete" -ForegroundColor Green
+Write-Host "Binaries are in: $OutputDir"
+
+if ($DryRun) {
+    Write-Host "[DRY-RUN] Skipping artifact listing." -ForegroundColor DarkYellow
+}
+else {
+    Get-ChildItem -Path $OutputDir -Filter "browser4-cli-*" | Select-Object Name, Length, LastWriteTime
+}

package/scripts/build-all-platforms.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+set -e
+
+# Build browser4 for all platforms using Docker
+# Usage: ./scripts/build-all-platforms.sh
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+OUTPUT_DIR="$PROJECT_ROOT/bin"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Building browser4 for all platforms...${NC}"
+echo ""
+
+# Ensure output directory exists
+mkdir -p "$OUTPUT_DIR"
+
+# Build the Docker image if needed
+echo -e "${YELLOW}Building Docker cross-compilation image...${NC}"
+docker build -t browser4-builder -f "$PROJECT_ROOT/docker/Dockerfile.build" "$PROJECT_ROOT"
+
+# Function to build for a target
+build_target() {
+    local target=$1
+    local output_name=$2
+
+    echo -e "${YELLOW}Building for ${target}...${NC}"
+
+    docker run --rm \
+        -v "$PROJECT_ROOT/cli:/build" \
+        -v "$OUTPUT_DIR:/output" \
+        browser4-builder \
+        -c "cargo zigbuild --release --target ${target} && cp /build/target/${target}/release/browser4-cli* /output/${output_name} && chmod +x /output/${output_name} 2>/dev/null || true"
+
+    if [ -f "$OUTPUT_DIR/$output_name" ]; then
+        echo -e "${GREEN}✓ Built ${output_name}${NC}"
+    else
+        echo -e "${RED}✗ Failed to build ${output_name}${NC}"
+        return 1
+    fi
+}
+
+# Build for each platform
+# Linux x64
+build_target "x86_64-unknown-linux-gnu" "browser4-cli-linux-x64"
+
+# Linux ARM64
+build_target "aarch64-unknown-linux-gnu" "browser4-cli-linux-arm64"
+
+# Windows x64
+build_target "x86_64-pc-windows-gnu" "browser4-cli-win32-x64.exe"
+
+# macOS x64 (via zig for cross-compilation)
+build_target "x86_64-apple-darwin" "browser4-cli-darwin-x64"
+
+# macOS ARM64 (via zig for cross-compilation)
+build_target "aarch64-apple-darwin" "browser4-cli-darwin-arm64"
+
+# Linux musl x64 (Alpine)
+build_target "x86_64-unknown-linux-musl" "browser4-cli-linux-musl-x64"
+
+# Linux musl ARM64 (Alpine)
+build_target "aarch64-unknown-linux-musl" "browser4-cli-linux-musl-arm64"
+
+echo ""
+echo -e "${GREEN}Build complete!${NC}"
+echo ""
+echo "Binaries are in: $OUTPUT_DIR"
+ls -la "$OUTPUT_DIR"/browser4-cli-*

package/scripts/check-version-sync.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+/**
+ * Verifies that package.json and browser4-cli/Cargo.toml have the same version.
+ * Used in CI to catch version drift.
+ */
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+
+// Read package.json version
+const packageJson = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf-8'));
+const packageVersion = packageJson.version;
+
+// Read Cargo.toml version
+const cargoToml = readFileSync(join(rootDir, 'browser4-cli/Cargo.toml'), 'utf-8');
+const cargoVersionMatch = cargoToml.match(/^version\s*=\s*"([^"]*)"/m);
+
+if (!cargoVersionMatch) {
+  console.error('Could not find version in browser4-cli/Cargo.toml');
+  process.exit(1);
+}
+
+const cargoVersion = cargoVersionMatch[1];
+
+// Read dashboard package.json version
+const dashboardPkg = JSON.parse(readFileSync(join(rootDir, 'packages/dashboard/package.json'), 'utf-8'));
+const dashboardVersion = dashboardPkg.version;
+
+const mismatches = [];
+if (packageVersion !== cargoVersion) {
+  mismatches.push(`  browser4-cli/Cargo.toml:              ${cargoVersion}`);
+}
+if (packageVersion !== dashboardVersion) {
+  mismatches.push(`  packages/dashboard:          ${dashboardVersion}`);
+}
+
+if (mismatches.length > 0) {
+  console.error('Version mismatch detected!');
+  console.error(`  package.json:                ${packageVersion}`);
+  for (const m of mismatches) console.error(m);
+  console.error('');
+  console.error("Run 'pnpm run version:sync' to fix this.");
+  process.exit(1);
+}
+
+console.log(`Versions are in sync: ${packageVersion}`);

package/scripts/copy-native.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+
+/**
+ * Copies the compiled Rust binary to bin/ with platform-specific naming
+ */
+
+import { copyFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { platform, arch } from 'os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+
+const sourceExt = platform() === 'win32' ? '.exe' : '';
+const sourcePath = join(projectRoot, `browser4-cli/target/release/browser4-cli${sourceExt}`);
+const binDir = join(projectRoot, 'bin');
+
+// Determine platform suffix
+const platformKey = `${platform()}-${arch()}`;
+const ext = platform() === 'win32' ? '.exe' : '';
+const targetName = `browser4-cli-${platformKey}${ext}`;
+const targetPath = join(binDir, targetName);
+
+if (!existsSync(sourcePath)) {
+  console.error(`Error: Native binary not found at ${sourcePath}`);
+  console.error('Run "cargo build --release --manifest-path browser4-cli/Cargo.toml" first');
+  process.exit(1);
+}
+
+if (!existsSync(binDir)) {
+  mkdirSync(binDir, { recursive: true });
+}
+
+copyFileSync(sourcePath, targetPath);
+console.log(`✓ Copied native binary to ${targetPath}`);

package/scripts/postinstall.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for browser4
+ *
+ * Downloads the platform-specific native binary if not present.
+ * On global installs, patches npm's bin entry to use the native binary directly:
+ * - Windows: Overwrites .cmd/.ps1 shims
+ * - Mac/Linux: Replaces symlink to point to native binary
+ */
+
+import { existsSync, mkdirSync, chmodSync, createWriteStream, unlinkSync, writeFileSync, symlinkSync, lstatSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { platform, arch } from 'os';
+import { get } from 'https';
+import { execSync } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, '..');
+const binDir = join(projectRoot, 'bin');
+
+// Detect if the system uses musl libc (e.g. Alpine Linux)
+function isMusl() {
+  if (platform() !== 'linux') return false;
+  try {
+    const result = execSync('ldd --version 2>&1 || true', { encoding: 'utf8' });
+    return result.toLowerCase().includes('musl');
+  } catch {
+    return existsSync('/lib/ld-musl-x86_64.so.1') || existsSync('/lib/ld-musl-aarch64.so.1');
+  }
+}
+
+// Platform detection
+const osKey = platform() === 'linux' && isMusl() ? 'linux-musl' : platform();
+const platformKey = `${osKey}-${arch()}`;
+const ext = platform() === 'win32' ? '.exe' : '';
+const binaryName = `browser4-cli-${platformKey}${ext}`;
+const binaryPath = join(binDir, binaryName);
+
+// Package info
+const packageJson = JSON.parse(
+  (await import('fs')).readFileSync(join(projectRoot, 'package.json'), 'utf8')
+);
+const version = packageJson.version;
+
+// GitHub release URL
+const GITHUB_REPO = 'platonai/browser4';
+const DOWNLOAD_URL = `https://github.com/${GITHUB_REPO}/releases/download/v${version}/${binaryName}`;
+
+async function downloadFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const file = createWriteStream(dest);
+
+    const request = (url) => {
+      get(url, (response) => {
+        // Handle redirects
+        if (response.statusCode === 301 || response.statusCode === 302) {
+          request(response.headers.location);
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
+          return;
+        }
+
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close();
+          resolve();
+        });
+      }).on('error', (err) => {
+        unlinkSync(dest);
+        reject(err);
+      });
+    };
+
+    request(url);
+  });
+}
+
+/**
+ * Detect which package manager ran this postinstall and write a marker file
+ * next to the binary so `browser4 upgrade` can use the correct one
+ * without fragile path heuristics or slow subprocess probing.
+ *
+ * npm_config_user_agent is set by npm/pnpm/yarn/bun during lifecycle scripts,
+ * e.g. "pnpm/8.10.0 node/v20.10.0 linux x64"
+ */
+function writeInstallMethod() {
+  const ua = process.env.npm_config_user_agent || '';
+  let method = '';
+  if (ua.startsWith('pnpm/')) method = 'pnpm';
+  else if (ua.startsWith('yarn/')) method = 'yarn';
+  else if (ua.startsWith('bun/')) method = 'bun';
+  else if (ua.startsWith('npm/')) method = 'npm';
+
+  if (method) {
+    try {
+      writeFileSync(join(binDir, '.install-method'), method);
+    } catch {
+      // Non-critical — upgrade will fall back to heuristics
+    }
+  }
+}
+
+async function main() {
+  // Check if binary already exists
+  if (existsSync(binaryPath)) {
+    // Ensure binary is executable (npm doesn't preserve execute bit)
+    if (platform() !== 'win32') {
+      chmodSync(binaryPath, 0o755);
+    }
+    console.log(`✓ Native binary ready: ${binaryName}`);
+
+    writeInstallMethod();
+
+    // On global installs, fix npm's bin entry to use native binary directly
+    await fixGlobalInstallBin();
+
+    showInstallReminder();
+    return;
+  }
+
+  // Ensure bin directory exists
+  if (!existsSync(binDir)) {
+    mkdirSync(binDir, { recursive: true });
+  }
+
+  console.log(`Downloading native binary for ${platformKey}...`);
+  console.log(`URL: ${DOWNLOAD_URL}`);
+
+  try {
+    await downloadFile(DOWNLOAD_URL, binaryPath);
+
+    // Make executable on Unix
+    if (platform() !== 'win32') {
+      chmodSync(binaryPath, 0o755);
+    }
+
+    console.log(`✓ Downloaded native binary: ${binaryName}`);
+  } catch (err) {
+    console.log(`Could not download native binary: ${err.message}`);
+    console.log('');
+    console.log('To build the native binary locally:');
+    console.log('  1. Install Rust: https://rustup.rs');
+    console.log('  2. Run: npm run build:native');
+  }
+
+  writeInstallMethod();
+
+  // On global installs, fix npm's bin entry to use native binary directly
+  // This avoids the /bin/sh error on Windows and provides zero-overhead execution
+  await fixGlobalInstallBin();
+
+  showInstallReminder();
+}
+
+function findSystemChrome() {
+  const os = platform();
+  if (os === 'darwin') {
+    const candidates = [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ];
+    return candidates.find(p => existsSync(p)) || null;
+  }
+  if (os === 'linux') {
+    const names = ['google-chrome', 'google-chrome-stable', 'chromium-browser', 'chromium'];
+    for (const name of names) {
+      try {
+        const result = execSync(`which ${name} 2>/dev/null`, { encoding: 'utf8' }).trim();
+        if (result) return result;
+      } catch {}
+    }
+    return null;
+  }
+  if (os === 'win32') {
+    const candidates = [
+      `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+    ];
+    return candidates.find(p => p && existsSync(p)) || null;
+  }
+  return null;
+}
+
+function showInstallReminder() {
+  const systemChrome = findSystemChrome();
+  if (systemChrome) {
+    console.log('');
+    console.log(`  ✓ System Chrome found: ${systemChrome}`);
+    console.log('    browser4 will use it automatically.');
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  console.log('  ⚠ No Chrome installation detected.');
+  console.log('  If you plan to use a local browser, run:');
+  console.log('');
+  console.log('    browser4 install');
+  if (platform() === 'linux') {
+    console.log('');
+    console.log('  On Linux, include system dependencies with:');
+    console.log('');
+    console.log('    browser4 install --with-deps');
+  }
+  console.log('');
+  console.log('  You can skip this if you use --cdp, --provider, --engine, or --executable-path.');
+  console.log('');
+}
+
+/**
+ * Fix npm's bin entry on global installs to use the native binary directly.
+ * This provides zero-overhead CLI execution for global installs.
+ */
+async function fixGlobalInstallBin() {
+  if (platform() === 'win32') {
+    await fixWindowsShims();
+  } else {
+    await fixUnixSymlink();
+  }
+}
+
+/**
+ * Fix npm symlink on Mac/Linux global installs.
+ * Replace the symlink to the JS wrapper with a symlink to the native binary.
+ */
+async function fixUnixSymlink() {
+  // Get npm's global bin directory (npm prefix -g + /bin)
+  let npmBinDir;
+  try {
+    const prefix = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+    npmBinDir = join(prefix, 'bin');
+  } catch {
+    return; // npm not available
+  }
+
+  const symlinkPath = join(npmBinDir, 'browser4');
+
+  // Check if symlink exists (indicates global install)
+  try {
+    const stat = lstatSync(symlinkPath);
+    if (!stat.isSymbolicLink()) {
+      return; // Not a symlink, don't touch it
+    }
+  } catch {
+    return; // Symlink doesn't exist, not a global install
+  }
+
+  // Replace symlink to point directly to native binary
+  try {
+    unlinkSync(symlinkPath);
+    symlinkSync(binaryPath, symlinkPath);
+    console.log('✓ Optimized: symlink points to native binary (zero overhead)');
+  } catch (err) {
+    // Permission error or other issue - not critical, JS wrapper still works
+    console.log(`⚠ Could not optimize symlink: ${err.message}`);
+    console.log('  CLI will work via Node.js wrapper (slightly slower startup)');
+  }
+}
+
+/**
+ * Fix npm-generated shims on Windows global installs.
+ * npm generates shims that try to run /bin/sh, which doesn't exist on Windows.
+ * We overwrite them to invoke the native .exe directly.
+ */
+async function fixWindowsShims() {
+  let npmBinDir;
+  try {
+    npmBinDir = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+  } catch {
+    return;
+  }
+
+  const cmdShim = join(npmBinDir, 'browser4.cmd');
+  const ps1Shim = join(npmBinDir, 'browser4.ps1');
+
+  // Shims may not exist yet during postinstall (npm creates them after
+  // lifecycle scripts). If missing, fall back: the JS wrapper at
+  // bin/browser4.js handles Windows correctly via child_process.spawn.
+  if (!existsSync(cmdShim)) {
+    return;
+  }
+
+  // Detect architecture so ARM64 Windows is handled correctly
+  const cpuArch = arch() === 'arm64' ? 'arm64' : 'x64';
+  const relativeBinaryPath = `node_modules\\browser4\\bin\\browser4-win32-${cpuArch}.exe`;
+  const absoluteBinaryPath = join(npmBinDir, relativeBinaryPath);
+
+  // Only rewrite shims if the native binary actually exists
+  if (!existsSync(absoluteBinaryPath)) {
+    return;
+  }
+
+  try {
+    const cmdContent = `@ECHO off\r\n"%~dp0${relativeBinaryPath}" %*\r\n`;
+    writeFileSync(cmdShim, cmdContent);
+
+    const ps1Content = `#!/usr/bin/env pwsh\r\n$basedir = Split-Path $MyInvocation.MyCommand.Definition -Parent\r\n& "$basedir\\${relativeBinaryPath}" $args\r\nexit $LASTEXITCODE\r\n`;
+    writeFileSync(ps1Shim, ps1Content);
+
+    console.log('✓ Optimized: shims point to native binary (zero overhead)');
+  } catch (err) {
+    console.log(`⚠ Could not optimize shims: ${err.message}`);
+    console.log('  CLI will work via Node.js wrapper (slightly slower startup)');
+  }
+}
+
+main().catch(console.error);

package/scripts/sync-version.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * Syncs the version from package.json to all other config files.
+ * Run this script before building or releasing.
+ */
+
+import { execSync } from "child_process";
+import { readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, "..");
+const cliDir = join(rootDir, "browser4-cli");
+
+// Read version from package.json (single source of truth)
+const packageJson = JSON.parse(
+  readFileSync(join(rootDir, "package.json"), "utf-8")
+);
+const version = packageJson.version;
+
+console.log(`Syncing version ${version} to all config files...`);
+
+// Update Cargo.toml
+const cargoTomlPath = join(cliDir, "Cargo.toml");
+let cargoToml = readFileSync(cargoTomlPath, "utf-8");
+const cargoVersionRegex = /^version\s*=\s*"[^"]*"/m;
+const newCargoVersion = `version = "${version}"`;
+
+let cargoTomlUpdated = false;
+if (cargoVersionRegex.test(cargoToml)) {
+  const oldMatch = cargoToml.match(cargoVersionRegex)?.[0];
+  if (oldMatch !== newCargoVersion) {
+    cargoToml = cargoToml.replace(cargoVersionRegex, newCargoVersion);
+    writeFileSync(cargoTomlPath, cargoToml);
+    console.log(`  Updated browser4-cli/Cargo.toml: ${oldMatch} -> ${newCargoVersion}`);
+    cargoTomlUpdated = true;
+  } else {
+    console.log(`  cli/Cargo.toml already up to date`);
+  }
+} else {
+  console.error("  Could not find version field in browser4-cli/Cargo.toml");
+  process.exit(1);
+}
+
+// Update Cargo.lock to match Cargo.toml
+if (cargoTomlUpdated) {
+  try {
+    execSync("cargo update -p browser4 --offline", {
+      cwd: cliDir,
+      stdio: "pipe",
+    });
+    console.log(`  Updated cli/Cargo.lock`);
+  } catch {
+    // --offline may fail if package not in cache, try without it
+    try {
+      execSync("cargo update -p browser4", {
+        cwd: cliDir,
+        stdio: "pipe",
+      });
+      console.log(`  Updated cli/Cargo.lock`);
+    } catch (e) {
+      console.error(`  Warning: Could not update Cargo.lock: ${e.message}`);
+    }
+  }
+}
+
+console.log("Version sync complete.");