capability-compiler 0.1.0__py3-none-any.whl

capability_compiler/adapters/browser/adapter.py

@@ -0,0 +1,474 @@
+"""The Playwright browser adapter — Capability Compiler's first adapter.
+
+Wraps (never reimplements) Playwright's async API. Responsibilities:
+
+* **Observe**: one normalized :class:`Observation` per call — aria snapshot
+  tree (state identity), DOM-scan interactive elements with geometry
+  (actionability), screenshot artifact, URL/title/DOM hash.
+* **Execute**: map domain actions to Playwright calls through semantic-first
+  target resolution (ref → role+name+ordinal → selector → coordinates),
+  letting Playwright's five actionability checks do the waiting.
+* **Ref stability**: ``e1..eN`` ids are positional within an observation;
+  execution always re-resolves against a fresh observation, so recorded
+  capabilities survive DOM churn better than raw handles.
+
+Security:
+* Navigation is **deny-by-default for the network**: with
+  ``security.allow_network = false`` (the default) only ``file:``/``data:``
+  ``about:`` and loopback URLs are permitted. Remote navigation requires the
+  explicit opt-in.
+* Page content (names, DOM, screenshots) is untrusted data. Nothing from the
+  page is ever evaluated as code by this adapter.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import time
+from typing import TYPE_CHECKING, Any, cast
+from urllib.parse import urlparse
+
+from capability_compiler.adapters.browser.aria import parse_aria_snapshot
+from capability_compiler.adapters.browser.elements import _SCAN_JS, parse_scan
+from capability_compiler.errors import (
+    ActionError,
+    ActionValidationError,
+    AdapterError,
+    AdapterNotConnectedError,
+    FailureCategory,
+    ObservationError,
+    PermissionDeniedError,
+)
+from capability_compiler.logging import StructuredLogAdapter, get_logger
+from capability_compiler.models import (
+    ActionResult,
+    EnvironmentMetadata,
+    ImageData,
+    Observation,
+    StructuralObservation,
+)
+from capability_compiler.models.action import (
+    ClickAction,
+    HoverAction,
+    KeyPressAction,
+    NavigateAction,
+    ScrollAction,
+    SelectAction,
+    TypeAction,
+    WaitAction,
+)
+from capability_compiler.types import new_id
+
+if TYPE_CHECKING:
+    from capability_compiler.config import CompilerSettings
+    from capability_compiler.models import Action
+    from capability_compiler.models.action import ActionTarget
+
+from playwright.async_api import Error as PlaywrightError
+from playwright.async_api import Page, async_playwright
+from playwright.async_api import TimeoutError as PlaywrightTimeoutError
+
+
+def _text_digest(text: str | None) -> str | None:
+    """Whitespace-normalized digest of visible page text (deterministic)."""
+    if text is None:
+        return None
+    normalized = " ".join(text.split())
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+_LOCAL_SCHEMES = {"file", "data", "about", "blob"}
+_LOOPBACK_HOSTS = {"localhost", "127.0.0.1", "[::1]", "::1"}
+
+
+def url_allowed(url: str, *, allow_network: bool) -> bool:
+    """Navigation policy: local schemes always; loopback always; anything
+    else requires ``allow_network``. Unparseable/unknown-scheme URLs deny."""
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return False
+    scheme = (parsed.scheme or "").lower()
+    if not scheme:
+        return False
+    if scheme in _LOCAL_SCHEMES:
+        return True
+    if scheme in {"http", "https"}:
+        if parsed.hostname and parsed.hostname.lower() in _LOOPBACK_HOSTS:
+            return True
+        return allow_network
+    return False
+
+
+class BrowserAdapter:
+    """Playwright-backed ``EnvironmentAdapter`` (kind ``"browser"``)."""
+
+    kind = "browser"
+
+    def __init__(self, settings: CompilerSettings | None = None) -> None:
+        from capability_compiler.config import CompilerSettings as _Settings
+
+        self.settings = settings or _Settings()
+        self._log = StructuredLogAdapter(get_logger("adapters.browser"), {})
+        self._playwright: Any = None
+        self._browser: Any = None
+        self._context: Any = None
+        self._page: Page | None = None
+        self._start_url: str | None = None
+        self._last_observation: Observation | None = None
+
+    # -- properties --------------------------------------------------------
+
+    @property
+    def connected(self) -> bool:
+        return self._browser is not None and self._browser.is_connected()
+
+    @property
+    def page(self) -> Page:
+        if self._page is None:
+            raise AdapterNotConnectedError("browser adapter has no page")
+        return self._page
+
+    # -- lifecycle ----------------------------------------------------------
+
+    async def connect(self, url: str | None = None) -> None:
+        """Launch the browser; optionally navigate to *url*."""
+        if self.connected:
+            return
+        browser_cfg = self.settings.browser
+        try:
+            self._playwright = await async_playwright().start()
+            launch_kwargs: dict[str, Any] = {
+                "headless": browser_cfg.headless,
+                "slow_mo": browser_cfg.slow_mo_ms or None,
+            }
+            if browser_cfg.extra_launch_args:
+                launch_kwargs["args"] = list(browser_cfg.extra_launch_args)
+            self._browser = await getattr(self._playwright, browser_cfg.browser).launch(
+                **launch_kwargs
+            )
+            context_kwargs: dict[str, Any] = {
+                "viewport": {
+                    "width": browser_cfg.viewport_width,
+                    "height": browser_cfg.viewport_height,
+                },
+            }
+            if browser_cfg.user_agent:
+                context_kwargs["user_agent"] = browser_cfg.user_agent
+            self._context = await self._browser.new_context(**context_kwargs)
+            self._context.set_default_timeout(browser_cfg.default_timeout_ms)
+            self._page = await self._context.new_page()
+        except PlaywrightError as exc:
+            raise AdapterError(
+                f"failed to launch {browser_cfg.browser}: {exc}",
+                category=FailureCategory.ENVIRONMENT_ERROR,
+                suggestions=["run: python -m playwright install " + browser_cfg.browser],
+            ) from exc
+        target = url or "about:blank"
+        await self._goto(target)
+        self._start_url = target
+
+    async def disconnect(self) -> None:
+        for closer in (
+            getattr(self._context, "close", None),
+            getattr(self._browser, "close", None),
+            getattr(self._playwright, "stop", None),
+        ):
+            if closer is not None:
+                with contextlib.suppress(PlaywrightError):  # teardown races
+                    await closer()
+        self._page = None
+        self._context = None
+        self._browser = None
+        self._playwright = None
+
+    async def reset(self) -> None:
+        """Return to the start URL (best effort; pages with side effects may
+        not fully reset — capability preconditions are the real guard)."""
+        if self._start_url:
+            await self._goto(self._start_url)
+
+    # -- observation ---------------------------------------------------------
+
+    async def observe(self, *, screenshot: bool = True) -> Observation:
+        """Capture one normalized observation of the current page."""
+        page = self.page
+        try:
+            snapshot_yaml = await page.aria_snapshot()
+            raw_elements = await page.evaluate(_SCAN_JS)
+            url = page.url
+            title = await page.title()
+            content = await page.content()
+            visible_text = await page.evaluate("() => document.body.innerText")
+        except PlaywrightError as exc:
+            raise ObservationError(
+                f"failed to observe page: {exc}",
+                category=FailureCategory.ENVIRONMENT_ERROR,
+            ) from exc
+
+        visual = None
+        if screenshot:
+            visual = await self._capture_screenshot()
+
+        observation = Observation(
+            observation_id=new_id("obs"),
+            sequence_number=self._next_sequence(),
+            visual=visual,
+            structural=StructuralObservation(
+                url=url,
+                title=title,
+                dom_hash=hashlib.sha256(content.encode("utf-8")).hexdigest(),
+                text_digest=_text_digest(visible_text),
+                viewport_width=self.settings.browser.viewport_width,
+                viewport_height=self.settings.browser.viewport_height,
+            ),
+            accessibility_tree=parse_aria_snapshot(snapshot_yaml),
+            interactive_elements=parse_scan(raw_elements),
+            environment=EnvironmentMetadata(
+                adapter_kind=self.kind,
+                adapter_version="playwright",
+                extra={"browser": self.settings.browser.browser},
+            ),
+        )
+        self._last_observation = observation
+        return observation
+
+    async def _capture_screenshot(self) -> ImageData | None:
+        page = self.page
+        try:
+            png = await page.screenshot(full_page=False)
+        except PlaywrightError as exc:
+            self._log.warning(
+                "screenshot.failed", extra={"extra_fields": {"error": str(exc)[:120]}}
+            )
+            return None
+        path: str | None = None
+        artifacts = self.settings.storage.artifacts_dir
+        try:
+            artifacts.mkdir(parents=True, exist_ok=True)
+            target = artifacts / f"{new_id('shot')}.png"
+            target.write_bytes(png)
+            path = str(target)
+        except OSError:
+            path = None
+        return ImageData.from_bytes(
+            png,
+            width=self.settings.browser.viewport_width,
+            height=self.settings.browser.viewport_height,
+            path=path,
+        )
+
+    def _next_sequence(self) -> int:
+        return (self._last_observation.sequence_number + 1) if self._last_observation else 0
+
+    # -- execution ------------------------------------------------------------
+
+    async def execute(self, action: Action) -> ActionResult:
+        """Apply *action*; action-level failures are returned, not raised."""
+        if not self.connected or self._page is None:
+            raise AdapterNotConnectedError("browser adapter is not connected")
+        started = time.perf_counter()
+        try:
+            await self._dispatch(action)
+            duration_ms = (time.perf_counter() - started) * 1000.0
+            return ActionResult(
+                action_id=action.action_id,
+                success=True,
+                duration_ms=duration_ms,
+                adapter_details={"browser": self.settings.browser.browser},
+            )
+        except PlaywrightTimeoutError as exc:
+            return ActionResult.failure(
+                action.action_id,
+                FailureCategory.TIMEOUT,
+                "action.timeout",
+                f"action timed out: {str(exc).splitlines()[0][:200]}",
+            )
+        except (ActionError, ActionValidationError, PermissionDeniedError) as exc:
+            return ActionResult.failure(
+                action.action_id,
+                exc.category,
+                exc.code,
+                exc.message,
+            )
+        except PlaywrightError as exc:
+            return ActionResult.failure(
+                action.action_id,
+                FailureCategory.ACTION_FAILED,
+                "action.playwright_error",
+                str(exc).splitlines()[0][:300],
+            )
+
+    async def _dispatch(self, action: Action) -> None:
+        import asyncio
+
+        if isinstance(action, ClickAction):
+            locator = await self.resolve_target(action.target, role_hint="button")
+            if action.double:
+                await locator.dblclick(button=action.button)
+            else:
+                await locator.click(button=action.button)
+        elif isinstance(action, TypeAction):
+            locator = await self.resolve_target(action.target)
+            await locator.fill(action.text)
+            if action.submit:
+                await locator.press("Enter")
+        elif isinstance(action, SelectAction):
+            locator = await self.resolve_target(action.target)
+            await locator.select_option(action.value)
+        elif isinstance(action, ScrollAction):
+            dy = {"up": -action.amount_px, "down": action.amount_px}.get(action.direction, 0)
+            dx = {"left": -action.amount_px, "right": action.amount_px}.get(action.direction, 0)
+            if action.target is not None:
+                locator = await self.resolve_target(action.target)
+                await locator.scroll_into_view_if_needed()
+            await self.page.mouse.wheel(dx, dy)
+        elif isinstance(action, HoverAction):
+            locator = await self.resolve_target(action.target)
+            await locator.hover()
+        elif isinstance(action, KeyPressAction):
+            await self.page.keyboard.press(action.key)
+            if action.hold_ms:
+                await asyncio.sleep(action.hold_ms / 1000)
+        elif isinstance(action, NavigateAction):
+            await self._goto(action.url)
+        elif isinstance(action, WaitAction):
+            await self.page.wait_for_timeout(action.milliseconds)
+        else:  # pragma: no cover - discriminated union is closed
+            raise ActionValidationError(
+                f"unsupported action kind: {type(action).__name__}",
+                context={"kind": getattr(action, "kind", "?")},
+            )
+
+    async def _goto(self, url: str) -> None:
+        if not url_allowed(url, allow_network=self.settings.security.allow_network):
+            raise PermissionDeniedError(
+                f"navigation to {url!r} requires allow_network=true",
+                context={"url": url},
+                suggestions=[
+                    "cc config: set security.allow_network=true",
+                    "or use a file:/// URL for local content",
+                ],
+            )
+        try:
+            await self.page.goto(url, wait_until="domcontentloaded")
+        except PlaywrightError as exc:
+            raise AdapterError(
+                f"navigation failed: {str(exc).splitlines()[0][:200]}",
+                category=FailureCategory.ENVIRONMENT_ERROR,
+            ) from exc
+
+    # -- target resolution ------------------------------------------------------
+
+    async def resolve_target(
+        self,
+        target: ActionTarget | None,
+        *,
+        role_hint: str | None = None,
+        _retried: bool = False,
+    ) -> Any:
+        """Resolve a semantic target to a Playwright locator.
+
+        Order: observation ``ref`` (role+name+ordinal) → explicit role+name →
+        selector → coordinates. When a ``ref`` misses the cached observation
+        (stale page, first action after navigation), the observation is
+        refreshed once and the lookup retried — the seed of Phase-6
+        re-anchoring: refs are positional, roles+names are semantic.
+        """
+        if target is None:
+            raise ActionValidationError("action has no target")
+        page = self.page
+
+        if target.ref:
+            element = (
+                self._last_observation.find_element(target.ref)
+                if self._last_observation is not None
+                else None
+            )
+            if element is None and not _retried:
+                # No cached observation, or it is stale (navigation since).
+                await self.observe(screenshot=False)
+                return await self.resolve_target(target, role_hint=role_hint, _retried=True)
+            if element is not None and self._ref_agrees(target, element):
+                locator = self._locator_for_element(page, element)
+                if locator is not None:
+                    return locator
+            # fall through when the ref is stale OR disagrees with the
+            # recorded semantics (drifted DOM renumbered the positional
+            # refs) — role+name below re-anchors to the right element.
+
+        if target.role or target.name:
+            role = str(target.role or role_hint or "button")
+            locator = page.get_by_role(cast("Any", role), name=target.name or "")
+            return locator.first if not target.name else locator
+
+        if target.selector:
+            return page.locator(target.selector).first
+
+        if target.coordinates is not None:
+            return page.locator("body")  # caller uses coordinates via mouse
+
+        raise ActionValidationError(
+            "target cannot be resolved",
+            context={"semantic_key": target.semantic_key()},
+        )
+
+    @staticmethod
+    def _ref_agrees(target: ActionTarget, element: Any) -> bool:
+        """True when the cached element for a ref matches the recorded
+        semantics. Recorded capabilities carry role+name alongside the ref;
+        when they disagree the DOM has drifted and the ref must not be
+        trusted (it now points at a different element)."""
+        if not target.role and not target.name:
+            return True  # ref-only targeting: nothing to cross-check
+        if target.role and element.role.lower() != target.role.lower():
+            return False
+        return not (target.name and target.name.lower() not in (element.name or "").lower())
+
+    def _locator_for_element(self, page: Page, element: Any) -> Any:
+        """Build a locator for a scanned element, disambiguated by ordinal."""
+        assert self._last_observation is not None
+        elements = self._last_observation.interactive_elements
+        same = [e for e in elements if e.role == element.role and e.name == element.name]
+        ordinal = same.index(element)
+        test_id = element.attributes.get("data-testid")
+        if test_id:
+            base = page.get_by_test_id(test_id)
+            if len(same) == 1:
+                return base
+        if element.name:
+            locator = page.get_by_role(cast("Any", element.role), name=element.name, exact=True)
+            if len(same) > 1:
+                locator = locator.nth(ordinal)
+            return locator
+        if element.attributes.get("id"):
+            return page.locator(f"[id='{element.attributes['id']}']")
+        if test_id:
+            return (
+                page.get_by_test_id(test_id).nth(ordinal)
+                if len(same) > 1
+                else page.get_by_test_id(test_id)
+            )
+        # Nameless element: tag + ordinal among same-tag elements.
+        tag = element.tag or element.role
+        same_tag = [e for e in elements if (e.tag or e.role) == tag]
+        return page.locator(tag).nth(same_tag.index(element))
+
+    def capabilities_description(self) -> list[str]:
+        return ["click", "type", "select", "scroll", "hover", "key_press", "navigate", "wait"]
+
+
+def register() -> None:
+    """Register the browser adapter (idempotent)."""
+    from capability_compiler.adapters.base import available_adapters, register_adapter
+
+    if "browser" not in available_adapters():
+        register_adapter(
+            "browser",
+            BrowserAdapter,
+            description="Playwright browser adapter (chromium/firefox/webkit)",
+        )
+
+
+__all__ = ["BrowserAdapter", "register", "url_allowed"]

capability_compiler/adapters/browser/aria.py

@@ -0,0 +1,147 @@
+"""Parser for Playwright's ``aria_snapshot()`` YAML format.
+
+Empirically validated against Playwright 1.62 (2026-09-01). The format is
+line-oriented YAML, two-space indentation per level::
+
+    - heading "Documents" [level=1]
+    - button "Export"
+    - textbox "Search":
+      - /placeholder: Search docs
+    - combobox:
+      - option "PDF" [selected]
+      - option "PNG"
+
+Grammar per line::
+
+    "- " <role> [ '"' <name> '"' ] [ '[' <attr>* ']' ] [ ':' [ ' ' <text> ] ]
+
+where ``attr`` is ``key=value`` or a bare flag (``selected``, ``disabled``,
+``checked``, ``expanded``, ``invalid``, ``level=N``, ``pressed``). Children
+beginning with ``/`` are pseudo-attributes (``/url``, ``/placeholder``).
+
+The parser is dependency-free and deterministic: same input → identical
+:class:`~capability_compiler.models.AccessibilityNode` tree. It never
+executes or evaluates anything from the snapshot (page content is untrusted
+data — see docs/security).
+"""
+
+from __future__ import annotations
+
+import re
+
+from capability_compiler.errors import ObservationError
+from capability_compiler.models import AccessibilityNode
+
+_LINE_RE = re.compile(r"""^(?P<prefix>[-\s]*)- (?P<rest>.*)$""")
+_ATTR_RE = re.compile(r"\[([^\]]*)\]")
+
+
+def parse_aria_snapshot(snapshot_yaml: str) -> AccessibilityNode:
+    """Parse an aria snapshot into a normalized tree (virtual root included).
+
+    The returned root node has ``role="root"``; children are the top-level
+    page nodes in document order.
+
+    Raises:
+        ObservationError: on structurally invalid input (never on merely
+            unknown roles or attributes — forward compatible).
+    """
+    root = AccessibilityNode(role="root", name="")
+    # Stack of (indent_level, node). Root sits at level -1 conceptually.
+    stack: list[tuple[int, AccessibilityNode]] = [(-1, root)]
+    for line_number, raw_line in enumerate(snapshot_yaml.splitlines(), start=1):
+        if not raw_line.strip():
+            continue
+        match = _LINE_RE.match(raw_line)
+        if not match or not raw_line.lstrip().startswith("-"):
+            msg = f"unparseable aria snapshot line {line_number}: {raw_line[:80]!r}"
+            raise ObservationError(msg, context={"line": line_number})
+        indent = len(match.group("prefix").replace("-", "", 1))
+        if indent % 2 != 0:
+            msg = f"odd indentation on line {line_number}"
+            raise ObservationError(msg, context={"line": line_number})
+        level = indent // 2
+
+        node, parent = _parse_node(match.group("rest"), line_number)
+        while stack and stack[-1][0] >= level:
+            stack.pop()
+        if not stack:
+            msg = f"indentation skips a level on line {line_number}"
+            raise ObservationError(msg, context={"line": line_number})
+        parent = stack[-1][1]
+        parent.children.append(node)
+        stack.append((level, node))
+    return root
+
+
+def _parse_node(rest: str, line_number: int) -> tuple[AccessibilityNode, AccessibilityNode]:
+    """Parse the text after ``- `` into a node; returns (node, dummy_parent)."""
+    text_after_colon: str | None = None
+    if ":" in rest:
+        # The colon separates node header from its text content (or a
+        # child-bearing marker when nothing follows).
+        head, _, tail = rest.partition(":")
+        text_after_colon = tail.strip() or None
+        rest = head.rstrip()
+
+    role = rest
+    name = ""
+    properties: dict[str, object] = {}
+
+    # Quoted name after the role.
+    name_match = re.search(r' "([^"]*)"', rest)
+    if name_match:
+        name = name_match.group(1)
+        role = (rest[: name_match.start()] + rest[name_match.end() :]).strip()
+
+    # Bracketed attributes (may be several: [level=1][disabled] is unusual
+    # but legal; Playwright emits combined [a] [b] forms).
+    attr_blob = " ".join(_ATTR_RE.findall(role) or [])
+    role = _ATTR_RE.sub(" ", role).strip()
+    for part in attr_blob.split():
+        if "=" in part:
+            key, _, value = part.partition("=")
+            properties[key] = _coerce(value)
+        else:
+            properties[part] = True
+
+    if not role:
+        msg = f"missing role on line {line_number}"
+        raise ObservationError(msg, context={"line": line_number})
+
+    if text_after_colon is not None and "text" not in properties:
+        properties["text"] = text_after_colon
+
+    node = AccessibilityNode(role=role, name=name, properties=properties)
+    return node, node
+
+
+def _coerce(value: str) -> object:
+    if value.lower() in {"true", "false"}:
+        return value.lower() == "true"
+    try:
+        return int(value)
+    except ValueError:
+        return value
+
+
+def format_node_line(node: AccessibilityNode) -> str:
+    """Render one node back to snapshot-line form (debugging/tests only)."""
+    parts = [node.role]
+    if node.name:
+        parts.append(f'"{node.name}"')
+    flags = []
+    for key, value in sorted(node.properties.items()):
+        if value is True:
+            flags.append(key)
+        elif value is not False and key != "text":
+            flags.append(f"{key}={value}")
+    line = "- " + " ".join(parts)
+    if flags:
+        line += " [" + " ".join(flags) + "]"
+    if node.properties.get("text"):
+        line += f": {node.properties['text']}"
+    return line
+
+
+__all__ = ["format_node_line", "parse_aria_snapshot"]