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

browser_cli/drivers/_extension/observe_actions.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+class ExtensionDriverObserveActionsMixin:
+    async def wait(
+        self,
+        page_id: str,
+        *,
+        seconds: float | None = None,
+        text: str | None = None,
+        gone: bool = False,
+        exact: bool = False,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "wait",
+            {
+                "seconds": seconds,
+                "text": text,
+                "gone": gone,
+                "exact": exact,
+            },
+        )
+        return {"page_id": page_id, **payload}
+
+    async def wait_for_network_idle(
+        self, page_id: str, *, timeout_seconds: float = 30.0
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id, "wait-network", {"timeout_seconds": timeout_seconds}
+        )
+        return {"page_id": page_id, **payload}
+
+    async def start_console_capture(self, page_id: str) -> dict[str, object]:
+        payload = await self._page_command(page_id, "console-start", {})
+        return {"page_id": page_id, **payload}
+
+    async def get_console_messages(
+        self,
+        page_id: str,
+        *,
+        message_type: str | None = None,
+        clear: bool = True,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "console-get",
+            {"message_type": message_type, "clear": clear},
+        )
+        return {"page_id": page_id, **payload}
+
+    async def stop_console_capture(self, page_id: str) -> dict[str, object]:
+        payload = await self._page_command(page_id, "console-stop", {})
+        return {"page_id": page_id, **payload}
+
+    async def start_network_capture(self, page_id: str) -> dict[str, object]:
+        payload = await self._page_command(page_id, "network-start", {})
+        return {"page_id": page_id, **payload}
+
+    async def wait_for_network_record(
+        self,
+        page_id: str,
+        *,
+        url_contains: str | None = None,
+        url_regex: str | None = None,
+        method: str | None = None,
+        status: int | None = None,
+        resource_type: str | None = None,
+        mime_contains: str | None = None,
+        include_static: bool = False,
+        timeout_seconds: float = 30.0,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "network-wait",
+            {
+                "url_contains": url_contains,
+                "url_regex": url_regex,
+                "method": method,
+                "status": status,
+                "resource_type": resource_type,
+                "mime_contains": mime_contains,
+                "include_static": include_static,
+                "timeout_seconds": timeout_seconds,
+            },
+        )
+        await self._materialize_network_body_artifacts(payload, page_id=page_id)
+        return {"page_id": page_id, **payload}
+
+    async def get_network_records(
+        self,
+        page_id: str,
+        *,
+        url_contains: str | None = None,
+        url_regex: str | None = None,
+        method: str | None = None,
+        status: int | None = None,
+        resource_type: str | None = None,
+        mime_contains: str | None = None,
+        include_static: bool = False,
+        clear: bool = True,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "network",
+            {
+                "url_contains": url_contains,
+                "url_regex": url_regex,
+                "method": method,
+                "status": status,
+                "resource_type": resource_type,
+                "mime_contains": mime_contains,
+                "include_static": include_static,
+                "clear": clear,
+            },
+        )
+        await self._materialize_network_body_artifacts(payload, page_id=page_id)
+        return {"page_id": page_id, **payload}
+
+    async def stop_network_capture(self, page_id: str) -> dict[str, object]:
+        payload = await self._page_command(page_id, "network-stop", {})
+        return {"page_id": page_id, **payload}
+
+    async def _materialize_network_body_artifacts(
+        self, payload: dict[str, object], *, page_id: str
+    ) -> None:
+        artifacts = list(payload.get("_artifacts") or [])
+        artifact_paths: dict[str, str] = {}
+        for artifact in artifacts:
+            if str(artifact.get("artifact_kind") or "") != "network-body":
+                continue
+            artifact_id = str(artifact.get("artifact_id") or "").strip()
+            if not artifact_id:
+                continue
+            resolved = self._resolve_artifact_output_path(
+                artifact,
+                page_id=page_id,
+                path=None,
+                suffix="",
+            )
+            self._write_artifact_bytes(artifact, resolved)
+            artifact_paths[artifact_id] = str(resolved)
+        if "record" in payload and isinstance(payload.get("record"), dict):
+            self._rewrite_network_body_path(payload["record"], artifact_paths)
+        records = payload.get("records")
+        if isinstance(records, list):
+            for record in records:
+                if isinstance(record, dict):
+                    self._rewrite_network_body_path(record, artifact_paths)
+
+    @staticmethod
+    def _rewrite_network_body_path(
+        record: dict[str, object], artifact_paths: dict[str, str]
+    ) -> None:
+        body = record.get("body")
+        if not isinstance(body, dict):
+            return
+        raw_path = str(body.get("path") or "")
+        if not raw_path.startswith("artifact://"):
+            return
+        artifact_id = raw_path.removeprefix("artifact://")
+        resolved_path = artifact_paths.get(artifact_id)
+        if resolved_path:
+            body["path"] = resolved_path
+
+    async def get_cookies(
+        self,
+        page_id: str,
+        *,
+        name: str | None = None,
+        domain: str | None = None,
+        path: str | None = None,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "cookies-get",
+            {"name": name, "domain": domain, "path": path},
+        )
+        return {"page_id": page_id, **payload}
+
+    async def set_cookie(
+        self,
+        page_id: str,
+        *,
+        name: str,
+        value: str,
+        domain: str | None = None,
+        path: str = "/",
+        expires: float | None = None,
+        http_only: bool = False,
+        secure: bool = False,
+        same_site: str | None = None,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "cookie-set",
+            {
+                "name": name,
+                "value": value,
+                "domain": domain,
+                "path": path,
+                "expires": expires,
+                "http_only": http_only,
+                "secure": secure,
+                "same_site": same_site,
+            },
+        )
+        return {"page_id": page_id, **payload}
+
+    async def clear_cookies(
+        self,
+        page_id: str,
+        *,
+        name: str | None = None,
+        domain: str | None = None,
+        path: str | None = None,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "cookies-clear",
+            {"name": name, "domain": domain, "path": path},
+        )
+        return {"page_id": page_id, **payload}
+
+    async def save_storage_state(
+        self, page_id: str, *, path: str | None = None
+    ) -> dict[str, object]:
+        payload = await self._page_command(page_id, "storage-get", {})
+        output_path = self._resolve_output_path(path, page_id=page_id, suffix=".json")
+        output_path.write_text(json.dumps(payload, ensure_ascii=True, indent=2), encoding="utf-8")
+        return {"page_id": page_id, "path": str(output_path)}
+
+    async def load_storage_state(self, page_id: str, *, path: str) -> dict[str, object]:
+        payload = json.loads(Path(path).read_text(encoding="utf-8"))
+        result = await self._page_command(page_id, "storage-set", payload)
+        return {"page_id": page_id, **result}
+
+    async def verify_text(
+        self,
+        page_id: str,
+        *,
+        text: str,
+        exact: bool = False,
+        timeout_seconds: float = 5.0,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "verify-text",
+            {"text": text, "exact": exact, "timeout_seconds": timeout_seconds},
+        )
+        return {"page_id": page_id, **payload}
+
+    async def verify_url(
+        self, page_id: str, *, expected: str, exact: bool = False
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id, "verify-url", {"expected": expected, "exact": exact}
+        )
+        return {"page_id": page_id, **payload}
+
+    async def verify_title(
+        self, page_id: str, *, expected: str, exact: bool = False
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id, "verify-title", {"expected": expected, "exact": exact}
+        )
+        return {"page_id": page_id, **payload}
+
+    async def verify_visible(
+        self,
+        page_id: str,
+        *,
+        role: str,
+        name: str,
+        timeout_seconds: float = 5.0,
+    ) -> dict[str, object]:
+        payload = await self._page_command(
+            page_id,
+            "verify-visible",
+            {"role": role, "name": name, "timeout_seconds": timeout_seconds},
+        )
+        return {"page_id": page_id, **payload}

