browser4-cli 0.1.18 → 0.1.20

package/README.md

@@ -109,10 +109,11 @@ browser4-cli -s=<session> <command> [args] [options]
 
 | Flag               | Description                                    |
 |--------------------|------------------------------------------------|
-| `--help [command]` | Print help (optionally for a specific command) |
-| `--version`        | Print version                                  |
+| `-h`, `--help [command]` | Print help (optionally for a specific command) |
+| `-v`, `--version`  | Print version                                  |
 | `-s=<name>`        | Named session label                            |
 | `--server=<url>`   | Override Browser4 server URL                   |
+| `--proxy=<url>`    | Manual HTTP proxy override for downloads       |
 | `--json`           | Emit machine-parseable JSON to stdout          |
 | `-q`, `--quiet`    | Suppress normal output, only show errors       |
 
@@ -120,6 +121,9 @@ browser4-cli -s=<session> <command> [args] [options]
 single-line JSON envelope (`{"status":"ok","command":"<name>","output":{...}}`).
 Omit `--json` for the default human-readable output.
 
+`--proxy=<url>` sets a manual HTTP proxy used only for downloading the
+Browser4 runtime bundle. It does not affect browser traffic.
+
 `-q` / `--quiet` suppresses all normal stdout output.  Errors and
 progress messages still go to stderr.  Combine with `--json` for
 silent-on-success scripting: `browser4-cli --json -q open`.
@@ -138,20 +142,20 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 
 | Command | Description |
 |---|---|
-| `open [url]` | Open or switch to a browser session. Supports `--headed` (force visible window) and `--headless` (force headless). |
+| `open [url]` | Open or switch to a browser session. Supports `--headed` (force visible window), `--headless` (force headless), `--profile=<path>`, `--profile-mode=<mode>` (temporary / sequential / default), and `--interact-level=<level>` (FASTEST / FAST / DEFAULT). |
 | `close` | Close the active session |
 | `goto <url>` | Navigate to a URL, auto-opening or refreshing the session if needed |
-| `click <ref> [button]` | Click an element |
-| `dblclick <ref> [button]` | Double-click an element |
-| `type <text> [ref]` | Type text into the focused element or an optional target element |
-| `fill <ref> <text>` | Fill text into an editable element |
+| `click <ref> [button]` | Click an element. Supports `--modifiers` (modifier keys to press). |
+| `dblclick <ref> [button]` | Double-click an element. Supports `--modifiers` (modifier keys to press). |
+| `type <text> [ref]` | Type text into the focused element or an optional target element. Supports `--submit` (press Enter after typing). |
+| `fill <ref> <text>` | Fill text into an editable element. Supports `--submit` (press Enter after filling). |
 | `hover <ref>` | Hover over an element |
 | `select <ref> <val>` | Select an option in a dropdown |
 | `upload <ref> <file>` | Upload a file |
 | `check <ref>` | Check a checkbox or radio button |
 | `uncheck <ref>` | Uncheck a checkbox or radio button |
 | `drag <startRef> <endRef>` | Drag and drop between two elements |
-| `snapshot` | Capture accessibility snapshot |
+| `snapshot` | Capture accessibility snapshot. Supports `--filename=<path>` to save snapshot to file. |
 | `eval <expression> [ref]` | Evaluate JavaScript on the page or a target element. Use `--file=<path>` to read the expression from a file. |
 | `get <mode> <selector> [name]` | Extract data from a page element. Modes: `text`, `html`, `box`, `styles`, `property`, `attr`. `name` is required for `property` and `attr`. |
 | `scroll <direction> <pixels>` | Scroll the page. Direction: `up`, `down`, `left`, or `right`. |
@@ -190,7 +194,8 @@ The tables below mirror the commands surfaced by the global `browser4-cli help`
 
 | Command | Description |
 |---|---|
-| `screenshot [ref]` | Take a screenshot (optionally of a specific element) |
+| `screenshot [ref]` | Take a screenshot (optionally of a specific element). Supports `--filename=<path>` and `--full-page` (full scrollable page). |
+| `pdf` | Save the current page as a PDF. Supports `--filename=<path>`. |
 
 #### Tabs
 
@@ -211,7 +216,7 @@ Run `tab-list` first to find each tab's zero-based index. Pass that index to `ta
 | `state-load <path>` | Restore cookies and localStorage from a saved state file |
 | `cookie-list` | List all cookies (optionally filtered by `--domain` / `--path`) |
 | `cookie-get <name>` | Get a cookie by name |
