pi-lean-portal 0.1.0

package/backends/python-base/pi_browser_bridge/__init__.py

@@ -0,0 +1,71 @@
+"""
+pi_browser_bridge — Shared Python bridge library for pi-lean-portal.
+
+Provides the infrastructure needed to build Python browser automation
+backends that communicate with the TypeScript ``PythonPluginAdapter``
+via JSON-RPC 2.0 over stdin/stdout.
+
+Key components
+--------------
+* :class:`BrowserBridge` — base class; subclass and override
+  ``create_browser_session()`` and operation methods.
+* :class:`PlaywrightBridge` — Playwright-specific base extracted from
+  the Chromium reference; parameterizes engine, UA, and launch args.
+* :mod:`.transport` — JSON-RPC 2.0 transport over stdin/stdout.
+* :mod:`.accessibility` — Playwright accessibility snapshot parser,
+  mirroring the TypeScript version.
+* :mod:`.bot_detection` — anti-automation / bot detection signal
+  matcher, mirroring the TypeScript version.
+
+Shipped bridges
+---------------
+* ``backends/chromium-py/bridge.py`` — ``ChromiumPyBridge``, a thin
+  subclass of :class:`PlaywrightBridge` driving Chromium.  Ships as the
+  parity reference for Python Chromium-based stealth backends.
+* ``backends/firefox-py/bridge.py`` — ``FirefoxPyBridge``, a thin
+  subclass driving Firefox.  Ships as the parity reference for Python
+  Firefox-based stealth backends.
+
+Quick start
+-----------
+::
+
+    from pi_browser_bridge import BrowserBridge
+
+    class MyBridge(BrowserBridge):
+        def create_browser_session(self, task_id, config):
+            # launch browser, return session dict
+            ...
+        def do_navigate(self, task_id, url, timeout_ms):
+            # navigate, return result dict
+            ...
+
+    if __name__ == "__main__":
+        MyBridge().run()
+"""
+
+from .bridge import BrowserBridge, SessionNotFoundError, InvalidParamsError
+from .playwright_base import PlaywrightBridge
+from .accessibility import (
+    AriaCachedNode,
+    AriaParseResult,
+    parse_snapshot,
+    build_locator_args,
+    INTERACTIVE_ROLES,
+    INFORMATIONAL_ROLES,
+)
+from .bot_detection import check_bot_detection
+
+__all__ = [
+    "BrowserBridge",
+    "PlaywrightBridge",
+    "SessionNotFoundError",
+    "InvalidParamsError",
+    "AriaCachedNode",
+    "AriaParseResult",
+    "parse_snapshot",
+    "build_locator_args",
+    "INTERACTIVE_ROLES",
+    "INFORMATIONAL_ROLES",
+    "check_bot_detection",
+]

package/backends/python-base/pi_browser_bridge/accessibility.py

