stealth-browserctl 0.0.1__py3-none-any.whl

backend/__init__.py

@@ -0,0 +1,18 @@
+"""Backend package for browserctl daemon."""
+
+from .daemon_server.server import StealthDaemon
+from .flow import(
+    CookieAttributes,
+    ResponseCookie,
+    RequestSummary,
+    RequestDetails,Request
+)
+__all__ = [
+    "StealthDaemon",
+    "CookieAttributes",
+    "ResponseCookie",
+    "RequestSummary",
+    "RequestDetails","Request"
+    ]
+
+

backend/constants.py

@@ -0,0 +1,20 @@
+"""Configuration constants for browserctl daemon."""
+
+from pathlib import Path
+
+# Base directory for daemon files
+DAEMON_DIR = Path.home() / ".browserctl"
+
+# Base directory for v2ray bin
+DEFAULT_V2RAY_INSTALL_PATH = DAEMON_DIR / "v2ray"
+
+# Socket path for IPC (cross-platform)
+# Unix: UDS (Unix Domain Socket)
+# Windows: Named Pipe
+DEFAULT_SOCKET_PATH = DAEMON_DIR / "daemon.sock"
+
+# PID file for tracking daemon process
+PID_FILE = DAEMON_DIR / "daemon.pid"
+
+# Authentication key for IPC connection
+AUTH_KEY = b'browserctl-daemon-v1'