-| `cookie-set <name> <value>` | Set a cookie (optional `--path`, `--domain`) |
+| `cookie-set <name> <value>` | Set a cookie. Supports `--path`, `--domain`, `--expires`, `--httpOnly`, `--secure`, `--sameSite` (Strict / Lax / None). |
 | `cookie-delete <name>` | Delete a cookie by name |
 | `cookie-clear` | Clear all cookies for the current page |
 | `localstorage-list` | List all localStorage entries |
@@ -229,7 +234,7 @@ Run `tab-list` first to find each tab's zero-based index. Pass that index to `ta
 
 | Command | Description |
 |---|---|
-| `list` | List browser sessions |
+| `list` | List browser sessions. Supports `--all` (list sessions across all workspaces). |
 | `close-all` | Close all browser sessions without stopping `Browser4.jar` / the Browser4 backend |
 | `kill-all` | Forcefully stop `Browser4.jar` / the Browser4 backend and kill Browser4 browser processes |
 
@@ -241,6 +246,7 @@ Use `close-all` for session cleanup when you want to keep the current Browser4 s
 |---|---|
 | `install` | Download the Browser4 runtime bundle. Supports `--tag=<version>` to pin a release and `--force` to reinstall even when already present. |
 | `upgrade` | Upgrade the Browser4 runtime bundle to the latest version or a specified `--tag` |
+| `uninstall` | Remove globally installed browser4-cli (npm, cargo) and its runtime data. Supports `-y` / `--yes` (skip confirmation) and `--dry-run` (preview). |
 | `stop` | Kill the Browser4 backend after closing all sessions |
 | `status` | Check whether the Browser4 backend is reachable and healthy |
 
@@ -256,6 +262,17 @@ When a local Browser4 checkout is detected with the `browser4-bundle` module pre
 `install` and `upgrade` auto-build the runtime bundle from source (via Maven) instead
 of downloading.
 
+`uninstall` attempts to remove browser4-cli from npm global packages and cargo
+installs, and deletes the Browser4 runtime data and cache directories. It prompts
+for confirmation unless `-y` / `--yes` is passed. Use `--dry-run` to preview what
+would be removed without making changes. Does not require a running server.
+
+```shell
+browser4-cli uninstall
+browser4-cli uninstall -y
+browser4-cli uninstall --dry-run
+```
+
 ### Advanced commands
 
 These commands are intentionally omitted from the global `browser4-cli help` overview.
@@ -265,7 +282,7 @@ Query `browser4-cli help <command>` for the exact syntax when you need them.
 |---|---|
 | `batch [command...]` | Execute multiple commands in one invocation. Only DOM operations are supported (Core, Navigation, Keyboard, Mouse, Export, Tabs categories). Commands like `open`, `close`, `list`, `agent run`, etc. are not allowed in batch mode. |
 | `console [min-level]` | List console messages |
-| `extract <instruction>` | Extract structured data from the current page |
+| `extract <instruction>` | Extract structured data from the current page. Supports `--schema` (JSON Schema for typed output). |
 | `summarize [instruction]` | Summarize page content using AI |
 | `agent run <task>` | Run an autonomous agent task |
 | `agent status <id>` | Check the status of a running agent task |
@@ -433,6 +450,69 @@ browser4-cli swarm query --sql @query.sql --seed-file=./urls.txt --refresh
 - Prefix the `--sql` value with `@` to read from a file (e.g. `--sql @query.sql`).
 - All commands return a task ID; use `swarm status` / `swarm result` to track progress.
 
