persistent-browser-bridge 0.1.0__py3-none-any.whl

pbb/__init__.py

@@ -0,0 +1,5 @@
+"""Persistent Browser Bridge public package."""
+
+from pbb.constants import __version__
+
+__all__ = ["__version__"]

pbb/browser/__init__.py

@@ -0,0 +1 @@
+"""Browser management primitives."""

pbb/browser/browser_detection.py

@@ -0,0 +1,117 @@
+"""Detect installed Edge, Chrome, or Chromium browsers."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class BrowserInstall:
+    name: str
+    channel: str | None
+    executable: str | None
+
+    def as_dict(self) -> dict[str, str | None]:
+        return asdict(self)
+
+
+def _windows_candidates() -> list[BrowserInstall]:
+    local = Path(os.environ.get("LOCALAPPDATA", ""))
+    return [
+        BrowserInstall(
+            "Microsoft Edge",
+            "msedge",
+            str(
+                Path(os.environ.get("PROGRAMFILES(X86)", "C:/Program Files (x86)"))
+                / "Microsoft/Edge/Application/msedge.exe"
+            ),
+        ),
+        BrowserInstall(
+            "Microsoft Edge",
+            "msedge",
+            str(
+                Path(os.environ.get("PROGRAMFILES", "C:/Program Files"))
+                / "Microsoft/Edge/Application/msedge.exe"
+            ),
+        ),
+        BrowserInstall(
+            "Microsoft Edge", "msedge", str(local / "Microsoft/Edge/Application/msedge.exe")
+        ),
+        BrowserInstall(
+            "Google Chrome",
+            "chrome",
+            str(
+                Path(os.environ.get("PROGRAMFILES", "C:/Program Files"))
+                / "Google/Chrome/Application/chrome.exe"
+            ),
+        ),
+        BrowserInstall(
+            "Google Chrome",
+            "chrome",
+            str(
+                Path(os.environ.get("PROGRAMFILES(X86)", "C:/Program Files (x86)"))
+                / "Google/Chrome/Application/chrome.exe"
+            ),
+        ),
+        BrowserInstall(
+            "Google Chrome", "chrome", str(local / "Google/Chrome/Application/chrome.exe")
+        ),
+    ]
+
+
+def detect_browsers() -> list[BrowserInstall]:
+    candidates: list[BrowserInstall] = []
+    if sys.platform == "win32":
+        candidates.extend(_windows_candidates())
+    elif sys.platform == "darwin":
+        candidates.extend(
+            [
+                BrowserInstall(
+                    "Microsoft Edge",
+                    "msedge",
+                    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+                ),
+                BrowserInstall(
+                    "Google Chrome",
+                    "chrome",
+                    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+                ),
+            ]
+        )
+    else:
+        for name, channel, command in (
+            ("Microsoft Edge", "msedge", "microsoft-edge"),
+            ("Google Chrome", "chrome", "google-chrome"),
+            ("Chromium", None, "chromium"),
+            ("Chromium", None, "chromium-browser"),
+        ):
+            candidates.append(BrowserInstall(name, channel, shutil.which(command)))
+    seen: set[tuple[str, str]] = set()
+    found: list[BrowserInstall] = []
+    for item in candidates:
+        if item.executable and Path(item.executable).is_file():
+            key = (item.name, str(Path(item.executable).resolve()).lower())
+            if key not in seen:
+                seen.add(key)
+                found.append(item)
+    return found
+
+
+def select_browser(preference: str) -> BrowserInstall:
+    installed = detect_browsers()
+    aliases = {"edge": "Microsoft Edge", "chrome": "Google Chrome", "chromium": "Chromium"}
+    if preference != "auto":
+        wanted = aliases[preference]
+        for browser in installed:
+            if browser.name == wanted:
+                return browser
+        if preference == "chromium":
+            return BrowserInstall("Playwright Chromium", None, None)
+        raise FileNotFoundError(f"Requested browser '{preference}' was not found")
+    if installed:
+        return installed[0]
+    return BrowserInstall("Playwright Chromium", None, None)

pbb/browser/locator.py

@@ -0,0 +1,103 @@
+"""Conservative target resolution."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import Locator, Page
+
+from pbb.browser.snapshot import SnapshotStore
+
+
+class LocatorResolutionError(RuntimeError):
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.details = details or {}
+
+
+@dataclass(frozen=True)
+class ResolvedLocator:
+    locator: Locator
+    metadata: dict[str, Any]
+
+
+async def _unique(locator: Locator, label: str) -> ResolvedLocator | None:
+    count = await locator.count()
+    if count == 1:
+        return ResolvedLocator(locator.first, {"strategy": label})
+    if count > 1:
+        matches: list[dict[str, str]] = []
+        for index in range(min(count, 10)):
+            item = locator.nth(index)
+            matches.append(
+                {
+                    "tag": await item.evaluate("el => el.tagName.toLowerCase()"),
+                    "text": (await item.inner_text())[:200],
+                }
+            )
+        raise LocatorResolutionError(
+            "ambiguous_target",
+            f"Target matched {count} elements using {label}",
+            {"matches": matches},
+        )
+    return None
+
+
+async def resolve_locator(page: Page, store: SnapshotStore, target: str) -> ResolvedLocator:
+    match = re.fullmatch(r"(?:(s_[0-9a-f]+):)?@(\d+)", target)
+    if match:
+        explicit_snapshot, raw_id = match.groups()
+        if explicit_snapshot and explicit_snapshot != store.snapshot_id:
+            raise LocatorResolutionError(
+                "stale_snapshot", "Snapshot reference is no longer current"
+            )
+        item = store.get(int(raw_id))
+        if item is None:
+            raise LocatorResolutionError(
+                "element_not_found", f"Snapshot element {target} was not found"
+            )
+        if page.url != store.page_url:
+            raise LocatorResolutionError("stale_snapshot", "Page URL changed after the snapshot")
+        locator = page.locator(item["selector"])
+        if await locator.count() != 1:
+            raise LocatorResolutionError(
+                "stale_snapshot", "Snapshot element changed or disappeared"
+            )
+        current = await locator.first.evaluate(
+            "el => ({name:(el.getAttribute('aria-label') || el.innerText || el.getAttribute('name') || el.getAttribute('placeholder') || '').replace(/\\s+/g,' ').trim(), role:el.getAttribute('role') || ''})"
+        )
+        expected_name = item.get("name", "")
+        if expected_name and current["name"] and expected_name != current["name"]:
+            raise LocatorResolutionError("stale_snapshot", "Snapshot element identity changed")
+        return ResolvedLocator(
+            locator.first, {"strategy": "snapshot", "snapshot_id": store.snapshot_id}
+        )
+
+    selector_error: PlaywrightError | None = None
+    try:
+        direct = await _unique(page.locator(target), "selector")
+        if direct:
+            return direct
+    except PlaywrightError as exc:
+        selector_error = exc
+    if selector_error and target.startswith(("#", ".", "[", "//", "css=", "xpath=")):
+        raise LocatorResolutionError(
+            "invalid_selector", f"Invalid selector: {target}"
+        ) from selector_error
+
+    strategies = [
+        (page.get_by_role("button", name=target, exact=True), "button role"),
+        (page.get_by_role("link", name=target, exact=True), "link role"),
+        (page.get_by_label(target, exact=True), "label"),
+        (page.get_by_placeholder(target, exact=True), "placeholder"),
+        (page.get_by_text(target, exact=True), "exact text"),
+    ]
+    for locator, label in strategies:
+        result = await _unique(locator, label)
+        if result:
+            return result
+    raise LocatorResolutionError("element_not_found", f"No element matched target: {target}")

