browser-control-and-automation-cli 0.1.1.dev3__py3-none-any.whl

browser_cli/browser/session.py

@@ -0,0 +1,158 @@
+"""Playwright-backed browser session wrapper."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+from browser_cli.browser.models import BrowserLaunchConfig
+from browser_cli.browser.snapshot import capture_snapshot
+from browser_cli.browser.stealth import (
+    build_context_options,
+    build_ignore_default_args,
+    build_init_script,
+    build_launch_args,
+)
+from browser_cli.errors import BrowserUnavailableError, ProfileUnavailableError, TemporaryReadError
+
+
+class BrowserSession:
+    def __init__(self, config: BrowserLaunchConfig) -> None:
+        self._config = config
+        self._playwright: Any | None = None
+        self._context: Any | None = None
+        self._page: Any | None = None
+
+    async def __aenter__(self) -> BrowserSession:
+        await self.start()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    async def start(self) -> None:
+        try:
+            from playwright.async_api import async_playwright
+        except ImportError as exc:  # pragma: no cover - dependency problem
+            raise BrowserUnavailableError(
+                "Playwright is not installed in this repo environment. Run: uv sync --dev"
+            ) from exc
+
+        try:
+            self._playwright = await async_playwright().start()
+            chromium = self._playwright.chromium
+            context_options = build_context_options(
+                viewport_width=self._config.viewport_width,
+                viewport_height=self._config.viewport_height,
+                locale=self._config.locale,
+            )
+            self._context = await chromium.launch_persistent_context(
+                user_data_dir=str(self._config.user_data_dir),
+                executable_path=str(self._config.executable_path)
+                if self._config.executable_path
+                else None,
+                headless=self._config.headless,
+                viewport={
+                    "width": self._config.viewport_width,
+                    "height": self._config.viewport_height,
+                },
+                ignore_default_args=build_ignore_default_args(),
+                args=[
+                    *build_launch_args(
+                        headless=self._config.headless,
+                        viewport_width=self._config.viewport_width,
+                        viewport_height=self._config.viewport_height,
+                        locale=self._config.locale,
+                    ),
+                    f"--profile-directory={self._config.profile_directory}",
+                ],
+                **context_options,
+            )
+            init_script = build_init_script(
+                headless=self._config.headless, locale=self._config.locale
+            )
+            if init_script:
+                await self._context.add_init_script(init_script)
+            self._page = (
+                self._context.pages[0] if self._context.pages else await self._context.new_page()
+            )
+            self._page.set_default_navigation_timeout(self._config.navigation_timeout_ms)
+        except Exception as exc:
+            await self.close()
+            self._raise_launch_error(exc)
+
+    async def close(self) -> None:
+        if self._context is not None:
+            await self._context.close()
+            self._context = None
+        if self._playwright is not None:
+            await self._playwright.stop()
+            self._playwright = None
+        self._page = None
+
+    async def navigate(self, url: str) -> None:
+        self._ensure_started()
+        try:
+            await self._page.goto(
+                url, wait_until="load", timeout=self._config.navigation_timeout_ms
+            )
+        except Exception as exc:
+            raise TemporaryReadError(f"Failed to navigate to {url}: {exc}") from exc
+
+    async def settle(self) -> None:
+        self._ensure_started()
+        await self._page.wait_for_timeout(self._config.settle_timeout_ms)
+
+    async def scroll_to_bottom(self) -> None:
+        self._ensure_started()
+        stable_rounds = 0
+        previous_height = -1
+        for _ in range(8):
+            current_height = await self._page.evaluate(
+                "() => Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)"
+            )
+            await self._page.evaluate(
+                "() => window.scrollTo({ top: document.body.scrollHeight, behavior: 'instant' })"
+            )
+            await self._page.wait_for_timeout(450)
+            next_height = await self._page.evaluate(
+                "() => Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)"
+            )
+            if next_height == current_height == previous_height:
+                stable_rounds += 1
+            else:
+                stable_rounds = 0
+            previous_height = next_height
+            if stable_rounds >= 1:
+                break
+
+    async def capture_html(self) -> str:
+        self._ensure_started()
+        return await self._page.content()
+
+    async def capture_snapshot(self) -> str:
+        self._ensure_started()
+        snapshot = await capture_snapshot(self._page, page_id="read_page")
+        return snapshot.tree
+
+    def _ensure_started(self) -> None:
+        if self._page is None:
+            raise TemporaryReadError("Browser session was not started.")
+
+    def _raise_launch_error(self, exc: Exception) -> None:
+        message = str(exc)
+        lowered = message.lower()
+        if (
+            "singleton" in lowered
+            or "profile" in lowered
+            or "user data directory is already in use" in lowered
+        ):
+            raise ProfileUnavailableError(message) from exc
+        if "executable" in lowered or "browser" in lowered or "failed to launch" in lowered:
+            raise BrowserUnavailableError(message) from exc
+        raise TemporaryReadError(message) from exc

browser_cli/browser/snapshot.py

@@ -0,0 +1,35 @@
+"""Compatibility wrapper around semantic snapshot generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from browser_cli.refs import SemanticSnapshotGenerator
+
+
+@dataclass(slots=True)
+class SnapshotCapture:
+    tree: str
+    refs: dict[str, dict[str, Any]]
+    snapshot_id: str
+
+
+async def capture_snapshot(
+    page: Any,
+    *,
+    page_id: str,
+    interactive: bool = False,
+    full_page: bool = True,
+) -> SnapshotCapture:
+    snapshot = await SemanticSnapshotGenerator().get_snapshot(
+        page,
+        page_id=page_id,
+        interactive=interactive,
+        full_page=full_page,
+    )
+    return SnapshotCapture(
+        tree=snapshot.tree,
+        refs={ref: data.to_summary() for ref, data in snapshot.refs.items()},
+        snapshot_id=snapshot.metadata.snapshot_id,
+    )