+## DOM Snapshot commands (`domsnapshot <subcommand>`)
+
+The `domsnapshot` commands capture and query a **static DOM snapshot** of the
+current page. Unlike the real-time accessibility `snapshot`, a DOM snapshot is
+a full HTML capture that can be queried repeatedly with CSS selectors and X-SQL
+without re-fetching the page.
+
+Use the spaced `domsnapshot <subcommand>` form:
+
+```shell
+browser4-cli domsnapshot
+browser4-cli domsnapshot get text "#productTitle"
+browser4-cli domsnapshot query --sql "SELECT dom_first_text(dom, '#title') AS title FROM dom(dom)"
+browser4-cli domsnapshot export --file=page.html
+```
+
+### Command overview
+
+| Command | Description |
+|---|---|
+| `domsnapshot` | Capture a static DOM snapshot of the current page |
+| `domsnapshot get <field> [selector] [name]` | Extract elements from the static DOM snapshot |
+| `domsnapshot query [url] --sql=<query>` | Run X-SQL against the DOM snapshot via the scrape API |
+| `domsnapshot export [--file=<path>]` | Save full snapshot HTML content to a local file |
+
+### `domsnapshot get` fields
+
+| Field | Description |
+|---|---|
+| `text` | Extract text content from the matched element |
+| `html` | Extract inner HTML from the matched element |
+| `attr` | Extract an attribute value (requires `name`, e.g. `attr "#link" "href"`) |
+
+`selector` defaults to `:root` when omitted. `name` (attribute name) is
+required for the `attr` field.
+
+### `domsnapshot query` with X-SQL
+
+```shell
+# Inline X-SQL:
+browser4-cli domsnapshot query "https://example.com" --sql "
+  SELECT
+    dom_base_uri(dom) AS url,
+    dom_first_text(dom, 'h1') AS title
+  FROM dom(dom);
+"
+
+# From a file:
+browser4-cli domsnapshot query --sql @query.sql
+```
+
+- `--sql` is **required**. Prefix with `@` to read from a file (e.g. `--sql @query.sql`).
+- `url` is optional and defaults to the current session's page URL.
+- These commands do not require an active swarm session.
+
+### Notes
+
+- `domsnapshot` commands are not supported inside `batch` mode.
+- Use `domsnapshot get` for quick element extraction; use `domsnapshot query`
+  with X-SQL for structured multi-element extraction.
+- The DOM snapshot is cached in the backend until the next `domsnapshot`
+  capture or session navigation.
+
 ## Element References
 
 The `snapshot` command returns an accessibility tree where every interactive
@@ -517,12 +597,27 @@ browser4-cli open
 browser4-cli open --headed https://browser4.io
 browser4-cli open --headless https://browser4.io
 
+# Open with a persistent profile
+browser4-cli open --profile=~/.browser4/profiles/work
+
+# Open with a temporary (single-use) profile
+browser4-cli open --profile-mode=temporary https://browser4.io
+
+# Open with interact-level control (FASTEST / FAST / DEFAULT)
+browser4-cli open --interact-level=FAST https://browser4.io
+
 # Navigate to a page — auto-opens a session if none is active
 browser4-cli goto https://browser4.io
 
 # Inspect the page — note the eN labels on interactive nodes
 browser4-cli snapshot
 
+# Capture a static DOM snapshot and extract data
+browser4-cli domsnapshot
+browser4-cli domsnapshot get text "#productTitle"
+browser4-cli domsnapshot get attr "#productTitle" "href"
+browser4-cli domsnapshot export --file=page.html
+
 # Interact using refs from the snapshot
 browser4-cli click e15
 browser4-cli type "Hello World" e15
@@ -537,6 +632,12 @@ browser4-cli keyup Shift
 # Take a screenshot and save it to disk
 browser4-cli screenshot
 