@@ -0,0 +1,408 @@
+"""
+Accessibility tree utilities for the Python bridge.
+
+Parses Playwright's page.aria_snapshot() output into an
+LLM-friendly text format with @e1, @e2 element references.  Caches
+parsed nodes so the TypeScript adapter can map interactions back via
+get_by_role().
+
+Mirrors the logic in core/shared/accessibility-tree.ts.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ─── Role classification sets ─────────────────────────────────────────
+
+INTERACTIVE_ROLES: set[str] = {
+    "button",
+    "link",
+    "textbox",
+    "searchbox",
+    "combobox",
+    "checkbox",
+    "radio",
+    "heading",
+    "listbox",
+    "option",
+    "menuitem",
+    "menuitemcheckbox",
+    "menuitemradio",
+    "tab",
+    "treeitem",
+    "switch",
+    "slider",
+    "spinbutton",
+    "progressbar",
+    "meter",
+    "scrollbar",
+    "gridcell",
+    "cell",
+    "columnheader",
+    "rowheader",
+    "tabpanel",
+    "img",
+    "figure",
+    "listitem",
+    "dialog",
+    "alertdialog",
+    "tooltip",
+    "navigation",
+    "banner",
+    "form",
+    "search",
+    "toolbar",
+    "menu",
+    "menubar",
+    "note",
+    "alert",
+    "status",
+    "list",
+    "table",
+    "grid",
+    "treegrid",
+    "article",
+    "section",
+    "blockquote",
+    "code",
+}
+
+INFORMATIONAL_ROLES: set[str] = {
+    "paragraph",
+    "text",
+    "group",
+    "region",
+    "main",
+    "complementary",
+    "contentinfo",
+    "definition",
+    "term",
+    "math",
+    "marquee",
+    "timer",
+    "log",
+    "deletion",
+    "insertion",
+    "mark",
+    "suggestion",
+    "comment",
+}
+
+
+# ─── Data structures ──────────────────────────────────────────────────
+
+@dataclass
+class AriaCachedNode:
+    ref: str
+    role: str
+    name: str
+    props: list[str]
+    depth: int
+    raw: str
+    occurrence_index: int = 0
+    """0-based position among siblings with same role+name in the snapshot."""
+    parent_ref: Optional[str] = None
+    """Ref of the nearest interactive ancestor (for subtree queries)."""
+
+
+@dataclass
+class AriaParseResult:
+    text: str
+    elements: dict[str, AriaCachedNode] = field(default_factory=dict)
+    count: int = 0
+
+
+# ─── Role icons (same mapping as TypeScript) ───────────────—──────────
+
+_ROLE_ICONS: dict[str, str] = {
+    "button": "\U0001f518 ",        # 🔘
+    "link": "\U0001f517 ",          # 🔗
+    "textbox": "\U0001f4dd ",       # 📝
+    "searchbox": "\U0001f50d ",     # 🔍
+    "combobox": "\U0001f4cb ",      # 📋
+    "checkbox": "\u2611 ",          # ☑
+    "radio": "\u25cb ",             # ○
+    "heading": "\U0001f4cc ",       # 📌
+    "listbox": "\U0001f4cb ",       # 📋
+    "option": "\u2022 ",            # •
+    "tab": "\U0001f4d1 ",           # 📑
+    "switch": "\U0001f500 ",        # 🔀
+    "slider": "\U0001f527 ",        # 🔧
+    "spinbutton": "\U0001f522 ",    # 🔢
+    "img": "\U0001f5bc ",          # 🖼
+    "figure": "\U0001f5bc ",       # 🖼
+    "table": "\U0001f4ca ",         # 📊
+    "grid": "\U0001f4ca ",          # 📊
+    "gridcell": "\u25ab ",          # ▫
+    "cell": "\u25ab ",              # ▫
+    "dialog": "\U0001f4ac ",        # 💬
+    "alertdialog": "\u26a0 ",       # ⚠
+    "navigation": "\U0001f9ed ",    # 🧭
+    "banner": "\U0001f4f0 ",        # 📰
+    "main": "\U0001f4c4 ",          # 📄
+    "complementary": "\U0001f4ce ", # 📎
+    "contentinfo": "\u2139 ",       # ℹ
+    "form": "\U0001f4dd ",          # 📝
+    "search": "\U0001f50d ",        # 🔍
+    "group": "\U0001f4e6 ",         # 📦
+    "toolbar": "\U0001f527 ",       # 🔧
+    "treeitem": "\u2022 ",          # •
+    "menu": "\U0001f4cb ",          # 📋
+    "menubar": "\U0001f4cb ",       # 📋
+    "paragraph": "\U0001f4c3 ",     # 📃
+    "article": "\U0001f4f0 ",       # 📰
+    "section": "\U0001f4c4 ",       # 📄
+    "list": "\U0001f4cb ",          # 📋
+    "listitem": "\u2022 ",          # •
+    "note": "\U0001f4dd ",          # 📝
+    "alert": "\U0001f514 ",         # 🔔
+    "status": "\U0001f4ca ",        # 📊
+    "code": "\U0001f4bb ",          # 💻
+    "blockquote": "\U0001f4ac ",   # 💬
+    "columnheader": "\U0001f4ca ", # 📊
+    "comment": "\U0001f4ac ",      # 💬
+    "definition": "\U0001f4d6 ",   # 📖
+    "deletion": "\u274c ",         # ❌
+    "insertion": "\u2795 ",        # ➕
+    "log": "\U0001f4cb ",          # 📋
+    "mark": "\U0001f58d \ufe0f ", # 🖍️
+    "marquee": "\U0001f4dc ",      # 📜
+    "math": "\U0001f9ee ",         # 🧮
+    "menuitem": "\U0001f4cb ",    # 📋
+    "menuitemcheckbox": "\u2611 ",  # ☑
+    "menuitemradio": "\u25cb ",    # ○
+    "meter": "\U0001f4ca ",        # 📊
+    "progressbar": "\u23f3 ",      # ⏳
+    "region": "\U0001f4e6 ",        # 📦
+    "rowheader": "\U0001f4ca ",    # 📊
+    "scrollbar": "\U0001f4dc ",    # 📜
+    "suggestion": "\U0001f4a1 ",   # 💡
+    "tabpanel": "\U0001f4d1 ",     # 📑
+    "term": "\U0001f4d6 ",         # 📖
+    "text": "\U0001f4dd ",         # 📝
+    "timer": "\u23f1 \ufe0f ",    # ⏱️
+    "tooltip": "\U0001f4a1 ",      # 💡
+    "treegrid": "\U0001f4ca ",     # 📊
+}
+
+
+def _role_icon(role: str) -> str:
+    return _ROLE_ICONS.get(role, "")
+
+
+def _truncate(s: str, max_len: int) -> str:
+    if len(s) <= max_len:
+        return s
+    return s[: max_len - 1] + "\u2026"  # …
+
+
+# ─── Line parser ──────────────────────────────────────────────────────
+
+@dataclass
+class _ParsedLine:
+    role: str
+    name: str
+    props: list[str]
+
+
+def _parse_line(line: str) -> Optional[_ParsedLine]:
+    """Parse a single line from the accessibility snapshot YAML-like output.
+
+    Expected format::
+
+        - role "name" [prop1, prop2]
+        - role "name":
+        - role : text content
+
+    Returns None if the line is not a recognised element line.
+    """
+    if not line.startswith("- "):
+        return None
+    content = line[2:].strip()
+
+    # Extract bracketed props like [level=1, checked]
+    props: list[str] = []
+    cleaned = re.sub(r"\[([^\]]+)\]", lambda m: props.append(m.group(1).strip()) or "", content).strip()
+
+    match = re.match(r"^([a-zA-Z_-]+)\s*", cleaned)
+    if not match:
+        return None
+
+    role = match.group(1).lower()
+    remainder = cleaned[match.end():].strip()
+    name = ""
+
+    # Quoted name: "name" or "name":
+    qmatch = re.match(r'^"((?:[^"\\]|\\.)*)"\s*:?\s*', remainder)
+    if qmatch:
+        name = qmatch.group(1)
+    else:
+        # Colon-text format: : text content
+        tmatch = re.match(r"^:\s*(.*)", remainder)
+        if tmatch:
+            name = tmatch.group(1).strip()[:100]
+
+    return _ParsedLine(role=role, name=name, props=props)
+
+
+# ─── Main parser ──────────────────────────────────────────────────────
+
+def parse_snapshot(snap: str) -> AriaParseResult:
+    """Parse the YAML-like output of Playwright's page.aria_snapshot().
+
+    Single-pass parser that assigns @e refs sequentially to all interactive
+    elements in DOM order.  Every interactive element gets a ref —
+    no cap, no dialog prioritisation.
+
+    Full ARIA trees beyond truncation are cached to disk by the router,
+    so there is no need to budget or prioritise ref allocations.
+
+    Mirrors the TypeScript ``parseSnapshot()`` in
+    ``core/shared/accessibility-tree.ts``.
+
+    Args:
+        snap: The raw snapshot string.
+
+    Returns:
+        An AriaParseResult with formatted text, element cache, and count.
+    """
+    lines = snap.split("\n")
+    elements: dict[str, AriaCachedNode] = {}
+    out_lines: list[str] = []
+    ref_counter = 0
+    occurrence_tracker: dict[str, int] = {}
+    # Depth-based parent stack — tracks the most recent interactive ref at each depth
+    parent_stack: list[str] = []
+
+    for raw_line in lines:
+        if not raw_line.strip():
+            continue
+
+        depth = _count_leading_spaces(raw_line)
+        trimmed = raw_line.strip()
+
+        # Property lines (start with /) — pass through as-is
+        if trimmed.startswith("/"):
+            out_lines.append(raw_line)
+            continue
+
+        parsed = _parse_line(trimmed)
+        if parsed is None:
+            out_lines.append(raw_line)
+            continue
+
+        role = parsed.role
+        name = parsed.name
+        props = parsed.props
+
+        # Informational roles: show in tree but no @e ref
+        if role in INFORMATIONAL_ROLES:
+            indent = "  " * depth
+            icon = _role_icon(role)
+            name_part = f' "{_truncate(name, 80)}"' if name else ""
+            out_lines.append(f"{indent}{icon}{role}{name_part}")
+            continue
+
+        # Non-interactive — skip entirely
+        if role not in INTERACTIVE_ROLES:
+            out_lines.append(raw_line)
+            continue
+
+        ref_counter += 1
+        ref = f"e{ref_counter}"
+        occ_key = f"{role}||{name}"
+        occurrence_index = occurrence_tracker.get(occ_key, 0)
+        occurrence_tracker[occ_key] = occurrence_index + 1
+
+        # Parent stack: trim entries past current depth
+        while len(parent_stack) > depth:
+            parent_stack.pop()
+
+        # Determine parentRef from the element at depth-1 (if any)
+        parent_ref: Optional[str] = None
+        if len(parent_stack) >= depth and depth > 0:
+            parent_ref = parent_stack[depth - 1]
+
+        # Push this ref onto the parent stack at its depth
+        parent_stack.append(ref)
+
+        node = AriaCachedNode(
+            ref=ref,
+            role=role,
+            name=name,
+            props=props,
+            depth=depth,
+            raw=trimmed,
+            occurrence_index=occurrence_index,
+            parent_ref=parent_ref,
+        )
+        elements[ref] = node
+
+        indent = "  " * depth
+        icon = _role_icon(role)
+        ref_tag = f"@{ref}"
+        name_part = f' "{_truncate(name, 80)}"' if name else ""
+        prop_str = f" [{', '.join(props)}]" if props else ""
+
+        out_lines.append(f"{indent}{ref_tag} {icon}{role}{name_part}{prop_str}")
+
+    return AriaParseResult(
+        text="\n".join(out_lines),
+        elements=elements,
+        count=len(elements),  # refs assigned, matching TS semantics
+    )
+
+
+# ─── Helpers ──────────────────────────────────────────────────────────
+
+def _count_leading_spaces(s: str) -> int:
+    match = re.match(r"^(\s*)", s)
+    return len(match.group(1)) if match else 0
+
+
+def build_locator_args(node: AriaCachedNode) -> tuple[str, dict]:
+    """Build get_by_role arguments from a cached node.
+
+    Returns (role, kwargs), suitable for use as::
+
+        page.get_by_role(role, **kwargs)
+
+    The kwargs dict includes an ``occurrenceIndex`` key that callers should
+    always pass to ``.nth(n)`` on the locator to avoid strict-mode violations
+    from duplicate role+name elements."""
+    kwargs: dict = {}
+
+    if node.name:
+        kwargs["name"] = node.name
+        kwargs["exact"] = len(node.name) < 60
+
+    for prop in node.props:
+        eq_idx = prop.find("=")
+        if eq_idx > 0:
+            key = prop[:eq_idx]
+            val = prop[eq_idx + 1:]
+            if key == "level":
+                kwargs["level"] = int(val)
+            elif key == "checked":
+                kwargs["checked"] = "mixed" if val == "mixed" else True
+            elif key == "expanded":
+                kwargs["expanded"] = val == "true"
+            elif key == "pressed":
+                kwargs["pressed"] = "mixed" if val == "mixed" else True
+            elif key == "selected":
+                kwargs["selected"] = val == "true"
+        else:
+            if prop == "checked":
+                kwargs["checked"] = True
+            elif prop == "expanded":
+                kwargs["expanded"] = True
+            elif prop == "pressed":
+                kwargs["pressed"] = True
+            elif prop == "selected":
+                kwargs["selected"] = True
+            elif prop == "disabled":
+                kwargs["disabled"] = True
+
+    kwargs["occurrenceIndex"] = node.occurrence_index
+    return node.role, kwargs

package/backends/python-base/pi_browser_bridge/bot_detection.py

@@ -0,0 +1,115 @@
+"""
+Bot detection for the Python bridge.
+
+Mirrors the logic in ``core/shared/bot-detection.ts`` ``checkPage()``.
+
+The matching *must* run in the Python process because it needs
+``page.title()`` and ``page.evaluate()`` for body/HTML — shipping the
+full HTML across JSON-RPC would be prohibitively expensive.  However,
+the signal lists are pure data and live here as a single source of
+truth for all Python-based browser backends.
+"""
+
+import re
+from typing import Any
+
+#: Block-level signals — checked against BOTH title and body text.
+#: Mirror of TypeScript bot-detection.ts BLOCK_SIGNALS.
+#: Only specific challenge phrases are included — generic single words
+#: like "captcha", "cloudflare", "recaptcha" are excluded because they
+#: cause false positives on legitimate pages mentioning them in passing.
+_BLOCK_SIGNALS: tuple[str, ...] = (
+    "please verify you are human",
+    "attention required!",
+    "just a moment...",
+    "checking your browser",
+    "you have been blocked",
+    "sorry, you have been blocked",
+    "verify you are human",
+    "your request has been blocked",
+    "we are checking your browser",
+    "cf-challenge",
+    "_cf_chl_opt",
+    "cdn-cgi/challenge",
+)
+
+#: Body-only string signals — high-specificity CDN patterns.
+#: Mirror of TypeScript bot-detection.ts BODY_ONLY_SIGNALS.
+_BODY_ONLY_SIGNALS: tuple[str, ...] = (
+    "errors.edgesuite.net",
+    "you don't have permission to access",
+)
+
+#: Body-only regex patterns — checked against raw body text.
+#: Mirror of TypeScript bot-detection.ts BODY_ONLY_PATTERNS.
+_BODY_ONLY_PATTERNS: tuple[re.Pattern, ...] = (
+    re.compile(r"reference\s*#[a-f0-9]+(?:\.[a-f0-9]+)+", re.IGNORECASE),
+)
+
+#: HTML-level CAPTCHA/widget signals (Python-only enhancement).
+_HTML_SIGNALS: tuple[str, ...] = (
+    "recaptcha",
+    "hcaptcha",
+    "turnstile",
+    "g-recaptcha",
+    "data-sitekey",
+)
+
+
+def check_bot_detection(page: Any) -> bool:
+    """Check for anti-automation / bot detection signals in the current page.
+
+    Mirrors the logic in ``bot-detection.ts`` ``checkPage()``.
+
+    Args:
+        page: A Playwright sync Page object (or a mock with ``title()``
+              and ``evaluate()`` methods).
+
+    Returns:
+        True if bot detection signals were found.
+    """
+    try:
+        title: str = page.title().lower()
+    except Exception:
+        title = ""
+
+    try:
+        body_text: str = page.evaluate(
+            "() => document.body?.innerText || ''"
+        ) or ""
+        body_text = body_text.lower()
+    except Exception:
+        body_text = ""
+
+    try:
+        html: str = page.evaluate(
+            "() => document.documentElement?.innerHTML || ''"
+        ) or ""
+        html = html.lower()
+    except Exception:
+        html = ""
+
+    # ── Block signals: checked against both title and body ───────
+    for signal in _BLOCK_SIGNALS:
+        if signal in title or signal in body_text:
+            return True
+
+    # ── Body-only string signals ────────────────────────────────
+    for signal in _BODY_ONLY_SIGNALS:
+        if signal in body_text:
+            return True
+
+    # ── Body-only regex patterns ────────────────────────────────
+    for pattern in _BODY_ONLY_PATTERNS:
+        if pattern.search(body_text):
+            return True
+
+    # ── HTML-level signals (Python-only enhancement) ────────────
+    for signal in _HTML_SIGNALS:
+        if signal in html:
+            return True
+
+    return False
+
+
+__all__ = ["check_bot_detection"]