browser4-cli 0.1.26 → 0.1.27

package/package.json

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

package/scripts/enumerate-help.ps1

@@ -0,0 +1,382 @@
+#!/usr/bin/env pwsh
+<#
+.SYNOPSIS
+    Enumerates every browser4-cli command and subcommand, prints help
+    information, and saves output to categorized files.
+.DESCRIPTION
+    This script discovers all browser4-cli commands (including hidden ones),
+    generates detailed help for each, and organizes the output into:
+      - A top-level help overview
+      - One file per command (with numbered prefixes for ordering)
+      - Prefix group overviews (swarm, agent, htmlsnapshot, crawl, snapshot)
+      - An INDEX.md for easy navigation
+
+    Output is saved to: <repo-root>/cli/help-output/
+.PARAMETER Binary
+    Path to the browser4-cli binary. Defaults to the release build in the
+    workspace: cli/browser4-cli/target/release/browser4-cli.exe
+.PARAMETER OutDir
+    Directory for help output. Defaults to cli/help-output/ under the repo root.
+.EXAMPLE
+    .\enumerate-help.ps1
+    .\enumerate-help.ps1 -Binary "C:\tools\browser4-cli.exe" -OutDir ".\docs\cli-help"
+#>
+
+param(
+    [string]$Binary,
+    [string]$OutDir
+)
+
+$ErrorActionPreference = "Stop"
+
+# ---- Resolve paths ----------------------------------------------------------
+$RepoRoot = Resolve-Path "$PSScriptRoot\..\.."
+
+if (-not $Binary) {
+    $Binary = Join-Path $RepoRoot "cli\browser4-cli\target\release\browser4-cli.exe"
+}
+if (-not $OutDir) {
+    $OutDir = Join-Path $RepoRoot "cli\help-output"
+}
+
+if (-not (Test-Path $Binary)) {
+    Write-Error "browser4-cli binary not found at: $Binary"
+    Write-Host "Build it first: cd cli/browser4-cli && cargo build --release"
+    exit 1
+}
+
+# Ensure output directory exists
+$null = New-Item -ItemType Directory -Force -Path $OutDir
+
+# Normalize binary path for reliable invocation
+$Binary = Resolve-Path $Binary
+
+Write-Host "browser4-cli binary : $Binary"
+Write-Host "Output directory   : $OutDir"
+Write-Host ""
+
+# ---- Helper: invoke the CLI and capture output ------------------------------
+function Invoke-Cli {
+    param([string[]]$Arguments)
+    $psi = [System.Diagnostics.ProcessStartInfo]::new()
+    $psi.FileName = $Binary
+    $psi.Arguments = $Arguments -join ' '
+    $psi.RedirectStandardOutput = $true
+    $psi.RedirectStandardError = $true
+    $psi.UseShellExecute = $false
+    $psi.CreateNoWindow = $true
+    $psi.StandardOutputEncoding = [System.Text.Encoding]::UTF8
+    $psi.StandardErrorEncoding = [System.Text.Encoding]::UTF8
+
+    $proc = [System.Diagnostics.Process]::new()
+    $proc.StartInfo = $psi
+    $null = $proc.Start()
+    $stdout = $proc.StandardOutput.ReadToEnd()
+    $stderr = $proc.StandardError.ReadToEnd()
+    $proc.WaitForExit(10000) | Out-Null
+
+    # Combine: stdout first, then stderr (stderr carries errors / tips)
+    $result = $stdout
+    if ($stderr.Trim().Length -gt 0) {
+        if ($result.Length -gt 0) { $result += "`n" }
+        $result += $stderr
+    }
+    return $result.TrimEnd()
+}
+
+# ---- Command definitions ----------------------------------------------------
+
+# Each entry: @{ Name = "<internal-name>"; HelpArgs = @("<arg1>", ...) }
+#
+# For simple commands (no spaced public form), use:
+#   HelpArgs = @("--help", "<internal-name>")
+#
+# For commands with a spaced public form, use:
+#   HelpArgs = @("<prefix>", "<sub>", "--help")
+# Because `browser4-cli --help agent-run` is rejected; must use
+# `browser4-cli agent run --help` instead.
+
+$Commands = @(
+    # -- Browser sessions --
+    @{ Name = "open";           HelpArgs = @("--help", "open") },
+    @{ Name = "attach";         HelpArgs = @("--help", "attach") },
+    @{ Name = "close";          HelpArgs = @("--help", "close") },
+    @{ Name = "list";           HelpArgs = @("--help", "list") },
+    @{ Name = "close-all";      HelpArgs = @("--help", "close-all") },
+    @{ Name = "kill-all";       HelpArgs = @("--help", "kill-all") },
+    @{ Name = "stop";           HelpArgs = @("--help", "stop") },
+    @{ Name = "status";         HelpArgs = @("--help", "status") },
+    @{ Name = "doctor";         HelpArgs = @("--help", "doctor") },
+
+    # -- Navigation --
+    @{ Name = "goto";           HelpArgs = @("--help", "goto") },
+    @{ Name = "go-back";        HelpArgs = @("--help", "go-back") },
+    @{ Name = "go-forward";     HelpArgs = @("--help", "go-forward") },
+    @{ Name = "reload";         HelpArgs = @("--help", "reload") },
+
+    # -- Keyboard --
+    @{ Name = "press";          HelpArgs = @("--help", "press") },
+    @{ Name = "type";           HelpArgs = @("--help", "type") },
+    @{ Name = "keydown";        HelpArgs = @("--help", "keydown") },
+    @{ Name = "keyup";          HelpArgs = @("--help", "keyup") },
+    @{ Name = "fill";           HelpArgs = @("--help", "fill") },
+
+    # -- Mouse --
+    @{ Name = "click";          HelpArgs = @("--help", "click") },
+    @{ Name = "dblclick";       HelpArgs = @("--help", "dblclick") },
+    @{ Name = "hover";          HelpArgs = @("--help", "hover") },
+    @{ Name = "drag";           HelpArgs = @("--help", "drag") },
+    @{ Name = "mousemove";      HelpArgs = @("--help", "mousemove") },
+    @{ Name = "mousedown";      HelpArgs = @("--help", "mousedown") },
+    @{ Name = "mouseup";        HelpArgs = @("--help", "mouseup") },
+    @{ Name = "mousewheel";     HelpArgs = @("--help", "mousewheel") },
+    @{ Name = "scroll";         HelpArgs = @("--help", "scroll") },
+
+    # -- Core --
+    @{ Name = "snapshot";       HelpArgs = @("--help", "snapshot") },
+    @{ Name = "get";            HelpArgs = @("--help", "get") },
+    @{ Name = "eval";           HelpArgs = @("--help", "eval") },
+    @{ Name = "wait";           HelpArgs = @("--help", "wait") },
+    @{ Name = "select";         HelpArgs = @("--help", "select") },
+    @{ Name = "check";          HelpArgs = @("--help", "check") },
+    @{ Name = "uncheck";        HelpArgs = @("--help", "uncheck") },
+    @{ Name = "dialog-accept";  HelpArgs = @("--help", "dialog-accept") },
+    @{ Name = "dialog-dismiss"; HelpArgs = @("--help", "dialog-dismiss") },
+    @{ Name = "resize";         HelpArgs = @("--help", "resize") },
+    @{ Name = "delete-data";    HelpArgs = @("--help", "delete-data") },
+    @{ Name = "batch";          HelpArgs = @("--help", "batch") },
+    @{ Name = "generate-locator"; HelpArgs = @("--help", "generate-locator") },
+
+    # -- Export --
+    @{ Name = "screenshot";     HelpArgs = @("--help", "screenshot") },
+    @{ Name = "pdf";            HelpArgs = @("--help", "pdf") },
+
+    # -- Tabs --
+    @{ Name = "tab-list";       HelpArgs = @("--help", "tab-list") },
+    @{ Name = "tab-new";        HelpArgs = @("--help", "tab-new") },
+    @{ Name = "tab-close";      HelpArgs = @("--help", "tab-close") },
+    @{ Name = "tab-select";     HelpArgs = @("--help", "tab-select") },
+
+    # -- Storage --
+    @{ Name = "state-save";     HelpArgs = @("--help", "state-save") },
+    @{ Name = "state-load";     HelpArgs = @("--help", "state-load") },
+    @{ Name = "cookie-list";    HelpArgs = @("--help", "cookie-list") },
+    @{ Name = "cookie-get";     HelpArgs = @("--help", "cookie-get") },
+    @{ Name = "cookie-set";     HelpArgs = @("--help", "cookie-set") },
+    @{ Name = "cookie-delete";  HelpArgs = @("--help", "cookie-delete") },
+    @{ Name = "cookie-clear";   HelpArgs = @("--help", "cookie-clear") },
+    @{ Name = "localstorage-list";    HelpArgs = @("--help", "localstorage-list") },
+    @{ Name = "localstorage-get";     HelpArgs = @("--help", "localstorage-get") },
+    @{ Name = "localstorage-set";     HelpArgs = @("--help", "localstorage-set") },
+    @{ Name = "localstorage-delete";  HelpArgs = @("--help", "localstorage-delete") },
+    @{ Name = "localstorage-clear";   HelpArgs = @("--help", "localstorage-clear") },
+    @{ Name = "sessionstorage-list";  HelpArgs = @("--help", "sessionstorage-list") },
+    @{ Name = "sessionstorage-get";   HelpArgs = @("--help", "sessionstorage-get") },
+    @{ Name = "sessionstorage-set";   HelpArgs = @("--help", "sessionstorage-set") },
+    @{ Name = "sessionstorage-delete"; HelpArgs = @("--help", "sessionstorage-delete") },
+    @{ Name = "sessionstorage-clear"; HelpArgs = @("--help", "sessionstorage-clear") },
+
+    # -- Agent (hidden: agent-run, agent-status, agent-result) --
+    @{ Name = "extract";        HelpArgs = @("--help", "extract") },
+    # agent-list is a standalone command, not hidden
+    @{ Name = "agent-list";     HelpArgs = @("--help", "agent-list") },
+
+    # -- Snapshot subcommands (spaced-form: htmlsnapshot *, snapshot grep) --
+    @{ Name = "snapshot-grep";  HelpArgs = @("--help", "snapshot-grep") },
+
+    # -- DOM Snapshot (base command + spaced subcommands) --
+    @{ Name = "htmlsnapshot";    HelpArgs = @("--help", "htmlsnapshot") },
+
+    # -- Crawl --
+    @{ Name = "crawl";          HelpArgs = @("--help", "crawl") },
+
+    # -- Install / Admin --
+    @{ Name = "install";        HelpArgs = @("--help", "install") },
+    @{ Name = "upgrade";        HelpArgs = @("--help", "upgrade") },
+    @{ Name = "uninstall";      HelpArgs = @("--help", "uninstall") },
+    @{ Name = "loop";           HelpArgs = @("--help", "loop") }
+)
+
+# Commands with spaced public forms — the CLI rejects `--help <kebab-name>`
+# for these, so we use `<prefix> <sub> --help` instead.
+$SpacedCommands = @(
+    # Agent subcommands (hidden)
+    @{ Name = "agent-run";      HelpArgs = @("agent", "run", "--help") },
+    @{ Name = "agent-status";   HelpArgs = @("agent", "status", "--help") },
+    @{ Name = "agent-result";   HelpArgs = @("agent", "result", "--help") },
+
+    # Swarm subcommands
+    @{ Name = "swarm-create";   HelpArgs = @("swarm", "create", "--help") },
+    @{ Name = "swarm-submit";   HelpArgs = @("swarm", "submit", "--help") },
+    @{ Name = "swarm-query";    HelpArgs = @("swarm", "query", "--help") },
+    @{ Name = "swarm-status";   HelpArgs = @("swarm", "status", "--help") },
+    @{ Name = "swarm-result";   HelpArgs = @("swarm", "result", "--help") },
+    @{ Name = "swarm-list";     HelpArgs = @("swarm", "list", "--help") },
+
+    # DOM Snapshot subcommands
+    @{ Name = "htmlsnapshot-get";       HelpArgs = @("htmlsnapshot", "get", "--help") },
+    @{ Name = "htmlsnapshot-get-all";   HelpArgs = @("htmlsnapshot", "get", "all", "--help") },
+    @{ Name = "htmlsnapshot-query";     HelpArgs = @("htmlsnapshot", "query", "--help") },
+    @{ Name = "htmlsnapshot-export";    HelpArgs = @("htmlsnapshot", "export", "--help") },
+    @{ Name = "htmlsnapshot-summary";   HelpArgs = @("htmlsnapshot", "summary", "--help") },
+    @{ Name = "htmlsnapshot-grep";      HelpArgs = @("htmlsnapshot", "grep", "--help") },
+    @{ Name = "htmlsnapshot-inspect";   HelpArgs = @("htmlsnapshot", "inspect", "--help") },
+
+    # Crawl subcommand
+    @{ Name = "crawl-list";     HelpArgs = @("crawl", "list", "--help") }
+)
+
+# Hidden commands (not shown in top-level help, but included for completeness)
+$HiddenCommands = @(
+    @{ Name = "upload";         HelpArgs = @("--help", "upload") },
+    @{ Name = "console";        HelpArgs = @("--help", "console") },
+    @{ Name = "summarize";      HelpArgs = @("--help", "summarize") }
+)
+# Note: agent-run, agent-status, agent-result are also hidden but already in $SpacedCommands
+
+# Prefix groups to generate overview pages for
+$PrefixGroups = @(
+    @{ Name = "swarm";       HelpArgs = @("--help", "swarm") },
+    @{ Name = "agent";        HelpArgs = @("--help", "agent") },
+    @{ Name = "htmlsnapshot";  HelpArgs = @("--help", "htmlsnapshot") },
+    @{ Name = "crawl";        HelpArgs = @("--help", "crawl") },
+    @{ Name = "snapshot";     HelpArgs = @("--help", "snapshot") }
+)
+
+# ---- Generate help files ----------------------------------------------------
+
+$allFiles = @()   # Track generated files for the index
+
+# 1. Top-level help
+Write-Host "[1/5] Generating top-level help..."
+$topHelp = Invoke-Cli -Arguments @("--help")
+$topFile = "00-top-level-help.txt"
+$topHelp | Out-File -FilePath (Join-Path $OutDir $topFile) -Encoding utf8
+$allFiles += @{ Path = $topFile; Label = "Top-level help (browser4-cli --help)" }
+Write-Host "       -> $topFile"
+
+# 2. Per-command help (simple commands)
+Write-Host "[2/5] Generating per-command help ($($Commands.Count) simple commands)..."
+$idx = 0
+foreach ($cmd in $Commands) {
+    $idx++
+    $padIdx = $idx.ToString("00")
+    $safeName = $cmd.Name -replace '[<>:"/\\|?*]', '_'
+    $fileName = "$padIdx-$safeName.txt"
+
+    Write-Host "       [$idx/$($Commands.Count)] $($cmd.Name)"
+    $help = Invoke-Cli -Arguments $cmd.HelpArgs
+    $help | Out-File -FilePath (Join-Path $OutDir $fileName) -Encoding utf8
+    $allFiles += @{ Path = $fileName; Label = $cmd.Name }
+}
+
+# 3. Spaced-form command help
+Write-Host "[3/5] Generating spaced-form command help ($($SpacedCommands.Count) commands)..."
+$baseIdx = $idx
+foreach ($cmd in $SpacedCommands) {
+    $idx++
+    $padIdx = $idx.ToString("00")
+    $safeName = $cmd.Name -replace '[<>:"/\\|?*]', '_'
+    $fileName = "$padIdx-$safeName.txt"
+
+    Write-Host "       [$($idx - $baseIdx)/$($SpacedCommands.Count)] $($cmd.Name)"
+    $help = Invoke-Cli -Arguments $cmd.HelpArgs
+    $help | Out-File -FilePath (Join-Path $OutDir $fileName) -Encoding utf8
+    $allFiles += @{ Path = $fileName; Label = $cmd.Name }
+}
+
+# 4. Hidden commands
+Write-Host "[4/5] Generating hidden-command help ($($HiddenCommands.Count) commands)..."
+$baseIdx = $idx
+foreach ($cmd in $HiddenCommands) {
+    $idx++
+    $padIdx = $idx.ToString("00")
+    $safeName = $cmd.Name -replace '[<>:"/\\|?*]', '_'
+    $fileName = "$padIdx-$safeName.txt"
+
+    Write-Host "       [$($idx - $baseIdx)/$($HiddenCommands.Count)] $($cmd.Name) [hidden]"
+    $help = Invoke-Cli -Arguments $cmd.HelpArgs
+    $help | Out-File -FilePath (Join-Path $OutDir $fileName) -Encoding utf8
+    $allFiles += @{ Path = $fileName; Label = "$($cmd.Name) (hidden)" }
+}
+
+# 5. Prefix group overviews
+Write-Host "[5/5] Generating prefix group overviews..."
+foreach ($group in $PrefixGroups) {
+    $safeName = $group.Name
+    $fileName = "prefix-$safeName.txt"
+
+    Write-Host "       prefix: $($group.Name)"
+    # For prefix groups, `--help <prefix>` prints subcommands
+    $help = Invoke-Cli -Arguments $group.HelpArgs
+    $help | Out-File -FilePath (Join-Path $OutDir $fileName) -Encoding utf8
+    $allFiles += @{ Path = $fileName; Label = "Prefix group: $($group.Name)" }
+}
+
+# ---- Generate INDEX.md ------------------------------------------------------
+Write-Host ""
+Write-Host "Generating INDEX.md..."
+
+$indexLines = @(
+    "# browser4-cli Help Reference",
+    "",
+    "Generated: $(Get-Date -Format 'yyyy-MM-dd HH:mm:ss')",
+    "Binary: $Binary",
+    "",
+    "## Overview",
+    "",
+    "This directory contains the complete help output for every browser4-cli",
+    "command and subcommand.",
+    "",
+    "## Files",
+    ""
+)
+
+foreach ($entry in $allFiles) {
+    $indexLines += "- [$($entry.Label)]($($entry.Path))"
+}
+
+$totalCmdCount = $Commands.Count + $SpacedCommands.Count + $HiddenCommands.Count
+$visibleCount = $totalCmdCount - 5  # 5 hidden: upload, console, summarize, agent-run, agent-result
+
+$indexLines += (
+    "",
+    "## Quick Reference",
+    "",
+    "### Global help",
+    '```',
+    "browser4-cli --help",
+    '```',
+    "",
+    "### Per-command help (simple commands)",
+    '```',
+    "browser4-cli --help <command>",
+    '```',
+    "",
+    "### Per-command help (spaced subcommands)",
+    '```',
+    "browser4-cli <prefix> <sub> --help      # e.g. browser4-cli swarm create --help",
+    "browser4-cli help <prefix> <sub>        # equivalent",
+    '```',
+    "",
+    "### Prefix group overview",
+    '```',
+    "browser4-cli --help <prefix>            # e.g. browser4-cli --help swarm",
+    '```',
+    "",
+    "## Command Count",
+    "",
+    "- **Total commands**: $totalCmdCount",
+    "- **Visible commands**: $visibleCount (5 hidden)",
+    "- **Hidden commands**: upload, console, summarize, agent-run, agent-status, agent-result",
+    ""
+)
+
+$indexContent = $indexLines -join "`n"
+$indexPath = Join-Path $OutDir "INDEX.md"
+$indexContent | Out-File -FilePath $indexPath -Encoding utf8
+
+Write-Host "Done! All help files saved to: $OutDir"
+Write-Host "             Total files: $($allFiles.Count + 1) (including INDEX.md)"
+Write-Host ""
+Write-Host "Start here: $(Join-Path $OutDir 'INDEX.md')"

