webtap-tool 0.11.0__py3-none-any.whl

webtap/services/setup/platform.py

@@ -0,0 +1,162 @@
+"""Platform detection and path management using platformdirs.
+
+PUBLIC API:
+  - get_platform_info: Get platform information dict with paths and Chrome location
+  - ensure_directories: Create required directories with proper permissions
+  - APP_NAME: Application name constant
+"""
+
+import platform
+import shutil
+from pathlib import Path
+from typing import Optional
+
+import platformdirs
+
+# Application constants
+APP_NAME = "webtap"
+APP_AUTHOR = "webtap"
+
+# Directory names
+BIN_DIR_NAME = ".local/bin"
+WRAPPER_NAME = "chrome-debug"
+TMP_RUNTIME_DIR = "/tmp"
+
+# Chrome executable names for Linux
+CHROME_NAMES_LINUX = [
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+]
+
+# Chrome paths for macOS
+CHROME_PATHS_MACOS = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "Applications/Google Chrome.app/Contents/MacOS/Google Chrome",  # Relative to home
+]
+
+# Chrome paths for Linux
+CHROME_PATHS_LINUX = [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+]
+
+# Platform identifiers
+PLATFORM_DARWIN = "Darwin"
+PLATFORM_LINUX = "Linux"
+
+# Application directories
+MACOS_APPLICATIONS_DIR = "Applications"
+LINUX_APPLICATIONS_DIR = ".local/share/applications"
+
+
+def get_platform_paths() -> dict[str, Path]:
+    """Get platform-appropriate paths using platformdirs.
+
+    Returns:
+        Dictionary of paths for config, data, cache, runtime, and state directories.
+    """
+    dirs = platformdirs.PlatformDirs(APP_NAME, APP_AUTHOR)
+
+    paths = {
+        "config_dir": Path(dirs.user_config_dir),  # ~/.config/webtap or ~/Library/Application Support/webtap
+        "data_dir": Path(dirs.user_data_dir),  # ~/.local/share/webtap or ~/Library/Application Support/webtap
+        "cache_dir": Path(dirs.user_cache_dir),  # ~/.cache/webtap or ~/Library/Caches/webtap
+        "state_dir": Path(dirs.user_state_dir),  # ~/.local/state/webtap or ~/Library/Application Support/webtap
+    }
+
+    # Runtime dir (not available on all platforms)
+    try:
+        paths["runtime_dir"] = Path(dirs.user_runtime_dir)
+    except AttributeError:
+        # Fallback for platforms without runtime dir
+        paths["runtime_dir"] = Path(TMP_RUNTIME_DIR) / APP_NAME
+
+    return paths
+
+
+def get_chrome_path() -> Optional[Path]:
+    """Find Chrome executable path for current platform.
+
+    Returns:
+        Path to Chrome executable or None if not found.
+    """
+    system = platform.system()
+
+    if system == PLATFORM_DARWIN:
+        # macOS standard locations
+        candidates = [
+            Path(CHROME_PATHS_MACOS[0]),
+            Path.home() / CHROME_PATHS_MACOS[1],
+        ]
+    elif system == PLATFORM_LINUX:
+        # Linux standard locations
+        candidates = [Path(p) for p in CHROME_PATHS_LINUX]
+    else:
+        return None
+
+    for path in candidates:
+        if path.exists():
+            return path
+
+    # Try to find in PATH
+    for name in CHROME_NAMES_LINUX:
+        if found := shutil.which(name):
+            return Path(found)
+
+    return None
+
+
+def get_platform_info() -> dict:
+    """Get comprehensive platform information.
+
+    Returns:
+        Dictionary with system info, paths, and capabilities.
+    """
+    system = platform.system()
+    paths = get_platform_paths()
+
+    # Unified paths for both platforms
+    paths["bin_dir"] = Path.home() / BIN_DIR_NAME  # User space, no sudo needed
+
+    # Platform-specific launcher locations
+    if system == PLATFORM_DARWIN:
+        paths["applications_dir"] = Path.home() / MACOS_APPLICATIONS_DIR
+    else:  # Linux
+        paths["applications_dir"] = Path.home() / LINUX_APPLICATIONS_DIR
+
+    chrome_path = get_chrome_path()
+
+    return {
+        "system": system.lower(),
+        "is_macos": system == PLATFORM_DARWIN,
+        "is_linux": system == PLATFORM_LINUX,
+        "paths": paths,
+        "chrome": {
+            "path": chrome_path,
+            "found": chrome_path is not None,
+            "wrapper_name": WRAPPER_NAME,
+        },
+        "capabilities": {
+            "desktop_files": system == PLATFORM_LINUX,
+            "app_bundles": system == PLATFORM_DARWIN,
+            "bindfs": system == PLATFORM_LINUX and shutil.which("bindfs") is not None,
+        },
+    }
+
+
+def ensure_directories() -> None:
+    """Ensure all required directories exist with proper permissions."""
+    paths = get_platform_paths()
+
+    for name, path in paths.items():
+        if name != "runtime_dir":  # Runtime dir is often system-managed
+            path.mkdir(parents=True, exist_ok=True, mode=0o755)
+
+    # Ensure bin directory exists
+    info = get_platform_info()
+    info["paths"]["bin_dir"].mkdir(parents=True, exist_ok=True, mode=0o755)