browser_cli/drivers/_extension/page_actions.py

@@ -0,0 +1,210 @@
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from browser_cli.refs.models import SnapshotInput
+
+from ..models import TabState
+
+
+class ExtensionDriverPageActionsMixin:
+    async def new_tab(
+        self,
+        *,
+        page_id: str,
+        url: str | None = None,
+        wait_until: str = "load",
+        timeout_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        session = await self._require_session()
+        payload = await session.send_request(
+            "open-tab",
+            {
+                "page_id": page_id,
+                "url": url,
+                "wait_until": wait_until,
+                "timeout_seconds": timeout_seconds,
+            },
+        )
+        tab_id = int(payload["tab_id"])
+        self._page_to_tab[page_id] = tab_id
+        self._tab_to_page[tab_id] = page_id
+        self._active_page_id = page_id
+        return {
+            "page_id": page_id,
+            "url": str(payload.get("url") or url or ""),
+            "title": str(payload.get("title") or ""),
+        }
+
+    async def close_tab(self, page_id: str) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request("close-tab", {"tab_id": tab_id})
+        self._page_to_tab.pop(page_id, None)
+        self._tab_to_page.pop(tab_id, None)
+        if self._active_page_id == page_id:
+            self._active_page_id = next(iter(self._page_to_tab.keys()), None)
+        result = {
+            "page_id": page_id,
+            "closed": True,
+            "url": str(payload.get("url") or ""),
+            "title": str(payload.get("title") or ""),
+        }
+        video_paths = await self._materialize_video_artifacts(payload.get("_artifacts") or [])
+        if video_paths:
+            result["video_path"] = video_paths[0]
+        return result
+
+    async def list_tabs(self) -> list[TabState]:
+        session = await self._require_session()
+        payload = await session.send_request("list-tabs", {})
+        results: list[TabState] = []
+        for item in payload.get("tabs", []):
+            try:
+                tab_id = int(item["tab_id"])
+            except Exception:
+                continue
+            page_id = self._tab_to_page.get(tab_id)
+            if not page_id:
+                continue
+            results.append(
+                TabState(
+                    page_id=page_id,
+                    url=str(item.get("url") or ""),
+                    title=str(item.get("title") or ""),
+                    active=bool(item.get("active")),
+                )
+            )
+            if item.get("active"):
+                self._active_page_id = page_id
+        return results
+
+    async def switch_tab(self, page_id: str) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request("activate-tab", {"tab_id": tab_id})
+        self._active_page_id = page_id
+        return {
+            "page_id": page_id,
+            "url": str(payload.get("url") or ""),
+            "title": str(payload.get("title") or ""),
+        }
+
+    async def get_page_summary(self, page_id: str) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request("page-summary", {"tab_id": tab_id})
+        return {
+            "page_id": page_id,
+            "url": str(payload.get("url") or ""),
+            "title": str(payload.get("title") or ""),
+        }
+
+    async def get_page_info(self, page_id: str) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request("page-info", {"tab_id": tab_id})
+        return {"page_id": page_id, **payload}
+
+    async def capture_html(self, page_id: str) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request("capture-html", {"tab_id": tab_id})
+        return {"page_id": page_id, "html": str(payload.get("html") or "")}
+
+    async def capture_snapshot_input(
+        self,
+        page_id: str,
+        *,
+        interactive: bool = False,
+        full_page: bool = True,
+    ) -> SnapshotInput:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request(
+            "capture-snapshot-input",
+            {
+                "tab_id": tab_id,
+                "interactive": interactive,
+                "full_page": full_page,
+            },
+        )
+        return SnapshotInput(
+            raw_snapshot=str(payload.get("raw_snapshot") or ""),
+            captured_url=str(payload.get("captured_url") or ""),
+            captured_at=float(payload.get("captured_at") or time.time()),
+        )
+
+    async def navigate(
+        self,
+        page_id: str,
+        url: str,
+        *,
+        wait_until: str = "load",
+        timeout_seconds: float = 30.0,
+    ) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        payload = await session.send_request(
+            "navigate",
+            {
+                "tab_id": tab_id,
+                "url": url,
+                "wait_until": wait_until,
+                "timeout_seconds": timeout_seconds,
+            },
+        )
+        return {
+            "page_id": page_id,
+            "url": str(payload.get("url") or url),
+            "title": str(payload.get("title") or ""),
+        }
+
+    async def reload(
+        self,
+        page_id: str,
+        *,
+        wait_until: str = "load",
+        timeout_seconds: float = 30.0,
+    ) -> dict[str, Any]:
+        return await self._simple_page_command(
+            page_id,
+            "reload",
+            {"wait_until": wait_until, "timeout_seconds": timeout_seconds},
+        )
+
+    async def go_back(self, page_id: str) -> dict[str, Any]:
+        return await self._simple_page_command(page_id, "go-back", {})
+
+    async def go_forward(self, page_id: str) -> dict[str, Any]:
+        return await self._simple_page_command(page_id, "go-forward", {})
+
+    async def resize(self, page_id: str, *, width: int, height: int) -> dict[str, Any]:
+        payload = await self._page_command(page_id, "resize", {"width": width, "height": height})
+        return {
+            "page_id": page_id,
+            "width": int(payload.get("width") or width),
+            "height": int(payload.get("height") or height),
+        }
+
+    async def evaluate(self, page_id: str, code: str) -> dict[str, Any]:
+        payload = await self._page_command(page_id, "eval", {"code": code})
+        return {"page_id": page_id, "result": payload.get("result")}
+
+    async def _simple_page_command(
+        self, page_id: str, action: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        payload = await self._page_command(page_id, action, payload)
+        return {
+            "page_id": page_id,
+            "url": str(payload.get("url") or ""),
+            "title": str(payload.get("title") or ""),
+        }
+
+    async def _page_command(
+        self, page_id: str, action: str, payload: dict[str, Any]
+    ) -> dict[str, Any]:
+        tab_id = self._require_tab_id(page_id)
+        session = await self._require_session()
+        return await session.send_request(action, {"tab_id": tab_id, **payload})

browser_cli/drivers/_extension/state_actions.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from browser_cli.errors import OperationFailedError, TabNotFoundError
+
+if TYPE_CHECKING:
+    from browser_cli.extension import ExtensionHub
+
+
+class ExtensionDriverStateMixin:
+    _hub: ExtensionHub
+    _page_to_tab: dict[str, int]
+    _tab_to_page: dict[int, str]
+    _active_page_id: str | None
+
+    async def ensure_started(self) -> None:
+        await self._hub.ensure_started()
+        if self._hub.session is None:
+            raise OperationFailedError(
+                "Browser CLI extension is not connected.",
+                error_code="EXTENSION_UNAVAILABLE",
+            )
+
+    async def stop(self) -> dict[str, Any]:
+        closed_pages = sorted(self._page_to_tab.keys())
+        session = self._hub.session
+        payload: dict[str, Any] = {}
+        cleanup_error: str | None = None
+        if session is not None:
+            try:
+                payload = await session.send_request("workspace-close", {})
+            except Exception as exc:
+                cleanup_error = str(exc)
+                payload = {}
+        video_paths = await self._materialize_video_artifacts(payload.get("_artifacts") or [])
+        self._page_to_tab.clear()
+        self._tab_to_page.clear()
+        self._active_page_id = None
+        result = {
+            "closed_pages": closed_pages,
+            "extension_connected": session is not None,
+            "video_paths": video_paths,
+        }
+        if cleanup_error:
+            result["cleanup_error"] = cleanup_error
+        return result
+
+    async def workspace_status(self) -> dict[str, Any]:
+        session = await self._require_session()
+        payload = await session.send_request("workspace-status", {})
+        return {
+            "window_id": payload.get("window_id"),
+            "tab_count": int(payload.get("tab_count") or 0),
+            "managed_tab_count": int(payload.get("managed_tab_count") or 0),
+            "binding_state": str(payload.get("binding_state") or "absent"),
+        }
+
+    async def rebuild_workspace_binding(self) -> dict[str, Any]:
+        session = await self._require_session()
+        payload = await session.send_request("workspace-rebuild-binding", {})
+        video_paths = await self._materialize_video_artifacts(payload.get("_artifacts") or [])
+        self._page_to_tab.clear()
+        self._tab_to_page.clear()
+        self._active_page_id = None
+        return {
+            "rebuilt": bool(payload.get("rebuilt")),
+            "workspace_window_state": {
+                "window_id": payload.get("window_id"),
+                "tab_count": int(payload.get("tab_count") or 0),
+                "managed_tab_count": int(payload.get("managed_tab_count") or 0),
+                "binding_state": str(payload.get("binding_state") or "absent"),
+            },
+            "video_paths": video_paths,
+        }
+
+    async def health(self):
+        session = self._hub.session
+        if session is None:
+            from ..models import DriverHealth
+
+            return DriverHealth(name=self.name, available=False, details={"connected": False})
+        hello = session.hello
+        from ..models import DriverHealth
+
+        return DriverHealth(
+            name=self.name,
+            available=hello.has_required_capabilities(),
+            details={
+                "connected": True,
+                "extension_version": hello.extension_version,
+                "browser_name": hello.browser_name,
+                "browser_version": hello.browser_version,
+                "capabilities": sorted(hello.capabilities),
+                "capability_complete": hello.has_required_capabilities(),
+                "missing_capabilities": hello.missing_required_capabilities(),
+                "workspace_window_state": dict(hello.workspace_window_state),
+                "extension_instance_id": hello.extension_instance_id,
+            },
+        )
+
+    async def _require_session(self):
+        await self.ensure_started()
+        session = self._hub.session
+        if session is None:
+            raise OperationFailedError(
+                "Browser CLI extension is not connected.", error_code="EXTENSION_UNAVAILABLE"
+            )
+        return session
+
+    def _require_tab_id(self, page_id: str) -> int:
+        tab_id = self._page_to_tab.get(page_id)
+        if tab_id is None:
+            raise TabNotFoundError()
+        return tab_id
+
+    @staticmethod
+    def _resolve_output_path(path: str | None, *, page_id: str, suffix: str) -> Path:
+        if not path:
+            from browser_cli.constants import get_app_paths
+
+            output = get_app_paths().artifacts_dir / f"{page_id}{suffix}"
+            output.parent.mkdir(parents=True, exist_ok=True)
+            return output.resolve()
+        raw = Path(path).expanduser()
+        if not raw.is_absolute():
+            from browser_cli.constants import get_app_paths
+
+            raw = (get_app_paths().artifacts_dir / raw).resolve()
+        if raw.suffix.lower() != suffix:
+            raw = raw.with_suffix(suffix)
+        raw.parent.mkdir(parents=True, exist_ok=True)
+        return raw