package/scripts/smoke-test-runtime-bundle.sh

@@ -0,0 +1,257 @@
+#!/bin/bash
+# ---------------------------------------------------------------------------
+# smoke-test-runtime-bundle.sh — Minimal CLI smoke test against a runtime bundle
+# ---------------------------------------------------------------------------
+# Usage:
+#   smoke-test-runtime-bundle.sh <cli-binary> <bundle-archive> [test-port] [timeout-secs]
+#
+# This script:
+#   1. Extracts the platform runtime bundle (.tar.gz or .zip)
+#   2. Sets up a local "installed" runtime directory (no network download)
+#   3. Starts a Python HTTP server serving a minimal interactive page
+#   4. Runs CLI commands: open → goto → type → click → close → kill-all
+#   5. Reports pass/fail for each step
+#
+# Designed for CI (GitHub Actions) but also runs on developer machines.
+# ---------------------------------------------------------------------------
+set -euo pipefail
+
+CLI_BINARY="${1:?Usage: $0 <cli-binary> <bundle-archive> [test-port] [timeout-secs]}"
+BUNDLE_ARCHIVE="${2:?}"
+TEST_PORT="${3:-0}"   # 0 = OS picks a free port
+TIMEOUT_SECS="${4:-300}"
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+pass()  { echo -e "${GREEN}[PASS]${NC} $*"; }
+fail()  { echo -e "${RED}[FAIL]${NC} $*"; }
+info()  { echo -e "${YELLOW}[INFO]${NC} $*"; }
+
+cleanup() {
+    if [ -n "${HTTP_PID:-}" ] && kill -0 "$HTTP_PID" 2>/dev/null; then
+        kill "$HTTP_PID" 2>/dev/null || true
+        wait "$HTTP_PID" 2>/dev/null || true
+    fi
+    if [ -n "${TEMP_DIR:-}" ] && [ -d "$TEMP_DIR" ]; then
+        rm -rf "$TEMP_DIR"
+    fi
+}
+trap cleanup EXIT
+
+# Resolve a free TCP port (port 0 not universally supported by Python http.server)
+find_free_port() {
+    python3 -c '
+import socket
+s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+s.bind(("127.0.0.1", 0))
+print(s.getsockname()[1])
+s.close()
+' 2>/dev/null || python -c '
+import socket
+s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+s.bind(("127.0.0.1", 0))
+print(s.getsockname()[1])
+s.close()
+'
+}
+
+# ---------------------------------------------------------------------------
+# validate inputs
+# ---------------------------------------------------------------------------
+if [ ! -f "$CLI_BINARY" ]; then
+    fail "CLI binary not found: $CLI_BINARY"
+    exit 1
+fi
+if [ ! -f "$BUNDLE_ARCHIVE" ]; then
+    fail "Bundle archive not found: $BUNDLE_ARCHIVE"
+    exit 1
+fi
+
+if [ "$TEST_PORT" -eq 0 ]; then
+    TEST_PORT=$(find_free_port)
+fi
+
+# ---------------------------------------------------------------------------
+# step 1: set up installed runtime directory
+# ---------------------------------------------------------------------------
+info "Setting up runtime directory..."
+
+TEMP_DIR=$(mktemp -d)
+RUNTIME_DIR="$TEMP_DIR/runtime-data"
+VERSIONS_DIR="$RUNTIME_DIR/runtime"          # daemon.rs: RUNTIME_VERSIONS_DIR_NAME
+BUNDLE_TAG="v99.99.99-smoke"
+BUNDLE_DIR="$VERSIONS_DIR/$BUNDLE_TAG"       # versioned_install_dir(tag)
+STATE_DIR="$TEMP_DIR/state"
+WORKSPACE_DIR="$TEMP_DIR/workspace"
+SERVER_LOG_DIR="$TEMP_DIR/server-logs"
+
+mkdir -p "$BUNDLE_DIR" "$STATE_DIR" "$WORKSPACE_DIR" "$SERVER_LOG_DIR"
+EXTRACT_DIR="$TEMP_DIR/extract"
+mkdir -p "$EXTRACT_DIR"
+
+# Extract archive (supports both .tar.gz and .zip)
+case "$BUNDLE_ARCHIVE" in
+    *.tar.gz)
+        tar xzf "$BUNDLE_ARCHIVE" -C "$EXTRACT_DIR"
+        ;;
+    *.zip)
+        python3 -c "
+import zipfile, sys
+with zipfile.ZipFile('$BUNDLE_ARCHIVE', 'r') as z:
+    z.extractall('$EXTRACT_DIR')
+" 2>/dev/null || unzip -q "$BUNDLE_ARCHIVE" -d "$EXTRACT_DIR"
+        ;;
+    *)
+        fail "Unsupported archive format: $BUNDLE_ARCHIVE (expected .tar.gz or .zip)"
+        exit 1
+        ;;
+esac
+
+# Find the bundle root (the directory containing runtime-bundle.json)
+BUNDLE_ROOT=$(find "$EXTRACT_DIR" -name 'runtime-bundle.json' -maxdepth 5 | head -1 | xargs dirname 2>/dev/null || true)
+if [ -z "$BUNDLE_ROOT" ] || [ ! -d "$BUNDLE_ROOT" ]; then
+    fail "Could not find runtime-bundle.json in extracted archive"
+    find "$EXTRACT_DIR" -maxdepth 3 -type d | while read -r d; do info "  $d"; done
+    exit 1
+fi
+info "Bundle root: $BUNDLE_ROOT"
+
+# Copy bundle contents into the versioned install directory
+cp -r "$BUNDLE_ROOT"/* "$BUNDLE_DIR/" 2>/dev/null || cp -r "$BUNDLE_ROOT"/. "$BUNDLE_DIR/"
+
+# Write minimal installation metadata (daemon.rs: BROWSER4_INSTALL_METADATA_FILE_NAME)
+cat > "$BUNDLE_DIR/browser4-installation.json" <<META
+{"tag":"$BUNDLE_TAG","asset_name":"smoke-test","download_url":"local","installed_at":"2026-01-01T00:00:00Z"}
+META
+
+# Write current.tag marker (daemon.rs: CURRENT_TAG_FILE_NAME)
+echo "$BUNDLE_TAG" > "$VERSIONS_DIR/current.tag"
+
+# On Unix, make the bundled java executable
+if [ -f "$BUNDLE_DIR/runtime/bin/java" ]; then
+    chmod +x "$BUNDLE_DIR/runtime/bin/java" 2>/dev/null || true
+fi
+
+info "Runtime directory: $RUNTIME_DIR"
+info "Bundle version dir: $BUNDLE_DIR"
+
+# ---------------------------------------------------------------------------
+# step 2: start test page server
+# ---------------------------------------------------------------------------
+info "Starting test HTTP server on port $TEST_PORT..."
+
+TEST_PAGE="$TEMP_DIR/test.html"
+cat > "$TEST_PAGE" <<'HTML'
+<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>Smoke Test</title></head><body>
+<h1>Browser4 Smoke Test</h1>
+<input id="input1" type="text" value="">
+<button id="btn1" onclick="document.getElementById('input1').value='clicked'">Click Me</button>
+</body></html>
+HTML
+
+python3 -m http.server "$TEST_PORT" --bind 127.0.0.1 > /dev/null 2>&1 &
+HTTP_PID=$!
+TEST_URL="http://127.0.0.1:$TEST_PORT/test.html"
+
+# Wait for HTTP server to be ready
+for i in $(seq 1 10); do
+    if curl -s -o /dev/null "$TEST_URL" 2>/dev/null; then
+        break
+    fi
+    sleep 0.5
+done
+
+# ---------------------------------------------------------------------------
+# step 3: determine server URL (let CLI auto-start the server)
+# ---------------------------------------------------------------------------
+# The CLI auto-starts the Browser4 server on the first command that needs it.
+# We DON'T pass --server so the CLI manages the server lifecycle itself.
+# This tests the full "CLI starts jlink JRE server" code path.
+
+SERVER_PORT=$(find_free_port)
+SERVER_URL="http://127.0.0.1:$SERVER_PORT"
+
+run_cli() {
+    # Set env vars that the CLI checks:
+    #   BROWSER4_RUNTIME_DIR  → where the installed runtime lives
+    #   BROWSER4_CLI_STATE_DIR → where CLI session state is persisted
+    #   BROWSER4_SERVER_LOG_DIR → where server startup logs go
+    BROWSER4_CLI_STATE_DIR="$STATE_DIR" \
+    BROWSER4_RUNTIME_DIR="$RUNTIME_DIR" \
+    BROWSER4_SERVER_LOG_DIR="$SERVER_LOG_DIR" \
+    "$CLI_BINARY" --server "$SERVER_URL" "$@"
+}
+
+FAILED_STEPS=0
+TOTAL_STEPS=0
+
+check_step() {
+    local label="$1"
+    shift
+    TOTAL_STEPS=$((TOTAL_STEPS + 1))
+    echo ""
+    info "--- $label ---"
+    if run_cli "$@" 2>&1; then
+        pass "$label"
+    else
+        fail "$label"
+        FAILED_STEPS=$((FAILED_STEPS + 1))
+        # On first failure, dump the server log if available
+        if [ "$FAILED_STEPS" -eq 1 ]; then
+            if [ -d "$SERVER_LOG_DIR" ] && [ -n "$(ls -A "$SERVER_LOG_DIR" 2>/dev/null)" ]; then
+                info "--- server log (last 80 lines) ---"
+                find "$SERVER_LOG_DIR" -type f -name '*.log' -exec tail -80 {} \; 2>/dev/null || true
+            fi
+            # Also check the temp dir for server logs (default location)
+            local default_log_dir="${TMPDIR:-/tmp}/browser4/browser4-cli/tmp/cli"
+            if [ -d "$default_log_dir" ] && [ -n "$(ls -A "$default_log_dir" 2>/dev/null)" ]; then
+                info "--- default server log (last 80 lines) ---"
+                find "$default_log_dir" -type f -name '*.log' -exec tail -80 {} \; 2>/dev/null || true
+            fi
+        fi
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# step 4: run CLI commands
+# ---------------------------------------------------------------------------
+
+# 4a. open — starts the server, opens a browser session, navigates to the page
+check_step "open" open "$TEST_URL" --profile-mode SEQUENTIAL --interact-level FASTEST
+
+# 4b. goto — navigate to the page (should be a no-op or refresh)
+check_step "goto" goto "$TEST_URL"
+
+# 4c. type — fill the input field
+check_step "type" type "hello-smoke" "#input1"
+
+# 4d. click — click the button
+check_step "click" click "#btn1"
+
+# 4e. close — close the active session
+check_step "close" close
+
+# 4f. kill-all — stop the server and clean up
+check_step "kill-all" kill-all
+
+# ---------------------------------------------------------------------------
+# step 5: report
+# ---------------------------------------------------------------------------
+echo ""
+echo "========================================"
+if [ "$FAILED_STEPS" -eq 0 ]; then
+    pass "SMOKE TEST PASSED ($TOTAL_STEPS/$TOTAL_STEPS steps OK)"
+    exit 0
+else
+    fail "SMOKE TEST FAILED ($FAILED_STEPS/$TOTAL_STEPS steps failed)"
+    info "Server logs at: $SERVER_LOG_DIR"
+    info "Temp directory: $TEMP_DIR"
+    exit 1
+fi