+# Take a full-page screenshot
+browser4-cli screenshot --full-page
+
+# Save the current page as a PDF
+browser4-cli pdf --filename=page.pdf
+
 # Inspect tab indices before switching tabs
 browser4-cli tab-list
 browser4-cli tab-select 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser4-cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Browser automation CLI for AI agents",
   "type": "module",
   "files": [
@@ -14,7 +14,7 @@
     "browser4": "./bin/browser4-cli.js"
   },
   "scripts": {
-    "version:sync": "node scripts/sync-version.js",
+    "version:sync": "node ../bin/version.mjs cli sync",
     "version": "npm run version:sync && git add browser4-cli/Cargo.toml browser4-cli/Cargo.lock",
     "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",

package/scripts/check-version-sync.js

@@ -1,44 +0,0 @@
-#!/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];
-
-const mismatches = [];
-if (packageVersion !== cargoVersion) {
-    mismatches.push(`  browser4-cli/Cargo.toml:              ${cargoVersion}`);
-}
-
-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/sync-version.js

@@ -1,277 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Syncs the CLI version from cli/VERSION-CLI to all dependent files.
- *
- * 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/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 version to cli/package.json
- *   - Writes the version to cli/browser4-cli/Cargo.toml
- *   - Updates Cargo.lock to match
- *
- * Usage:
- *   node cli/scripts/sync-version.js          # sync all files
- *   node cli/scripts/sync-version.js --check  # exit 1 if out of sync (CI lint)
- */
-
-import {execSync} from "child_process";
-import {readFileSync, writeFileSync} from "fs";
-import {dirname, join, resolve} from "path";
-import {fileURLToPath} from "url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const scriptsDir = __dirname;                                // cli/scripts
-const cliDir = resolve(scriptsDir, "..");                    // cli
-const cargoDir = join(cliDir, "browser4-cli");               // cli/browser4-cli
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Strip the "-SNAPSHOT" suffix if present. */
-function stripSnapshot(version) {
-  if (version.endsWith("-SNAPSHOT")) {
-    return version.slice(0, -"-SNAPSHOT".length);
-  }
-  return version;
-}
-
-/**
- * Parse a semver string into { major, minor, patch } integers.
- * Returns null for non-semver strings (e.g. snapshots, prereleases).
- */
-function parseSemver(version) {
-  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
-  if (!m) return null;
-  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
-}
-
-/**
- * Fetch the latest published version of a package from the npm registry.
- * Returns the version string, or null if the package hasn't been published
- * yet or the registry is unreachable.
- */
-function getLatestPublishedVersion(packageName) {
-  try {
-    const raw = execSync(`npm view "${packageName}" version --json`, {
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 10_000,
-    });
-    return JSON.parse(raw.toString().trim());
-  } catch {
-    // Package may not be published yet, or network is unavailable.
-    return null;
-  }
-}
-
-/**
- * Check whether `local` is an expected bump from `published`:
- *   - same version (already published)
- *   - next patch
- *   - next minor
- *
- * Returns { ok: true } or { ok: false, reason: "..." }.
- */
-function checkVersionBump(published, local) {
-  const pub = parseSemver(published);
-  const loc = parseSemver(local);
-
-  if (!pub || !loc) {
-    // Can't compare — pre-release / snapshot versions are fine.
-    return { ok: true };
-  }
-
-  // Same version — already published.
-  if (loc.major === pub.major && loc.minor === pub.minor && loc.patch === pub.patch) {
-    return { ok: true, note: `version ${local} is already published` };
-  }
-
-  // Next patch: X.Y.Z → X.Y.(Z+1)
-  if (loc.major === pub.major && loc.minor === pub.minor && loc.patch === pub.patch + 1) {
-    return { ok: true };
-  }
-
-  // Next minor: X.Y.Z → X.(Y+1).0
-  if (loc.major === pub.major && loc.minor === pub.minor + 1 && loc.patch === 0) {
-    return { ok: true };
-  }
-
-  // Local is behind published.
-  if (
-    loc.major < pub.major ||
-    (loc.major === pub.major && loc.minor < pub.minor) ||
-    (loc.major === pub.major && loc.minor === pub.minor && loc.patch < pub.patch)
-  ) {
-    return {
-      ok: false,
-      reason: `local version ${local} is behind the published version ${published}`,
-    };
-  }
-
-  // Anything else — skipping versions, major bump, etc.
-  return {
-    ok: false,
-    reason: `version bump from ${published} to ${local} is neither a patch nor a minor increment`,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-const checkOnly = process.argv.includes("--check");
-
-// The npm package name (hard-coded — stable across versions)
-const pkgName = "browser4-cli";
-
-// 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);
-}
-
-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);
-if (publishedVersion) {
-  console.log(`Latest published: ${pkgName}@${publishedVersion}`);
-  const bump = checkVersionBump(publishedVersion, version);
-  if (!bump.ok) {
-    console.warn(`\x1b[33mWARNING: ${bump.reason}\x1b[0m`);
-  } else if (bump.note) {
-    console.log(`  (${bump.note})`);
-  }
-} else {
-  console.log(`Latest published: (not found — package may not be published yet)`);
-}
-
-// ---------------------------------------------------------------------------
-// 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;
-const cargoMatch = cargoToml.match(cargoVersionRegex);
-
-if (!cargoMatch) {
-  console.error("ERROR: Could not find version field in Cargo.toml");
-  process.exit(1);
-}
-
-const cargoVersion = cargoMatch[0].match(/"([^"]*)"/)[1];
-if (cargoVersion !== version) {
-  if (checkOnly) {
-    console.error(`MISMATCH: ${cargoTomlPath} version is "${cargoVersion}", expected "${version}"`);
-    process.exitCode = 1;
-  } else {
-    cargoToml = cargoToml.replace(cargoVersionRegex, `version = "${version}"`);
-    writeFileSync(cargoTomlPath, cargoToml);
-    console.log(`  Updated ${cargoTomlPath}: ${cargoVersion} -> ${version}`);
-  }
-} else {
-  if (!checkOnly) console.log(`  ${cargoTomlPath} already up to date`);
-}
-
-// ---------------------------------------------------------------------------
-// 5. 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", {
-        cwd: cargoDir,
-        stdio: "pipe",
-      });
-      console.log("  Updated Cargo.lock");
-      lockUpdated = true;
-    } catch (e) {
-      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}`);
-    }
-  }
-}
-
-// 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 with cli/VERSION-CLI: ${version}`);
-  }
-} else {
-  console.log(`\nVersion sync complete: ${pkgName}@${version}`);
-}