browser_cli/browser/stealth.py

@@ -0,0 +1,450 @@
+"""Stealth helpers adapted from bridgic-browser concepts."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+CHROME_DISABLED_COMPONENTS = [
+    "AcceptCHFrame",
+    "AutoExpandDetailsElement",
+    "AvoidUnnecessaryBeforeUnloadCheckSync",
+    "CertificateTransparencyComponentUpdater",
+    "DestroyProfileOnBrowserClose",
+    "DialMediaRouteProvider",
+    "ExtensionManifestV2Disabled",
+    "GlobalMediaControls",
+    "HttpsUpgrades",
+    "ImprovedCookieControls",
+    "LazyFrameLoading",
+    "LensOverlay",
+    "MediaRouter",
+    "PaintHolding",
+    "ThirdPartyStoragePartitioning",
+    "Translate",
+    "AutomationControlled",
+    "BackForwardCache",
+    "OptimizationHints",
+    "ProcessPerSiteUpToMainFrameThreshold",
+    "InterestFeedContentSuggestions",
+    "CalculateNativeWinOcclusion",
+    "HeavyAdPrivacyMitigations",
+    "PrivacySandboxSettings4",
+    "AutofillServerCommunication",
+    "CrashReporting",
+    "OverscrollHistoryNavigation",
+    "InfiniteSessionRestore",
+    "ExtensionDisableUnsupportedDeveloper",
+    "ExtensionManifestV2Unsupported",
+]
+
+CHROME_DISABLED_COMPONENTS_HEADED = [
+    "AutomationControlled",
+    "InfiniteSessionRestore",
+]
+
+CHROME_STEALTH_ARGS = [
+    "--disable-field-trial-config",
+    "--disable-background-networking",
+    "--disable-background-timer-throttling",
+    "--disable-backgrounding-occluded-windows",
+    "--disable-back-forward-cache",
+    "--disable-breakpad",
+    "--disable-client-side-phishing-detection",
+    "--disable-component-extensions-with-background-pages",
+    "--disable-component-update",
+    "--no-default-browser-check",
+    "--disable-hang-monitor",
+    "--disable-ipc-flooding-protection",
+    "--disable-popup-blocking",
+    "--disable-prompt-on-repost",
+    "--disable-renderer-backgrounding",
+    "--metrics-recording-only",
+    "--no-first-run",
+    "--no-service-autorun",
+    "--export-tagged-pdf",
+    "--disable-search-engine-choice-screen",
+    "--unsafely-disable-devtools-self-xss-warnings",
+    "--disable-sync",
+    "--allow-legacy-extension-manifests",
+    "--allow-pre-commit-input",
+    "--disable-blink-features=AutomationControlled",
+    "--log-level=2",
+    "--lang=en-US",
+    "--disable-focus-on-load",
+    "--disable-window-activation",
+    "--generate-pdf-document-outline",
+    "--no-pings",
+    "--disable-infobars",
+    "--hide-crash-restore-bubble",
+    "--disable-domain-reliability",
+    "--disable-datasaver-prompt",
+    "--disable-speech-synthesis-api",
+    "--disable-speech-api",
+    "--disable-print-preview",
+    "--safebrowsing-disable-auto-update",
+    "--disable-external-intent-requests",
+    "--disable-desktop-notifications",
+    "--noerrdialogs",
+    "--silent-debugger-extension-api",
+    "--disable-extensions-http-throttling",
+    "--extensions-on-chrome-urls",
+    "--disable-default-apps",
+]
+
+CHROME_STEALTH_ARGS_HEADED = [
+    "--disable-blink-features=AutomationControlled",
+    "--no-first-run",
+    "--no-default-browser-check",
+    "--disable-infobars",
+    "--hide-crash-restore-bubble",
+    "--no-service-autorun",
+    "--log-level=2",
+    "--disable-search-engine-choice-screen",
+    "--unsafely-disable-devtools-self-xss-warnings",
+    "--disable-popup-blocking",
+]
+
+CHROME_LINUX_ONLY_ARGS = [
+    "--disable-dev-shm-usage",
+    "--ash-no-nudges",
+    "--suppress-message-center-popups",
+]
+
+CHROME_IGNORE_DEFAULT_ARGS = [
+    "--enable-automation",
+    "--hide-scrollbars",
+]
+
+DEFAULT_PERMISSIONS = [
+    "clipboard-read",
+    "clipboard-write",
+    "notifications",
+]
+
+_STEALTH_INIT_SCRIPT_TEMPLATE = r"""
+(function () {
+  const _nativeFns = new WeakSet();
+  const _nativeFnNames = new WeakMap();
+  const _mkNative = (fn, name) => {
+    _nativeFns.add(fn);
+    if (name !== undefined) _nativeFnNames.set(fn, name);
+    return fn;
+  };
+
+  const _origFnToString = Function.prototype.toString;
+  Function.prototype.toString = _mkNative(function toString() {
+    if (_nativeFns.has(this)) {
+      const _n = _nativeFnNames.has(this) ? _nativeFnNames.get(this) : (this.name || '');
+      return `function ${_n}() { [native code] }`;
+    }
+    return _origFnToString.call(this);
+  }, 'toString');
+
+  const _wdDesc = Object.getOwnPropertyDescriptor(Navigator.prototype, 'webdriver');
+  if (_wdDesc) {
+    Object.defineProperty(Navigator.prototype, 'webdriver', {
+      get: _mkNative(function () { return undefined; }, ''),
+      configurable: true,
+    });
+  } else if (navigator.webdriver !== undefined) {
+    Object.defineProperty(navigator, 'webdriver', {
+      get: _mkNative(function () { return undefined; }, ''),
+      configurable: true,
+    });
+  }
+
+  const _makeMime = (type, suffixes, description) =>
+    ({ type, suffixes, description, enabledPlugin: null });
+
+  const _pdfMimes = [
+    _makeMime('application/pdf', 'pdf', 'Portable Document Format'),
+    _makeMime('text/pdf', 'pdf', 'Portable Document Format'),
+  ];
+
+  const _makePlugin = (name, description) => {
+    const p = { name, description, filename: 'internal-pdf-viewer', length: _pdfMimes.length };
+    _pdfMimes.forEach((m, i) => {
+      const localMime = { type: m.type, suffixes: m.suffixes, description: m.description, enabledPlugin: p };
+      Object.defineProperty(p, i, { value: localMime, enumerable: true });
+    });
+    p.item = _mkNative(function item(i) { return p[i] ?? null; }, 'item');
+    p.namedItem = _mkNative(function namedItem(n) {
+      const idx = _pdfMimes.findIndex(m => m.type === n);
+      return idx >= 0 ? p[idx] : null;
+    }, 'namedItem');
+    return p;
+  };
+
+  const _plugins = [
+    _makePlugin('PDF Viewer', 'Portable Document Format'),
+    _makePlugin('Chrome PDF Viewer', 'Portable Document Format'),
+    _makePlugin('Chromium PDF Viewer', 'Portable Document Format'),
+    _makePlugin('Microsoft Edge PDF Viewer', 'Portable Document Format'),
+    _makePlugin('WebKit built-in PDF', 'Portable Document Format'),
+  ];
+
+  _pdfMimes.forEach((m) => { m.enabledPlugin = _plugins[0]; });
+
+  const _pluginList = Object.assign([..._plugins], {
+    item: _mkNative(function item(i) { return _plugins[i] ?? null; }, 'item'),
+    namedItem: _mkNative(function namedItem(n) { return _plugins.find(p => p.name === n) ?? null; }, 'namedItem'),
+    refresh: _mkNative(function refresh() {}, 'refresh'),
+    length: _plugins.length,
+  });
+
+  Object.defineProperty(navigator, 'plugins', {
+    get: _mkNative(function () { return _pluginList; }, ''),
+    configurable: true,
+  });
+
+  const _mimeList = Object.assign([..._pdfMimes], {
+    item: _mkNative(function item(i) { return _pdfMimes[i] ?? null; }, 'item'),
+    namedItem: _mkNative(function namedItem(n) { return _pdfMimes.find(m => m.type === n) ?? null; }, 'namedItem'),
+    length: _pdfMimes.length,
+  });
+
+  Object.defineProperty(navigator, 'mimeTypes', {
+    get: _mkNative(function () { return _mimeList; }, ''),
+    configurable: true,
+  });
+
+  try {
+    Object.defineProperty(navigator, 'languages', {
+      get: _mkNative(function () { return __BROWSER_CLI_LANGS__; }, ''),
+      configurable: true,
+    });
+  } catch (_) {}
+
+  if (!window.chrome || !window.chrome.runtime || !window.chrome.csi || !window.chrome.loadTimes) {
+    const _chrome = {
+      app: {
+        isInstalled: false,
+        getDetails: _mkNative(function getDetails() { return null; }, 'getDetails'),
+        getIsInstalled: _mkNative(function getIsInstalled() { return false; }, 'getIsInstalled'),
+        installState: _mkNative(function installState() { return 'not_installed'; }, 'installState'),
+      },
+      runtime: {
+        connect: _mkNative(function connect() {}, 'connect'),
+        sendMessage: _mkNative(function sendMessage() {}, 'sendMessage'),
+      },
+      csi: _mkNative(function csi() {
+        return {
+          onloadT: Date.now(),
+          pageT: Date.now() - (performance.timeOrigin ?? performance.timing?.navigationStart ?? 0),
+          startE: Date.now() - 1000,
+          tran: 15,
+        };
+      }, 'csi'),
+      loadTimes: _mkNative(function loadTimes() {
+        return {
+          commitLoadTime: Date.now() / 1000 - 1,
+          connectionInfo: 'h2',
+          finishDocumentLoadTime: Date.now() / 1000,
+          finishLoadTime: Date.now() / 1000,
+          firstPaintAfterLoadTime: 0,
+          firstPaintTime: Date.now() / 1000 - 0.5,
+          navigationType: 'Other',
+          npnNegotiatedProtocol: 'h2',
+          requestTime: Date.now() / 1000 - 1,
+          startLoadTime: Date.now() / 1000 - 1,
+          wasAlternateProtocolAvailable: false,
+          wasFetchedViaSpdy: true,
+          wasNpnNegotiated: true,
+        };
+      }, 'loadTimes'),
+    };
+    try {
+      Object.defineProperty(window, 'chrome', {
+        value: _chrome, writable: false, enumerable: true, configurable: false,
+      });
+    } catch (_) { window.chrome = _chrome; }
+  }
+
+  if (navigator.permissions && navigator.permissions.query) {
+    const _origQuery = navigator.permissions.query.bind(navigator.permissions);
+    navigator.permissions.query = _mkNative(function query(params) {
+      if (params && params.name === 'notifications') {
+        return Promise.resolve({ state: Notification.permission === 'denied' ? 'default' : Notification.permission, onchange: null });
+      }
+      return _origQuery(params);
+    }, 'query');
+  }
+
+  if (window.Notification && Notification.permission === 'denied') {
+    try {
+      Object.defineProperty(Notification, 'permission', {
+        get: _mkNative(function () { return 'default'; }, ''),
+        configurable: true,
+      });
+    } catch (_) {}
+  }
+
+  try { document.hasFocus = _mkNative(function hasFocus() { return true; }, 'hasFocus'); } catch (_) {}
+  try { Object.defineProperty(document, 'hidden', { get: _mkNative(function () { return false; }, ''), configurable: true }); } catch (_) {}
+  try { Object.defineProperty(document, 'visibilityState', { get: _mkNative(function () { return 'visible'; }, ''), configurable: true }); } catch (_) {}
+
+  if (window.outerWidth === 0) {
+    try { Object.defineProperty(window, 'outerWidth', { get: _mkNative(function () { return window.innerWidth; }, ''), configurable: true }); } catch (_) {}
+  }
+  if (window.outerHeight === 0) {
+    try { Object.defineProperty(window, 'outerHeight', { get: _mkNative(function () { return window.innerHeight; }, ''), configurable: true }); } catch (_) {}
+  }
+
+  if (navigator.deviceMemory === undefined) {
+    try { Object.defineProperty(navigator, 'deviceMemory', { get: _mkNative(function () { return 8; }, ''), configurable: true }); } catch (_) {}
+  }
+
+  if (!navigator.hardwareConcurrency || navigator.hardwareConcurrency < 2) {
+    try { Object.defineProperty(navigator, 'hardwareConcurrency', { get: _mkNative(function () { return 8; }, ''), configurable: true }); } catch (_) {}
+  }
+
+  if (!navigator.connection) {
+    try {
+      Object.defineProperty(navigator, 'connection', {
+        get: _mkNative(function () { return { effectiveType: '4g', downlink: 10, rtt: 100, saveData: false }; }, ''),
+        configurable: true,
+      });
+    } catch (_) {}
+  }
+
+  (function () {
+    const _patchWebGL = (Ctx) => {
+      if (!Ctx) return;
+      const _orig = Ctx.prototype.getParameter;
+      Ctx.prototype.getParameter = _mkNative(function getParameter(parameter) {
+        const _val = _orig.call(this, parameter);
+        if (parameter === 37445) {
+          if (_val && (_val.includes('Google') || _val === '')) return 'Intel Inc.';
+          return _val;
+        }
+        if (parameter === 37446) {
+          if (_val && (_val.includes('SwiftShader') || _val === '')) return 'Intel Iris OpenGL Engine';
+          return _val;
+        }
+        return _val;
+      }, 'getParameter');
+    };
+    _patchWebGL(window.WebGLRenderingContext);
+    _patchWebGL(window.WebGL2RenderingContext);
+  })();
+})();
+"""
+
+
+def _normalize_locale(raw: str | None) -> str | None:
+    if raw is None:
+        return None
+    value = raw.strip().split(".", 1)[0]
+    if not value:
+        return None
+    return value.replace("_", "-")
+
+
+def _languages_for_locale(locale: str | None) -> list[str]:
+    normalized = _normalize_locale(locale)
+    if not normalized:
+        return ["en-US", "en"]
+    parts = normalized.split("-")
+    base = parts[0]
+    langs = [normalized]
+    if base != normalized:
+        langs.append(base)
+    if base.lower() != "en" and "en" not in langs:
+        langs.append("en")
+    return langs
+
+
+def _get_playwright_disabled_features() -> list[str]:
+    try:
+        import playwright as playwright_pkg
+    except Exception:
+        return []
+    try:
+        switches_js = (
+            Path(playwright_pkg.__file__).parent
+            / "driver/package/lib/server/chromium/chromiumSwitches.js"
+        )
+        text = switches_js.read_text(encoding="utf-8")
+        match = re.search(r"const disabledFeatures\s*=.*?\[(.+?)\]\.filter", text, re.DOTALL)
+        if not match:
+            return []
+        return [feature for feature in re.findall(r'"([^"]+)"', match.group(1)) if feature]
+    except Exception:
+        return []
+
+
+def _build_disable_features(headless: bool) -> str:
+    playright_features = _get_playwright_disabled_features()
+    browser_cli_features = (
+        CHROME_DISABLED_COMPONENTS if headless else CHROME_DISABLED_COMPONENTS_HEADED
+    )
+    combined = list(dict.fromkeys(playright_features + list(browser_cli_features)))
+    return f"--disable-features={','.join(combined)}"
+
+
+def build_launch_args(
+    *,
+    headless: bool,
+    viewport_width: int,
+    viewport_height: int,
+    locale: str | None = None,
+) -> list[str]:
+    normalized_locale = _normalize_locale(locale) or "en-US"
+    if headless:
+        args = [arg for arg in CHROME_STEALTH_ARGS if not arg.startswith("--lang=")]
+        args.append(f"--lang={normalized_locale}")
+        if sys.platform == "linux":
+            args.extend(CHROME_LINUX_ONLY_ARGS)
+        args.append(_build_disable_features(headless=True))
+        args.append(f"--window-size={viewport_width},{viewport_height}")
+        args.extend(
+            [
+                "--headless=new",
+                "--hide-scrollbars",
+                "--mute-audio",
+                "--blink-settings=primaryHoverType=2,availableHoverTypes=2,primaryPointerType=4,availablePointerTypes=4",
+            ]
+        )
+        return args
+
+    args = list(CHROME_STEALTH_ARGS_HEADED)
+    if sys.platform == "linux":
+        args.append("--disable-dev-shm-usage")
+    args.append(_build_disable_features(headless=False))
+    args.append(f"--lang={normalized_locale}")
+    args.append(f"--window-size={viewport_width},{viewport_height}")
+    return args
+
+
+def build_ignore_default_args() -> list[str]:
+    return list(CHROME_IGNORE_DEFAULT_ARGS)
+
+
+def build_context_options(
+    *,
+    viewport_width: int,
+    viewport_height: int,
+    locale: str | None = None,
+) -> dict[str, Any]:
+    options: dict[str, Any] = {
+        "accept_downloads": True,
+        "permissions": list(DEFAULT_PERMISSIONS),
+        "screen": {"width": viewport_width, "height": viewport_height},
+    }
+    normalized_locale = _normalize_locale(locale)
+    if normalized_locale:
+        options["locale"] = normalized_locale
+    return options
+
+
+def build_init_script(*, headless: bool, locale: str | None = None) -> str | None:
+    if not headless:
+        return None
+    return _STEALTH_INIT_SCRIPT_TEMPLATE.replace(
+        "__BROWSER_CLI_LANGS__",
+        json.dumps(_languages_for_locale(locale)),
+    )

browser_cli/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package."""

browser_cli/cli/error_hints.py

@@ -0,0 +1,26 @@
+"""Short recovery hints for common CLI failures."""
+
+from __future__ import annotations
+
+from browser_cli import error_codes
+from browser_cli.errors import BrowserCliError
+
+
+def next_hint_for_error(exc: BrowserCliError) -> str | None:
+    if exc.error_code == error_codes.BROWSER_UNAVAILABLE:
+        return "install stable Google Chrome and re-run browser-cli doctor"
+    if exc.error_code == error_codes.PROFILE_UNAVAILABLE:
+        return "close Browser CLI-owned Chrome windows or inspect browser-cli status"
+    if exc.error_code in {
+        error_codes.DAEMON_NOT_AVAILABLE,
+        error_codes.AUTOMATION_SERVICE_NOT_AVAILABLE,
+    }:
+        return "run browser-cli reload"
+    message = str(exc).lower()
+    if exc.error_code == error_codes.INVALID_INPUT and "task" in message:
+        return "run browser-cli task validate <task-dir>"
+    if "version" in message and "not found" in message:
+        return "run browser-cli automation versions <automation-id>"
+    if "automation" in message and "not found" in message:
+        return "run browser-cli automation list"
+    return None