pbb/browser/locks.py

@@ -0,0 +1,77 @@
+"""PBB-owned profile lock files."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import psutil
+
+
+class ProfileLockedError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class LockInfo:
+    pid: int
+    start_time: float
+    profile: str
+
+
+class ProfileLock:
+    def __init__(self, profile_path: Path, profile: str) -> None:
+        self.path = profile_path / "profile.lock"
+        self.profile = profile
+        self.acquired = False
+
+    def read(self) -> LockInfo | None:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+            return LockInfo(**raw)
+        except (OSError, ValueError, TypeError):
+            return None
+
+    def is_stale(self) -> bool:
+        info = self.read()
+        if info is None:
+            return self.path.exists()
+        if not psutil.pid_exists(info.pid):
+            return True
+        try:
+            return abs(psutil.Process(info.pid).create_time() - info.start_time) > 2
+        except (psutil.Error, OSError):
+            return True
+
+    def acquire(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if self.path.exists():
+            info = self.read()
+            if not self.is_stale():
+                owner = info.pid if info else "unknown"
+                raise ProfileLockedError(
+                    f"Profile '{self.profile}' is already in use by PID {owner}."
+                )
+            self.path.unlink(missing_ok=True)
+        info = LockInfo(os.getpid(), psutil.Process().create_time(), self.profile)
+        flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY
+        try:
+            descriptor = os.open(self.path, flags)
+        except FileExistsError as exc:
+            raise ProfileLockedError(f"Profile '{self.profile}' is already in use.") from exc
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(asdict(info), handle)
+        self.acquired = True
+
+    def release(self) -> None:
+        if self.acquired:
+            self.path.unlink(missing_ok=True)
+            self.acquired = False
+
+    def clear_stale(self) -> bool:
+        if self.path.exists() and self.is_stale():
+            self.path.unlink()
+            return True
+        return False

pbb/browser/manager.py

@@ -0,0 +1,218 @@
+"""Own the Playwright persistent context for the daemon lifetime."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from pathlib import Path
+from typing import Any
+
+from playwright.async_api import (
+    BrowserContext,
+    Error,
+    Page,
+    Playwright,
+    TimeoutError,
+    async_playwright,
+)
+
+from pbb.browser.browser_detection import BrowserInstall, select_browser
+from pbb.browser.locator import LocatorResolutionError, resolve_locator
+from pbb.browser.locks import ProfileLock
+from pbb.browser.profile import create_profile
+from pbb.browser.snapshot import SnapshotStore, capture_snapshot
+from pbb.config import Settings
+
+
+class BrowserManager:
+    def __init__(self, settings: Settings, profile: str, browser: str | None = None) -> None:
+        self.settings = settings
+        self.profile = profile
+        self.preference = browser or settings.browser
+        self.install: BrowserInstall | None = None
+        self.playwright: Playwright | None = None
+        self.context: BrowserContext | None = None
+        self.active_page: Page | None = None
+        self.store = SnapshotStore()
+        self.lock = ProfileLock(create_profile(profile), profile)
+        self.restarts = 0
+
+    async def start(self) -> None:
+        if self.context:
+            return
+        self.lock.acquire()
+        try:
+            self.install = select_browser(self.preference)
+            self.playwright = await async_playwright().start()
+            options: dict[str, Any] = {
+                "user_data_dir": str(create_profile(self.profile)),
+                "headless": self.settings.headless,
+                "accept_downloads": True,
+                "downloads_path": str(self.settings.download_dir),
+                "timeout": self.settings.timeout,
+            }
+            if self.install.channel:
+                options["channel"] = self.install.channel
+            elif self.install.executable:
+                options["executable_path"] = self.install.executable
+            self.context = await self.playwright.chromium.launch_persistent_context(**options)
+            self.context.set_default_timeout(self.settings.timeout)
+            self.active_page = (
+                self.context.pages[-1] if self.context.pages else await self.context.new_page()
+            )
+        except Exception:
+            self.lock.release()
+            if self.playwright:
+                await self.playwright.stop()
+                self.playwright = None
+            raise
+
+    async def close(self) -> None:
+        try:
+            if self.context:
+                await self.context.close()
+        finally:
+            self.context = None
+            self.active_page = None
+            if self.playwright:
+                await self.playwright.stop()
+                self.playwright = None
+            self.lock.release()
+
+    async def page(self) -> tuple[Page, bool]:
+        if not self.context:
+            await self.start()
+            assert self.active_page is not None
+            return self.active_page, True
+        assert self.context is not None
+        try:
+            if not self.active_page or self.active_page.is_closed():
+                pages = [page for page in self.context.pages if not page.is_closed()]
+                self.active_page = pages[-1] if pages else await self.context.new_page()
+                return self.active_page, True
+            return self.active_page, False
+        except Error:
+            await self.close()
+            self.restarts += 1
+            await self.start()
+            assert self.active_page is not None
+            return self.active_page, True
+
+    async def status(self) -> dict[str, Any]:
+        page = self.active_page
+        running = self.context is not None
+        restarted = False
+        if running and (page is None or page.is_closed()):
+            page, restarted = await self.page()
+        return {
+            "success": True,
+            "browser_running": running,
+            "browser": self.install.name if self.install else None,
+            "profile": self.profile,
+            "url": page.url if page and not page.is_closed() else None,
+            "title": await page.title() if page and not page.is_closed() else None,
+            "tabs": len(self.context.pages) if self.context else 0,
+            "browser_restarted": restarted,
+        }
+
+    async def navigate(self, url: str) -> dict[str, Any]:
+        page, restarted = await self.page()
+        started = time.perf_counter()
+        try:
+            await page.goto(url, wait_until="domcontentloaded", timeout=self.settings.timeout)
+        except TimeoutError as exc:
+            raise LocatorResolutionError(
+                "navigation_timeout", f"Navigation timed out: {url}"
+            ) from exc
+        return {
+            "success": True,
+            "url": page.url,
+            "title": await page.title(),
+            "duration_ms": round((time.perf_counter() - started) * 1000),
+            "browser_restarted": restarted,
+        }
+
+    async def snapshot(self) -> dict[str, Any]:
+        page, restarted = await self.page()
+        result = await capture_snapshot(page, self.store, self.settings.snapshot_max_chars)
+        result["browser_restarted"] = restarted
+        return result
+
+    async def click(self, target: str) -> dict[str, Any]:
+        page, restarted = await self.page()
+        resolved = await resolve_locator(page, self.store, target)
+        started = time.perf_counter()
+        await resolved.locator.click()
+        await asyncio.sleep(0.15)
+        return {
+            "success": True,
+            "action": "click",
+            "target": target,
+            "url": page.url,
+            "duration_ms": round((time.perf_counter() - started) * 1000),
+            "browser_restarted": restarted,
+        }
+
+    async def fill(self, target: str, value: str) -> dict[str, Any]:
+        page, restarted = await self.page()
+        resolved = await resolve_locator(page, self.store, target)
+        started = time.perf_counter()
+        await resolved.locator.fill(value)
+        input_type = await resolved.locator.get_attribute("type")
+        return {
+            "success": True,
+            "action": "fill",
+            "target": target,
+            "value_redacted": input_type == "password",
+            "url": page.url,
+            "duration_ms": round((time.perf_counter() - started) * 1000),
+            "browser_restarted": restarted,
+        }
+
+    async def text(self, target: str) -> dict[str, Any]:
+        page, restarted = await self.page()
+        resolved = await resolve_locator(page, self.store, target)
+        return {
+            "success": True,
+            "text": await resolved.locator.inner_text(),
+            "browser_restarted": restarted,
+        }
+
+    async def download(self, target: str, output: Path | None = None) -> dict[str, Any]:
+        page, restarted = await self.page()
+        resolved = await resolve_locator(page, self.store, target)
+        try:
+            async with page.expect_download(timeout=self.settings.timeout) as info:
+                await resolved.locator.click()
+            download = await info.value
+        except TimeoutError as exc:
+            raise LocatorResolutionError(
+                "download_not_triggered", "The target did not trigger a download before timeout"
+            ) from exc
+        destination = output or self.settings.download_dir
+        destination = destination.expanduser().resolve()
+        if destination.suffix and not destination.is_dir():
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            saved_path = destination
+        else:
+            destination.mkdir(parents=True, exist_ok=True)
+            saved_path = destination / download.suggested_filename
+        await download.save_as(saved_path)
+        return {
+            "success": True,
+            "suggested_filename": download.suggested_filename,
+            "saved_path": str(saved_path),
+            "size": saved_path.stat().st_size,
+            "browser_restarted": restarted,
+        }
+
+    async def screenshot(self, output: Path, full_page: bool) -> dict[str, Any]:
+        page, restarted = await self.page()
+        path = output.expanduser().resolve()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        await page.screenshot(path=path, full_page=full_page)
+        return {
+            "success": True,
+            "saved_path": str(path),
+            "browser_restarted": restarted,
+        }