backend/daemon_client.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""
+module of Stealth CLI Daemon Client, it's for communicating with the daemon server using multiprocessing.connection.
+"""
+
+import subprocess
+import time
+from multiprocessing.connection import Client
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from loguru import logger
+from backend.constants import DEFAULT_SOCKET_PATH, AUTH_KEY
+from backend.daemon_server.models import DaemonRequest, DaemonResponse
+
+
+class DaemonClient:
+    """Client for communicating with the daemon server using multiprocessing.connection (cross-platform)."""
+    def __init__(self, socket_path: Optional[Path] = None):
+        self.socket_path = socket_path or DEFAULT_SOCKET_PATH
+
+    def is_daemon_running(self) -> bool:
+        """Check if daemon is running."""
+        # On Unix, check if socket file exists
+        # On Windows, Named Pipes don't create files
+        if self.socket_path.exists():
+            return True
+        
+        # Try to connect (works on both platforms)
+        try:
+            client = Client(str(self.socket_path), authkey=AUTH_KEY)
+            client.close()
+            return True
+        except:
+            return False
+
+    def send_request(
+        self,
+        command: str,
+        args: Optional[Dict[str, Any]] = None,
+        session: Optional[str] = None,
+        timeout: float = 30.0
+    ) -> Any:
+        """Send a request to the daemon."""
+        # Create structured request (defaults handled by Pydantic model)
+        request_data = {'command': command}
+        if args is not None:
+            request_data['args'] = args
+        if session is not None:
+            request_data['session'] = session
+        
+        request = DaemonRequest(**request_data)
+
+        try:
+            # Connect to daemon (cross-platform)
+            client = Client(str(self.socket_path), authkey=AUTH_KEY)
+
+            # Send request (auto-serialization)
+            client.send(request.model_dump())
+
+            # Receive response (auto-deserialization)
+            response = client.recv()
+
+            client.close()
+
+            # Parse response
+            resp = DaemonResponse(**response)
+            
+            if not resp.success:
+                raise RuntimeError(resp.error or 'Unknown error')
+
+            return resp.result
+
+        except Exception as e:
+            raise RuntimeError(f"Failed from daemon: {e}")
+
+    def start_daemon(self) -> None:
+        """Start the daemon if not running."""
+        if self.is_daemon_running():
+            logger.debug("Daemon is already running")
+            return
+
+        # Start daemon using subprocess
+        import sys
+        daemon_script = Path(__file__).parent / "daemon_server.py"
+
+        subprocess.run(
+            [sys.executable, str(daemon_script), "start"],
+            check=True
+        )
+
+        # Wait for daemon to start
+        for _ in range(20):
+            if self.is_daemon_running():
+                logger.info("Daemon started")
+                return
+            time.sleep(0.5)
+
+        raise RuntimeError("Failed to start daemon")
+
+    def stop_daemon(self) -> None:
+        """Stop the daemon."""
+        import sys
+        daemon_script = Path(__file__).parent / "daemon_server.py"
+
+        subprocess.run(
+            [sys.executable, str(daemon_script), "stop"],
+            check=True
+        )

backend/daemon_server/README.md

@@ -0,0 +1,143 @@
+# Daemon Server Module Structure
+
+## Overview
+
+The daemon server has been refactored from a single 1268-line file into a well-organized module structure for better maintainability and code organization.
+
+## Module Structure
+
+```
+src/backend/daemon_server/
+├── __init__.py              # Module exports
+├── base_handler.py          # Base command handler class
+├── server.py                # Main daemon server
+├── core_commands.py         # Core browser commands (open, close, goto, etc.)
+├── interaction_commands.py  # Interaction commands (click, fill, type, etc.)
+├── navigation_commands.py   # Navigation commands (tabs, back, forward, etc.)
+├── input_commands.py        # Input commands (keyboard, mouse)
+├── dialog_commands.py       # Dialog commands (accept, dismiss)
+├── storage_commands.py      # Storage commands (cookies, localStorage, sessionStorage)
+└── session_commands.py      # Session management commands
+```
+
+## Architecture
+
+### Command Handler Pattern
+
+Each command category is implemented as a separate handler class:
+
+```python
+class CommandHandler:
+    """Base class for command handlers."""
+    
+    def can_handle(self, command: str) -> bool:
+        """Check if this handler can handle the command."""
+        raise NotImplementedError
+    
+    def execute(self, session, command: str, args: Dict[str, Any]) -> Any:
+        """Execute the command."""
+        raise NotImplementedError
+```
+
+### Handler Categories
+
+1. **CoreCommands** - Basic browser operations
+   - `open`, `close`, `goto`, `snapshot`, `screenshot`, `pdf`, `resize`, `eval`
+
+2. **InteractionCommands** - Element interactions
+   - `click`, `dblclick`, `type`, `fill`, `press`, `hover`, `drag`, `select`, `upload`, `check`, `uncheck`
+
+3. **NavigationCommands** - Navigation control
+   - `go_back`, `go_forward`, `reload`, `new_tab`, `list_tab`, `close_tab`, `select_tab`
+
+4. **InputCommands** - Keyboard and mouse input
+   - `keydown`, `keyup`, `mousemove`, `mousedown`, `mouseup`, `mousewheel`
+
+5. **DialogCommands** - Alert/dialog handling
+   - `dialog_accept`, `dialog_dismiss`
+
+6. **StorageCommands** - Storage management
+   - State: `state_save`, `state_load`
+   - Cookies: `cookie_list`, `cookie_get`, `cookie_set`, `cookie_delete`, `cookie_clear`
+   - LocalStorage: `localstorage_list`, `localstorage_get`, `localstorage_set`, `localstorage_delete`, `localstorage_clear`
+   - SessionStorage: `sessionstorage_list`, `sessionstorage_get`, `sessionstorage_set`, `sessionstorage_delete`, `sessionstorage_clear`
+
+7. **SessionCommands** - Session management
+   - `list_sessions`, `close_all`, `kill_all`, `delete_data`
+
+### Main Server
+
+The `StealthDaemon` class in `server.py`:
+- Manages the Unix socket server
+- Handles client connections
+- Routes commands to appropriate handlers
+- Manages browser sessions via `BrowserManager`
+
+```python
+class StealthDaemon:
+    def __init__(self):
+        self.browser_manager = BrowserManager()
+        self.handlers = [
+            CoreCommands(),
+            InteractionCommands(),
+            NavigationCommands(),
+            InputCommands(),
+            DialogCommands(),
+            StorageCommands(),
+            SessionCommands(self.browser_manager),
+        ]
+    
+    def _execute_command(self, session, command: str, args: Dict[str, Any]) -> Any:
+        """Execute a command on a browser session."""
+        for handler in self.handlers:
+            if handler.can_handle(command):
+                return handler.execute(session, command, args)
+        raise ValueError(f"Unknown command: {command}")
+```
+
+## Usage
+
+The module is used exactly the same way as before:
+
+```python
+from backend.daemon_server import StealthDaemon
+
+daemon = StealthDaemon()
+daemon.start()
+```
+
+## Adding New Commands
+
+To add a new command:
+
+1. Identify the appropriate handler category
+2. Add the command to the `COMMANDS` list
+3. Implement the `_cmd_<command>` method
+4. Test the command
+
+Example:
+
+```python
+# In interaction_commands.py
+
+class InteractionCommands(CommandHandler):
+    COMMANDS = [
+        'click', 'dblclick', 'type', 'fill', 'press',
+        'hover', 'drag', 'select', 'upload', 'check', 'uncheck',
+        'new_command'  # Add here
+    ]
+    
+    def _cmd_new_command(self, session, args: Dict[str, Any]) -> None:
+        """New command implementation."""
+        # Implementation here
+        pass
+```
+
+## Future Improvements
+
+1. **Add Type Hints**: Add comprehensive type annotations
+2. **Add Docstrings**: Improve documentation for each method
+3. **Add Unit Tests**: Create tests for each handler
+4. **Add Logging**: Add more detailed logging
+5. **Add Validation**: Add input validation for commands
+6. **Add Error Handling**: Improve error messages and recovery

backend/daemon_server/__init__.py

@@ -0,0 +1,6 @@
+from .models import DaemonRequest
+
+__all__ = [
+    'DaemonRequest',
+]
+

backend/daemon_server/browser/__init__.py

@@ -0,0 +1,17 @@
+from .browser import BrowserManager,BrowserSession
+from .ariasnapshot import AriaSnapshotManager
+from .session_config  import (
+    SessionConfig,
+    BrowserConfig,
+    TimeoutsConfig,
+)
+
+
+__all__ = [
+    "BrowserManager","BrowserSession",
+    "AriaSnapshotManager",
+    "SessionConfig",
+    "BrowserConfig",
+    "TimeoutsConfig",
+
+]

backend/daemon_server/browser/ariasnapshot/__init__.py

@@ -0,0 +1,11 @@
+"""
+Playwright ariaSnapshot tool - Capture and validate accessibility trees.
+"""
+
+from .manager import AriaSnapshotManager
+
+__version__ = '1.0.0'
+
+__all__ = [
+    'AriaSnapshotManager',
+]

backend/daemon_server/browser/ariasnapshot/aria/__init__.py

@@ -0,0 +1,22 @@
+"""
+ARIA snapshot generation and rendering.
+"""
+
+from .types import (
+    AriaBox, ScrollInfo, AriaExtraProps, AriaNode, AriaSnapshot,
+    AriaTreeOptions
+)
+from .base import AriaTreeGenerator, AriaTreeResult
+from .generator_dom import DOMAriaTreeGenerator
+
+__all__ = [
+    # Types
+    'AriaBox', 'ScrollInfo', 'AriaExtraProps', 'AriaNode', 'AriaSnapshot',
+    'AriaTreeOptions',
+
+    # Base classes
+    'AriaTreeGenerator', 'AriaTreeResult',
+
+    # Generators
+    'DOMAriaTreeGenerator'
+]

backend/daemon_server/browser/ariasnapshot/aria/base.py

@@ -0,0 +1,123 @@
+"""
+Base Aria Tree Generator - Abstract interface for accessibility tree generation.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Union, Optional, Any, List
+from dataclasses import dataclass
+import json
+from .types import AriaTreeOptions, AriaSnapshot, AriaNode
+
+
+# Helper functions for working with TypedDict
+
+
+def is_node_interactable(node: AriaNode) -> bool:
+    """
+    Check if a node is interactable.
+
+    Args:
+        node: The AriaNode to check
+
+    Returns:
+        True if the node is interactable, False otherwise
+    """
+    # Check if disabled
+    if node.get('disabled'):
+        return False
+
+    # Check if visible
+    box = node.get('box')
+    if box and not box.get('visible', True):
+        return False
+
+    return True
+
+
+@dataclass
+class AriaTreeResult:
+    """
+    Result of aria tree generation.
+
+    Attributes:
+        snapshot: The accessibility tree snapshot
+        ref_map: Mapping from ref string to XPath, e.g., {'ref1': '/html/body/div[1]'}
+        method: Generation method used ('dom' or 'cdp')
+        yaml_str: Pre-generated YAML string (from JavaScript)
+    """
+    snapshot: AriaSnapshot
+    ref_map: Dict[str, str]
+    method: str
+    yaml_str: str = ''  # Pre-generated YAML from JavaScript
+
+    def to_dict(self) -> Dict:
+        """Convert to dictionary format."""
+        return {
+            'snapshot': self.snapshot,
+            'refMap': self.ref_map,
+            'method': self.method
+        }
+
+    def to_yaml(self) -> str:
+        """
+        Render an aria tree to YAML string.
+
+        Returns:
+            YAML string representation of the snapshot
+        """
+        # Use pre-generated YAML if available (from JavaScript)
+        return self.yaml_str
+
+    def to_json(self, compact: bool = False) -> str:
+        """
+        Render an aria tree to JSON string.
+
+        Args:
+            compact: If True, use compact JSON format (no indentation)
+
+        Returns:
+            JSON string representation of the snapshot
+        """
+        # Use the original structure directly, no simplification needed
+        if compact:
+            return json.dumps(self.snapshot['root'], separators=(',', ':'), ensure_ascii=False)
+        else:
+            return json.dumps(self.snapshot['root'], indent=2, ensure_ascii=False)
+
+    @staticmethod
+    def _normalize_whitespace(text: str) -> str:
+        """Normalize whitespace in text."""
+        if not text:
+            return ''
+        return ' '.join(text.split())
+
+    @staticmethod
+    def _escape_yaml(text: str) -> str:
+        """Escape text for YAML output."""
+        if not text:
+            return ''
+        text = text.replace('\\', '\\\\')
+        text = text.replace('"', '\\"')
+        return text
+
+class AriaTreeGenerator(ABC):
+    """Abstract base class for aria tree generators."""
+    
+    @abstractmethod
+    def generate(
+        self,
+        root_element: Any,
+        options: AriaTreeOptions
+    ) -> AriaTreeResult:
+        """
+        Generate an accessibility tree from a DOM element.
+        
+        Args:
+            root_element: Root DOM element to start from
+            options: Options for tree generation
+            
+        Returns:
+            AriaTreeResult containing snapshot, ref_map, and method
+        """
+        pass
+    