webtap/services/state_snapshot.py

@@ -0,0 +1,86 @@
+"""Immutable state snapshots for thread-safe SSE broadcasting."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class StateSnapshot:
+    """Immutable snapshot of WebTap state.
+
+    Frozen dataclass provides inherent thread safety - multiple threads can
+    read simultaneously without locks. Updated atomically when state changes.
+
+    Used by SSE broadcast to avoid lock contention between asyncio event loop
+    and background threads (WebSocket, disconnect handlers).
+
+    Attributes:
+        connected: Whether connected to Chrome page
+        page_id: Stable page identifier (empty if not connected)
+        page_title: Page title (empty if not connected)
+        page_url: Page URL (empty if not connected)
+        event_count: Total CDP events stored
+        fetch_enabled: Whether fetch interception is active
+        paused_count: Number of paused requests (if fetch enabled)
+        enabled_filters: Tuple of enabled filter category names
+        disabled_filters: Tuple of disabled filter category names
+        inspect_active: Whether element inspection mode is active
+        selections: Dict of selected elements (id -> element data)
+        prompt: Browser prompt text (unused, reserved)
+        pending_count: Number of pending element selections being processed
+        error_message: Current error message or None
+        error_timestamp: Error timestamp or None
+    """
+
+    # Connection state
+    connected: bool
+    page_id: str
+    page_title: str
+    page_url: str
+
+    # Event state
+    event_count: int
+
+    # Fetch interception state
+    fetch_enabled: bool
+    response_stage: bool
+    paused_count: int
+
+    # Filter state (immutable tuples)
+    enabled_filters: tuple[str, ...]
+    disabled_filters: tuple[str, ...]
+
+    # Browser/DOM state
+    inspect_active: bool
+    selections: dict[str, Any]  # Dict is mutable but replaced atomically
+    prompt: str
+    pending_count: int
+
+    # Error state
+    error_message: str | None
+    error_timestamp: float | None
+
+    @classmethod
+    def create_empty(cls) -> "StateSnapshot":
+        """Create empty snapshot for disconnected state."""
+        return cls(
+            connected=False,
+            page_id="",
+            page_title="",
+            page_url="",
+            event_count=0,
+            fetch_enabled=False,
+            response_stage=False,
+            paused_count=0,
+            enabled_filters=(),
+            disabled_filters=(),
+            inspect_active=False,
+            selections={},
+            prompt="",
+            pending_count=0,
+            error_message=None,
+            error_timestamp=None,
+        )
+
+
+__all__ = ["StateSnapshot"]