pbb/browser/profile.py

@@ -0,0 +1,56 @@
+"""Dedicated persistent-profile management."""
+
+from __future__ import annotations
+
+import re
+import shutil
+from pathlib import Path
+
+from pbb.utils.paths import profiles_dir
+
+PROFILE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+
+
+class InvalidProfileName(ValueError):
+    pass
+
+
+def validate_profile_name(name: str) -> str:
+    if not PROFILE_RE.fullmatch(name) or name in {".", ".."}:
+        raise InvalidProfileName(
+            "profile names must be 1-64 characters using letters, numbers, '.', '_' or '-'"
+        )
+    return name
+
+
+def profile_path(name: str) -> Path:
+    validate_profile_name(name)
+    root = profiles_dir().resolve()
+    path = (root / name).resolve()
+    if path.parent != root:
+        raise InvalidProfileName("profile path escapes the PBB profiles directory")
+    return path
+
+
+def create_profile(name: str) -> Path:
+    path = profile_path(name)
+    path.mkdir(parents=True, exist_ok=True)
+    marker = path / ".pbb-profile"
+    marker.touch(exist_ok=True)
+    return path
+
+
+def list_profiles() -> list[str]:
+    root = profiles_dir()
+    if not root.exists():
+        return []
+    return sorted(
+        item.name for item in root.iterdir() if item.is_dir() and (item / ".pbb-profile").exists()
+    )
+
+
+def delete_profile(name: str) -> None:
+    path = profile_path(name)
+    if not (path / ".pbb-profile").exists():
+        raise FileNotFoundError(f"PBB profile '{name}' does not exist")
+    shutil.rmtree(path)