backend/daemon_server/browser/ariasnapshot/aria/generator_dom.py

@@ -0,0 +1,89 @@
+"""
+DOM-based Aria Tree Generator.
+Uses JavaScript injection to compute accessibility tree from DOM.
+"""
+
+from typing import Any, Dict, Optional
+
+from .base import AriaTreeGenerator, AriaTreeResult
+from .types import AriaTreeOptions, AriaSnapshot
+from backend.daemon_server.scripts.script_loader import ScriptLoader
+from webdriver_bidi.local_value import LocalValue as V
+
+ARIA_SNAPSHOT_SYMBOL_KEY = "stealth.ariaSnapshot.v1"
+
+
+class DOMAriaTreeGenerator(AriaTreeGenerator):
+    """
+    DOM-based accessibility tree generator.
+
+    Uses JavaScript to walk the DOM and compute accessibility properties.
+    Fast and works with any browser, but may miss some ARIA edge cases.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the DOM generator."""
+        self._tool: Optional[ScriptLoader] = None
+
+    def generate(
+        self,
+        root_element: Any,
+        options: AriaTreeOptions,
+        driver: Any = None
+    ) -> AriaTreeResult:
+        """
+        Generate an accessibility tree from a DOM element using JavaScript.
+
+        Args:
+            root_element: Root DOM element to start from (BiDiElement)
+            options: Options for tree generation
+            driver: BiDi-based driver instance (required)
+
+        Returns:
+            AriaTreeResult containing snapshot, ref_map, and method
+        """
+        if driver is None:
+            raise ValueError("driver must be provided to DOMAriaTreeGenerator.generate()")
+
+        # Prepare previousXpathToRef for stable refs (invert the map for O(1) lookup)
+        previous_ref_map = options.get('previous_ref_map')
+        previous_xpath_to_ref = None
+        if previous_ref_map:
+            previous_xpath_to_ref = {
+                xpath: ref for ref, xpath in previous_ref_map.items()
+            }
+
+        # Build options object (AI mode only)
+        ai_options = {
+            'depth': options.get('depth'),
+            'boxes': options.get('boxes', False),
+        }
+
+        # Use ScriptLoader to call the API
+        if self._tool is None:
+            self._tool = ScriptLoader(
+                driver,
+                ARIA_SNAPSHOT_SYMBOL_KEY,
+                'ariaSnapshot.js'
+            )
+
+        # Build BiDi LocalValue arguments explicitly
+        result = self._tool.call(
+            'generateAriaSnapshot',
+            V.element(root_element.shared_id),       # root element
+            V.from_value(ai_options),                # options dict
+            V.from_value(previous_xpath_to_ref),     # previousXpathToRef
+            V.boolean(True),                         # generate_yaml=True
+            return_value=True
+        )
+
+        # Extract snapshot, refMap, and YAML from JavaScript result
+        snapshot_dict = result.get('snapshot', result)
+        yaml_str = result.get('snapshot_yaml', '')
+
+        return AriaTreeResult(
+            snapshot=snapshot_dict,
+            ref_map=result.get('refMap', {}),
+            method='dom',
+            yaml_str=yaml_str
+        )

backend/daemon_server/browser/ariasnapshot/aria/types.py

@@ -0,0 +1,57 @@
+"""
+Copyright (c) Microsoft Corporation.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from enum import Enum
+from typing_extensions import TypedDict, NotRequired,Optional
+
+# Import auto-generated TypedDict types from TypeScript
+# These are automatically generated by: npm run build:types
+from .types_generated import (
+    ScrollInfo,
+    AriaBox,
+    AriaExtraProps,
+    AriaNode,
+    AriaTreeOptions as GeneratedAriaTreeOptions,
+    AriaTreeResult
+)
+
+# Re-export the generated types
+__all__ = [
+    'ScrollInfo', 'AriaBox', 'AriaExtraProps', 'AriaNode',
+    'AriaTreeOptions', 'AriaSnapshot', 'AriaTreeResult',
+]
+
+
+# Define AriaSnapshot (wrapper for root node)
+class AriaSnapshot(TypedDict):
+    """
+    Complete accessibility snapshot.
+
+    Structure: { root: AriaNode }
+    """
+    root: AriaNode
+
+
+# Extend AriaTreeOptions with additional Python-specific fields
+class AriaTreeOptions(GeneratedAriaTreeOptions, total=False):
+    """
+    Options for generating aria tree for AI/LLM consumption.
+
+    Extends the auto-generated AriaTreeOptions with Python-specific options.
+    """
+    ref_prefix: str
+    depth: Optional[int]
+    previous_ref_map: dict[str, str]

backend/daemon_server/browser/ariasnapshot/aria/types_generated.py

@@ -0,0 +1,60 @@
+from typing_extensions import Dict, List, Literal, NotRequired, TypedDict, Union
+
+class ScrollInfo(TypedDict):
+  scrollX: float
+  scrollY: float
+  scrollWidth: float
+  scrollHeight: float
+  clientWidth: float
+  clientHeight: float
+  scrollable: bool
+
+class AriaBox(TypedDict):
+  visible: bool
+  inline: bool
+  cursor: Union[None,str]
+  x: NotRequired[float]
+  y: NotRequired[float]
+  width: NotRequired[float]
+  height: NotRequired[float]
+
+class AriaExtraProps(TypedDict):
+  url: NotRequired[str]
+  placeholder: NotRequired[str]
+  src: NotRequired[str]
+  size: NotRequired[str]
+
+class AriaNode(TypedDict):
+  role: str
+  name: str
+  children: List[Union[str,'AriaNode']]
+  props: AriaExtraProps
+  box: AriaBox
+  receivesPointerEvents: bool
+  ref: NotRequired[str]
+  scroll: NotRequired[ScrollInfo]
+  active: NotRequired[bool]
+  checked: NotRequired[Union[Literal[False],Literal[True],Literal["mixed"]]]
+  disabled: NotRequired[bool]
+  expanded: NotRequired[bool]
+  level: NotRequired[float]
+  pressed: NotRequired[Union[Literal[False],Literal[True],Literal["mixed"]]]
+  selected: NotRequired[bool]
+  value: NotRequired[float]
+  min: NotRequired[float]
+  max: NotRequired[float]
+  modal: NotRequired[bool]
+
+class AriaTreeOptions(TypedDict):
+  refPrefix: NotRequired[str]
+  doNotRenderActive: NotRequired[bool]
+  depth: NotRequired[float]
+  boxes: NotRequired[bool]
+
+class Ts2Py_RiRAjt1ZVF(TypedDict):
+  root: AriaNode
+
+class AriaTreeResult(TypedDict):
+  snapshot: Ts2Py_RiRAjt1ZVF
+  refMap: Dict[str,str]
+  snapshot_yaml: NotRequired[str]